V2 direction — summary of locked and leaning-locked decisions

Status: directional summary — pre-implementation Date: 2026-05-30 Scope: v2 = a new repo intended to escape writing-system drift, host on Cloudflare, adopt-over-build for libraries.

---

v1 / v2 terminology

• v1 = this repo (writing-system) — what we're trying to escape from
• v2 = the new repo, curated take-list + Cloudflare stack + adopted libraries

---

Locked decisions

Hosting

Cloudflare end-to-end. Specifically:

Database

Postgres on Neon via Hyperdrive — clean break from Supabase. Cloudflare doesn't host Postgres natively; D1 (SQLite) doesn't fit because of pgvector + planned graph layer.

Auth

better-auth on Workers — replaces Supabase Auth. Battle-tested CF integration with D1 / Postgres / Drizzle support.

Editor substrate

Tiptap / ProseMirror family (BlockNote is the strongest candidate within that family because it provides block-with-stable-id natively — exactly what the locked book-editor schema needs). Final pick — BlockNote vs Tiptap-with-own-shell — not closed.

Agent / memory / retrieval

Adopt-over-build for the intelligence layer. RAG is not a project; the memory system is the architectural choice.

• Memory system = Zep / Graphiti — temporal knowledge graph + vector + bi-temporal facts. Benchmark-backed advantage on temporal reasoning (63.8% vs Mem0's 49.0% on LongMemEval, GPT-4o). Handles both the book-continuity scenario and the policy-doc supersession scenario.
• Long-context fallback — for docs under ~500k accumulated tokens, Claude Opus 4.7's 1M-token flat-priced context can replace the retrieval layer entirely. Skip the memory system when it fits.
• No custom RAPTOR build. v1 memory said "custom RAPTOR-style tree" — that was a plan, not code. Nothing was built. v2 adopts Zep + LlamaIndex methods inside it instead.

Take-list (what crosses from v1 to v2)

Four buckets only. Nothing else.

1. Schema state — pg_dump -s against live Postgres → single 0001_initial.sql in v2. No migration history transfers — that's drift.
2. The 60 routed pages + their transitive component closure (only what they import).
3. chattr + kai-ai integration shape (decision below on whether chattr stays in the harness or is dropped).
4. Surviving BlockData workbench React patterns (only what the 60 routed pages actually use).

Explicitly excluded from v2:

• All 183 v1 migration files (history is drift)
• The 90 unrouted page files
• nonactive-files/ (agchain archive)
• _research/ tree
• __references/ clones
• apps/devdocs/content/internal/done/ (already deleted in v1 this pass)
• Supabase edge functions
• Cloud Run deploy scaffolding
• The unrouted agchain_*.py route files
• Buddy-era runtime docs

Drift discipline

• A keep.txt (transitively-derived from the 60 routed pages) is the closed list. Files not on the list cannot enter v2.
• Per-package LICENSE files in v2. Per-package licensing is supported, not monolithic.
• Documentation lives only in apps/devdocs/content/. No drifting docs created elsewhere.

---

Service inventory (Cloudflare side)

Already provisioned on the writing-system Cloudflare account (c3815704e2ffdecd4ef75409036420e4):

• R2 bucket writing-system-prod
• Cloudflare Secrets Store (default_secrets_store)
• Cloudflared tunnel for local dev
• secrets/dev/cloudflare.yaml SOPS file with CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, TUNNEL_TOKEN
• cloudflare:whoami / cloudflare:secrets-store:* scripts wired through SOPS+age

Not yet provisioned and needed for v2:

• Cloudflare Containers project (for FastAPI)
• Cloudflare Pages project (for web)
• Workers project (for edge / Hono / auth)
• Hyperdrive binding (for Postgres pooling)
• Vectorize index
• Neon Postgres account + project

---

Open forks (not yet closed)

1. Editor: BlockNote vs Tiptap-with-own-shell. Both ProseMirror-based; BlockNote gives block-with-stable-id natively.
2. chattr's role. Locked v1 memory says "chattr + kai-ai is the agent harness." User opened the door to: keep chattr Python as an HTTP-callable service, swap harness for Mastra (TS, MIT, adopt-not-build). Not yet pinned.
3. kai-ai language. Greenfield enough to choose TS or Python. Depends on the harness decision above.
4. Apache AGE vs ArangoDB vs Zep-only for the KG. Zep covers the temporal-KG slot for v2 MVP; AGE/ArangoDB only enter if Zep's graph proves insufficient. Defer.
5. v2 repo name. "writing-system-v2" is placeholder. May ship under a different product name.

---

What was rejected this pass

• Cloud Run as production target — Phase 2 was in progress in v1 but never used; v2 skips entirely
• Supabase as Postgres host (clean break preferred); Supabase-as-DB-only was the fallback if migration friction blocked Neon
• Custom RAPTOR build — was a plan in v1 memory; v2 adopts Zep
• Pure RAG as an architectural project — RAG is a primitive inside memory systems; not the unit of decision
• D1 for primary DB — SQLite + 10GB cap doesn't fit pgvector + planned graph workload
• Rewrite API to TS as the way to get Cloudflare-native — Cloudflare Containers solves the Python-on-CF problem without the rewrite; option only reopens if chattr+kai-ai are also moved to TS

---

Where this aligns with prior locked direction

• [project-long-doc-editor-direction] book editorial OS framing survives. Editor + intelligence layer + revision-proposal layer + editorial agents still the model.
• [feedback-no-license-blockers] AGPL/copyleft is not a gating concern. License is a separate workstream.
• [feedback-edge-functions] distancing from Supabase edge functions consistent with the Workers-edge plan.
• [project-jon-buddy-role-split] Buddy archived; jon-local Docker is the local-stack reality; no Buddy hosts in v2.