Agent guidance rewritten and the prisma-8 branch integrated to main

[borisno2]

Parent

#1129 — build spec 9 of the Prisma 8 architecture spec. Lands on the prisma-8 integration branch, not main.

What to build

The root, core and auth agent-guidance files describe the Prisma 8 architecture — generator, the two surfaces, transactions and errors, the dev loop, auth — with no reference to PSL, prismaClientConstructor, extendPrismaSchema, SQLite, join-table naming or P#### codes, keeping public-API docblocks and pointing rationale at the ADRs; migration-guide references to the fragment API are removed; then the prisma-8 integration branch is merged to main with every package suite, every example and every e2e job green.

Acceptance criteria

• No deleted construct is named in any of the three guidance files except as a historical pointer to an ADR
• The full CI matrix is green on the integration branch before merge, and on main after
• The architecture spec's consumer-impact section is re-read against the merged tree and any remaining item is filed as an issue rather than left implicit

Blocked by

• Blog, custom-field, composable-dashboard, auth-demo and mcp-demo converted #1171
• Tiptap, file-upload, JSON and plain-CSS-theming examples converted #1172
• Both RAG examples converted with embeddings regenerated #1173
• The documentation site rewritten for Prisma 8, with the costs placed where users meet them #1174

---

Generated by Claude Code

[borisno2]

Before this integration PR: #1178 lists the CI gates (test/test:coverage duplication and the e2e base_ref == 'main' gate added in #1177) that must be removed here, and the auth e2e guards that must be re-keyed off the SQLite adapter so the required e2e check does not pass by skipping.

[borisno2]

Changeset policy for the integration branch, as run by /deliver-prd on 2026-09-03: every ticket's changeset on prisma-8 is minor (or patch) per the pr-changeset rule that major needs an explicit request. Several of them remove public config keys (#1132: prismaClientConstructor, extendPrismaSchema, joinTableNaming, db.relationName, index sort; #1130: SQLite and Prisma 7). Before this PR merges to main, decide the aggregate bump — almost certainly major with a migration guide — and consolidate the branch's changesets accordingly.

[borisno2]

Two facts for whoever picks this up, found while delivering #1170 (2026-09-09):

ADR-0066 is claimed twice. main has docs/adr/0066-the-hook-bound-context-is-the-same-secured-context-as-a-transactions.md; prisma-8 has docs/adr/0066-a-plugins-write-of-its-own-column-runs-no-hook.md. The duplicate-number check (#1114) will fail the prisma-8 → main release PR. Renumber the prisma-8 one (and every reference to it — packages/core/CLAUDE.md, the spec, changesets) when main is merged into prisma-8 ahead of the release PR. prisma-8 claims 0067 on #1375, so the next free number after both branches merge is 0068.

prisma-8 is 25 commits behind main as of the GitHub compare on 2026-09-09 (merge base 93a3736, 58 ahead). Merge main into prisma-8 as part of this ticket, before the release PR, and treat that merge as a review surface: the same shared context types have been appended on both sides more than once during this build.

---

🤖 Generated with Claude Code

[borisno2]

Two concrete divergences for this ticket, found by the review of PR #1379 (2026-09-10) while checking the
documentation against the code. Both are in files this ticket owns, so they are recorded here rather than fixed there.

The root CLAUDE.md still shows the stale row-lock form. Its interactive-transaction example reads the capacity
threshold off the locked row, whose columns are the row as of before the lock. The correct form re-reads the parent
in its own statement after taking the lock, which is what packages/core/src/secured/capacity-gate.test.ts does and
what the rewritten documentation now shows. As written, the guidance demonstrates precisely the staleness the row
lock exists to prevent, and it is the copy an agent reads first.

A three-way disagreement about db.indexes and sort. The code, the documentation and CLAUDE.md did not
agree on whether a generate-time check refuses a sort direction on an index entry. The documentation was corrected
against the code on #1379. Re-check CLAUDE.md's account when rewriting it, and take the code as the truth.

Worth generalising while this ticket is open: the review found several documentation claims that no grep would
catch, because the defect was a fabricated API — an option, type or prop that reads plausibly and does not exist.
The method that caught them was enumerating the real exported surface from the built .d.ts files and diffing the
documented names against it. The three guidance files this ticket rewrites deserve the same treatment rather than a
spelling sweep.

---

🤖 Generated with Claude Code

[borisno2]

Three more concrete divergences in the files this ticket owns, found by the stronger sweeps on PR #1379 (2026-09-10). Each was found by resolving the documented name against the packages' real exported surface, not by a spelling search — every one of these names reads as plausible and none exists.

• packages/cli/CLAUDE.md:175 imports createContext from @opensaas/stack-core. There is no such export.
• packages/tiptap/CLAUDE.md:282 imports from @opensaas/stack-tiptap/components. That is not an exported subpath.
• packages/core/CLAUDE.md:53 names OperationAccessControl, which exists nowhere under packages/*/src.

Also, adding to the note above about the sort claim: the root CLAUDE.md does not merely disagree with the code, it documents the { field: 'createdAt', sort: 'desc' } form as working and shows the Prisma index it supposedly emits. No sort key is read anywhere. The source's own TSDoc carries a third, different version of the claim and is filed separately.

Method note for this ticket. The sweep that found these walked 40 export subpaths' type declarations with the TypeScript checker, collected 809 exported names, and diffed 759 documented bindings against them. It found nothing further in the documentation site or the package READMEs, and three hits in the CLAUDE.md files — which is to say the guidance files are now the least verified surface in the repo, because nothing compiles them and no sweep had been run over them. Run that diff over all three guidance files as part of this ticket rather than trusting a read-through.

🤖 Generated with Claude Code