Spec: Examples, scaffolder, docs and agent guidance on Prisma 8

[borisno2]

Build spec 9 of 9 derived from the Prisma 8 architecture spec (sections 11 and 14, phase 9). It gathers the consumer sweep the map accumulated across every record; this issue restates no decision.

Problem Statement

Twelve database-backed examples, the scaffolder's templates, the documentation site and both agent-guidance files describe and exercise the Prisma 7 stack: SQLite databases, findMany call sites, nested writes, prismaClientConstructor, extendPrismaSchema, a Serializable transaction example, a P2034 retry loop, a synchronous-client recipe over a generated client, and a deploy guide pinning a file tree that no longer exists. Until they move, a user following any of them builds against an API that does not exist, and an AI agent reading the guidance does the same.

Solution

Every example converts to Postgres under opensaas dev on the query-value surface with reseeded data; the scaffolder templates convert with the two examples they copy from; the documentation site's reference, how-to and deploy pages describe the Prisma 8 surfaces using the glossary's terms; and both agent-guidance files are rewritten so an agent reads the real architecture. The costs taken knowingly are stated where a user will meet them.

User Stories

1. As an app developer, I want every example to run with pnpm dev on a fresh clone, so that I can learn from a working project.
2. As an app developer, I want every example's context.db call site on the query-value surface with PascalCase keys, so that the code I copy compiles.
3. As an app developer, I want every example's relationship write spelled as connect on the owning side or a junction-row create, so that no example teaches a deleted construct.
4. As an app developer, I want every example's post.author-style read handling null, so that the example is honest about access control.
5. As an app developer, I want every example's seed to reseed under uuid7 ids, so that no seed depends on a stable id.
6. As an app developer, I want the two RAG examples to regenerate their embeddings on seed, so that no JSON-to-vector conversion is pretended.
7. As an app developer, I want the theming example to keep working with no database, so that a non-database example still demonstrates the query surface and field builders.
8. As an app developer, I want pnpm create opensaas-app to scaffold a project that is dev-ready with no --db flag, so that the scaffold matches the one provider.
9. As an app developer, I want the context API reference to document the secured surface's read and write subsets, the Where vocabulary, denial values and materialisation, so that I know what the surface offers before I reach for the bypass.
10. As an app developer, I want the reference's bypass section to be the Unsafe surface's SQL recipe with its cost list, so that I know exactly what I give up.
11. As an app developer, I want the interactive-transaction guidance to show the row-lock capacity gate, so that I never look for an isolation level.
12. As an app developer, I want the deploy guide to describe db migrate from the committed migrations directory, the extension privilege beside the Database escape, and no file-tracing pin, so that a deploy follows the real workflow.
13. As an app developer, I want the plugin how-to's raw-SQL placeholder rewritten against the Unsafe surface, so that a plugin author is not taught a deleted call.
14. As an app developer, I want the config reference to document db.idField, db.extensions, db.client, db.provider, db.indexes without sort, typed referential actions, the temporal timestamps and the junction-list pattern, so that every config key has a page.
15. As an app developer, I want the synchronous-client recipe rewritten around db.client.pg and the JSON import, so that a module-init consumer has a working pattern.
16. As an app developer, I want the field-type documentation to describe the replaced builder contract and needs on columns, so that a custom field author has the real interface.
17. As an app developer, I want the documented costs — application-side updatedAt, the needs leak channel, the untyped-hook silent break, result-size memory, two-round-trip locks, case-insensitive filters, HNSW approximation — stated where I will meet them, so that none is discovered as a bug.
18. As an AI coding agent, I want the root guidance to describe the Prisma 8 architecture — generator, surfaces, transactions, errors, dev loop, auth — with no reference to PSL, prismaClientConstructor, extendPrismaSchema, SQLite, join-table naming or P#### codes, so that I never implement against a deleted API.
19. As an AI coding agent, I want the core and auth package guidance rewritten likewise, so that package-level advice agrees with the root.
20. As a stack maintainer, I want the migration-guide references to the fragment API removed, so that no doc points at a deleted export.
21. As a stack maintainer, I want the e2e suites green on the converted starter-auth example, so that the flagship flows are proven end to end.

Implementation Decisions

• Examples: all twelve database-backed examples convert (the set is not cut); each declares Postgres, uses opensaas dev, and reseeds; both RAG examples declare pgvector through the plugin and regenerate embeddings; the composable-dashboard posts page is already inside the vocabulary and is verified rather than rewritten; the theming example converts for the query surface and field builders only.
• Scaffolder: templates are build-time copies of the starter and starter-auth examples and convert with them; the --db flag and its helper are gone (spec 1); the post-step is generate only (spec 5).
• Docs site: the context-API, config-API, field-types, RAG, plugin, transaction and deploy pages rewritten in the glossary's terms; every page names its Concepts term where one exists. Diátaxis quadrants respected.
• Agent guidance: the root, core and auth guidance files rewritten against the architecture spec, keeping public-API docblocks and removing rationale that belongs in the ADRs.
• Costs from the architecture spec's section 14 are placed on the page where the relevant feature is documented, not on a separate caveats page.

Testing Decisions

• A good test for an example is the example running: generate, dev, seed, and its own test script or e2e suite passing on the Dev database and on CI's container.
• Examples: each example's existing test script (where one exists) rewritten to the new surface and run in CI; the starter-auth e2e suite including the plain-Node anchor; the nightly cold-clone job over the scaffolder.
• Docs: every code block in the reference and how-to pages type-checks against the real packages where the docs build already does so; a P#### grep over docs; a link check.
• Prior art: the blog example's access-control test script; the existing e2e suites; the existing docs build.

Out of Scope

Any package code change (specs 1–8); the Keystone-migration plugin and its skills (out of scope for the whole effort); the public site's narrative landing (unchanged).

Further Notes

Blocked by specs 5, 7 and 8 — the last spec, since examples need everything. The costs list in the architecture spec is the checklist for story 17.

Build specs

The nine build specs, in dependency order. Native blocking edges are set on each issue.

1. Spec: Contract generation — the generator emits a Contract module, Contract artifacts and the Generated bundle #1121 — no blockers
2. Spec: Runtime boundary — client construction, the Engine stamp, the Unsafe surface and the Test context #1122 — blocked by Spec: Contract generation — the generator emits a Contract module, Contract artifacts and the Generated bundle #1121
3. Spec: The secured surface, reads — query-value context.db, the Where vocabulary and the two-phase read #1123 — blocked by Spec: Runtime boundary — client construction, the Engine stamp, the Unsafe surface and the Test context #1122
4. Spec: The secured surface, writes — connect, transactions, the row lock and stack-owned errors #1124 — blocked by Spec: The secured surface, reads — query-value context.db, the Where vocabulary and the two-phase read #1123
5. Spec: Dev loop and migration workflow — opensaas dev, the Dev database and production migrate #1125 — blocked by Spec: Contract generation — the generator emits a Contract module, Contract artifacts and the Generated bundle #1121, Spec: Runtime boundary — client construction, the Engine stamp, the Unsafe surface and the Test context #1122
6. Spec: The Auth adapter — better-auth over the Unsafe surface #1126 — blocked by Spec: Contract generation — the generator emits a Contract module, Contract artifacts and the Generated bundle #1121, Spec: Runtime boundary — client construction, the Engine stamp, the Unsafe surface and the Test context #1122
7. Spec: MCP and the admin UI on the secured surface #1127 — blocked by Spec: The secured surface, reads — query-value context.db, the Where vocabulary and the two-phase read #1123, Spec: The secured surface, writes — connect, transactions, the row lock and stack-owned errors #1124
8. Spec: Third-party field packages — RAG's native vector column, storage and tiptap on the new builder contract #1128 — blocked by Spec: Contract generation — the generator emits a Contract module, Contract artifacts and the Generated bundle #1121, Spec: The secured surface, reads — query-value context.db, the Where vocabulary and the two-phase read #1123
9. Spec: Examples, scaffolder, docs and agent guidance on Prisma 8 #1129 (this issue) — blocked by Spec: Dev loop and migration workflow — opensaas dev, the Dev database and production migrate #1125, Spec: MCP and the admin UI on the secured surface #1127, Spec: Third-party field packages — RAG's native vector column, storage and tiptap on the new builder contract #1128

---

Generated by Claude Code