Foundry on Autri — Integration Scoping#

Status: Draft — grounded + decisions locked + red-teamed, pre blue-team. Created 2026-06-26 (Dan & Claude); grounded against the real Foundry + Autri repos and red-teamed 2026-06-29 (session 26, decisions D1–D7). This doc answers one question: what would it take, and what would it look like, to make Foundry a native authoring layer of Autri — the full conversion, broken into workable phases. Next step: blue-team → requirements contract (Phase 0).

TL;DR#

Autri today is read-mostly: ingest documents, chunk, embed, retrieve, inspect, ground an agent. Foundry is the missing write half: create, edit, version, annotate, and review documents with humans and AI together. The proposal is to make Foundry a first-party native authoring module on the Autri substrate, not a separate app and not dissolved into the core.

The thing that makes this safe rather than scope-creep is one distinction: share the substrate, not the surface. Autri's substrate (auth, MCP, multi-tenancy, storage, ingest, retrieve, document-write core) is shared. The user-facing surfaces stay focused — "Autri Read" (retrieval/inspector) and "Autri Author" (the Foundry layer) are distinct, separately-positioned capabilities on one backend. "Do one thing well" holds at the substrate; verticals and modules get to be richer.

Two decisions made in session 26 collapse the hard parts: (1) a document is an S3 object (Autri's existing model — the canonical source is the uploaded file, chunks are derived), which settles the long-standing git-vs-Postgres source-of-truth tension in Autri's favor; and (2) in-app document editing is versioned — every edit re-embeds only the changed sections and writes a version to a full changelog (doc edits + comments, together). Read-only uploaded docs stay unversioned (the session-25 punt, which is the right place for it); in-app-authored docs get real version history, which is itself a headline feature. Together these turn the "editable source of truth" piece into a deliberate, valuable versioning system built on the write + versioning substrate that already shipped.

Why this is worth doing#

• Compounding, not duplicating. Foundry currently runs its own auth (OAuth AS + GitHub IdP), its own search (Anvil), its own storage (SQLite), its own MCP server, its own content pipeline (git clone/pull/push). Autri has productized every one of those as multi-tenant infrastructure. Re-platforming stops the double-maintenance and lets the effort focus on the part that is actually Foundry: the authoring and review experience.
• The agentic-dev thesis needs all three organs. An agent's working memory needs to read context (retrieval — Autri today), write/update docs (editing — Foundry), and capture the why (annotations/review — Foundry). For "Autri for agentic software development," the authoring layer is a core organ, not a bolt-on. The dev-memory dogfood loop is the live proof-of-concept.
• Versioned authoring is a feature, not just plumbing. In-app editing with a full changelog of edits + review comments (D2) is a headline capability in its own right — the "what changed, who said what, and when" history that design docs and policies actually need. We want it regardless of the Foundry framing.
• Pricing lever. Authoring as a module is a natural tier/add-on on top of the read substrate, which serves the quality-per-dollar / margin north star.

Why it could be a trap (and the mitigations)#

• The risk is attention, not architecture. Autri is pre-launch with a signed Brehob deal. The mitigation is sequencing: do not build this on the critical path now; architect toward it and build when the core is launched. The Wave-2 document-write convergence (@autri/retrieval/documents.ts) plus the session-25 versioning lifecycle are already bricks one and two.
• Bundling the surfaces would muddy the pitch. "Makes any AI better without retraining" is crisp; "KB + editor + review + retrieval + MCP" is a platform pitch that is harder to sell. Mitigation: keep the surfaces and positioning separate even though the backend is shared.
• The new substrate work (versioned in-app editing) is real and load-bearing. The incremental-re-embed + section-level atomic versioning (D2) is genuinely new machinery, not a port. Mitigation: it is built in-house through the normal process (D7), sequenced after launch, with the atomicity design locked in the requirements contract before any build.

The architecture — substrate vs surface#

The cut that decides where anything belongs is one test: does it operate on Autri's core object (the document/KB), or on a domain object?

• QuoteAI operates on quotes — a domain object that references KB content. It is a vertical app: loosely coupled, sits on top, brings its own domain logic.
• Foundry operates on the document itself — creating, editing, versioning, annotating, reviewing the exact objects Autri stores and retrieves. That is not "on top." It is the substrate's primary object with a write/review surface, so it is a native module — more woven than a third-party app, less than dissolved-into-core.

Three tiers:

1. Autri core (substrate) — auth, MCP, multi-tenancy, storage, ingest, retrieve, document-write core. The thing you buy.
2. Foundry (authoring module) — editing, sections, annotations, review, versioning, optional GitHub sync. Turns read-mostly Autri into read-write. First-party, deeply integrated, optionally enabled (a tier).
3. Vertical apps (e.g. QuoteAI) — domain products on top, consuming substrate (and optionally the authoring module).

What Foundry is today (grounded audit)#

From a code audit of the Foundry repo (~/Documents/Code/foundry): ~13,900 LOC across ~138 files. Astro 6 + React 19 site (~3,900 LOC of components), Express + TypeScript API (~6,556 LOC), SQLite (better-sqlite3), Anvil semantic search (sqlite-vss + ONNX embeddings, OpenAI fallback), its own OAuth 2.0 AS (GitHub IdP, DCR, PKCE), a 25-tool MCP server over Streamable HTTP, git-backed markdown content (clone/pull/push), deployed as Docker on Fly.io. (The earlier draft said "18 tools / 6 service modules" — the real numbers are 25 tools and 8 service modules.)

The audit splits cleanly into two halves — the half Autri replaces, and the half that is the genuine Foundry value to port:

Gets replaced by the Autri substrate:

• SQLite storage → Autri Postgres (add annotation/review tables to Autri's schema).
• Foundry's own OAuth AS + GitHub IdP → Autri's MCP auth server (Cognito, DCR, PKCE) — same shape, already built and deployed (auth-server/).
• Anvil semantic search → Autri's hybrid retrieval (vector + FTS + section lookup) — strictly stronger than Anvil's semantic-only.
• Git-backed markdown files + the section parser → Autri's document/chunk model (already section-aware) on S3-backed source objects.
• .access.json prefix access control → dropped for v1 (D5). Foundry's public/private model is abandoned; all access control is handled at the Autri level (org → library → KB scope + Autri auth for contributors). Per-document visibility / anonymous-public reads can be revisited later if a real need appears.
• Fly.io single-node deploy → Autri's AWS infra.

Ports over (the actual value):

• The annotation domain model — threading (parent_id), statuses (draft/submitted/replied/resolved/orphaned), text-anchored, section-targeted. This is the core Foundry insight. (Note: its current heading_path + content_hash anchoring is the root of several open production bugs — see "Known authoring-tool issues.")
• The review batch model — collect annotations into reviews, submit in bulk; review lifecycle draft → submitted → complete.
• The 25-tool MCP authoring surface — the agent contract (list/create/edit/resolve annotations, reviews, get/create docs and sections, search, sync). Maps onto Autri service calls.
• The transport-agnostic service layer (~1,682 LOC across 8 modules: annotations, reviews, docs, pages, search, mgmt, context, errors) — takes an auth context, returns/throws domain types, with zero HTTP/SQL/filesystem types leaking into the domain logic. The domain logic + error contract port faithfully; note the rewire is a real re-implementation, not a drop-in (see Phase 1 / G4).
• The editing/review UI — annotation threads, inline comments, review submit, search modal, TOC. The valued UX features are mostly self-contained React; the framework-coupled part is the Astro SSR shell (see UI/UX).

What Autri already has that narrows the gap: the Source Legibility epic (migration 017) already stores a canonical per-page source string (pages.source_path) plus per-chunk character ranges (chunks.source_ranges) for converted docs (docx/xlsx/markdown). So text-anchored annotations have real stored coordinates to hang on today — Foundry's whole corpus is markdown, which rides exactly that path. Grounded (session 26): markdown sectioning is fine-grained per heading (A1, A1.1, A1.2), deterministic, and stable across re-ingest; the known section-coarsening bug affects PDFs, not markdown — so (section_id, char-range) annotation anchors are stable on markdown by construction.

Locked decisions (session 26)#

• D1 — A document is an S3 object. Follow Autri's existing model: the canonical, editable source of truth is the markdown object in S3; chunks are derived from it. Not git-as-source, not a new sections.source_text column. Editing produces new markdown, written back to S3; re-indexing derives from there. Git becomes an optional import/export bridge (Phase 5), never the source of truth. Resolves the doc's former central tension in Autri's favor and lets editing reuse the existing publish + versioning pipeline. Applies to both uploaded and in-app-authored docs.
• D2 — In-app document editing is versioned; edits re-embed only the changed sections. This is the deliberate build the red-team confirmed we want (not a deferred optimization). Read-only uploaded docs stay unversioned (the session-25 punt — correctly placed); in-app-authored docs get a full version history — a changelog of edits and review comments together. On save: write the new full markdown to S3 (mechanical), diff old-vs-new to find changed sections (mechanical), re-chunk + re-embed only the changed sections (semantic, surgical), recompute source_ranges for the whole doc (mechanical, no LLM). Atomicity is the keystone requirement (the red-team's central finding): the current substrate embeds whole-doc at finalize and a naive in-place section swap would leave a window where retrieval sees the section missing or un-embedded. So the incremental update must stage the changed section's new chunks + embeddings, then atomically flip section-level visibility — the chunk/section-level analog of the shipped whole-doc atomic flip (supersedeAndFlip + the superseded partial index). Building that section-granular stage-then-flip IS the versioning machinery. Unchanged sections keep their chunks and section_ids, so their annotations never move. Embodies "code does mechanics, AI does semantics."
• D3 — Foundry is a standalone, re-themed surface inside Autri, rebuilt native in Next.js. A sidebar entry ("Foundry") opening a standalone document authoring/review tool that matches Autri's styling and keeps Foundry's UX. Surface and stack both decided. The session-26 UI-coupling assessment confirmed the rebuild: ~80% of the UX value is in self-contained React 19 components (annotation threads, comment drafts, review submit, search, settings, TOC — ~3,800 LOC) that lift into Next.js with only data/auth/style swaps; ~20% is Astro shell (file routing, markdown SSR, nav generation — ~880 LOC) that gets rebuilt; a wholesale Astro sub-app "gains nothing" (duplicated chrome, no shared session, separate deploy) for similar effort. Rough size: ~2.5–3 weeks for one Next.js-capable engineer. The single largest rebuild cost is char-offset annotation anchoring — a remark/rehype pass that preserves source positions so a highlight maps to (chunk_id, char range) instead of Foundry's brittle quoted-text DOM search; new work regardless of stack, and exactly the fix for the orphaning-bug cluster (D4). The backend rewire to Autri's Postgres/S3/retrieval is identical regardless of stack — that is the real work.
• D4 — Fix-on-port, don't port the bug. Foundry's 15 open issues (especially the annotation-orphaning cluster, which stems directly from the fragile heading_path + content_hash + quoted_text anchoring) get fixed by the new section_id + char-range anchor model and D2's stable-chunk behavior, not faithfully reproduced. The list below is tracked as port acceptance criteria.
• D5 — Everything private for v1; Foundry's public/private model is abandoned. No per-document visibility, no anonymous-public reads. All access control lives at the Autri level (org → library → KB scope); adding a collaborator is an Autri auth / library-access action. This is a deliberate scope cut (Autri has no document-level ACL or unauthenticated read path today, and v1's use — dev-memory + work-team review — is authenticated anyway). Revisit per-doc visibility only if a real public-docs need appears.
• D6 — author_type (human vs AI) is derived at the surface boundary. user_id is solid in both contexts (Cognito sub in the web session and in the MCP token). The human/ai distinction has no auth signal (a connector could be an interactive client), so it is set by origin: web app = human, MCP = agent. Accepted as a heuristic for v1.
• D7 — Built in-house through the normal process. No external contributor on this; delivery runs through the hl/CSDLC pipeline (epic → red/blue-team → /hl:ship waves). The [substrate] / [app] tags below denote coupling/risk for sequencing, not an ownership handoff.

The source-of-truth model — a doc is an S3 object#

Foundry and Autri used to disagree about what a document is. Foundry: content is git-backed versioned markdown; the source of truth lives in a git repo, and Foundry is a view + annotation + review layer that pushes edits back to git. Autri: content is an ingested artifact — you upload a document, it gets parsed, chunked, embedded; the chunks are derived, not the editable source.

D1 settles this: Autri's model wins. The document is an S3 markdown object. The flow:

1. The editor produces markdown (a new doc, or an edit to an existing one).
2. The markdown is written to S3 as the document's canonical source object (documents.source_path is already exactly this — the uploaded source object key in the uploads bucket).
3. Ingestion derives chunks/embeddings/source_ranges from that object — for markdown, via the deterministic code route (no LLM), so section boundaries come straight from headings and are stable.
4. Retrieval, the inspector, the agent — everything downstream — consumes the derived index, unchanged.

Why this is the right call: it makes editing a re-publish of the canonical object rather than a bespoke new write path, it reuses the Wave-2 write core and the session-25 versioning lifecycle, and it keeps one source-of-truth story across the whole platform (uploaded docs and authored docs are the same kind of object). Git is demoted to an optional bridge — import a repo's markdown into S3-backed docs, and/or export S3-backed docs back to a repo — handled in Phase 5, never as the live source.

Open sub-question for the requirements contract: migrating Foundry's existing git-backed corpus into S3-backed Autri docs (one-time import) and re-anchoring its existing annotations from heading_path to section_id + char-range.

The editing & versioning model#

Building on D1 + D2. In-app-authored docs get a real version history; uploaded read-only docs do not (the session-25 punt, kept). This is the deliberate feature, and its hardest piece — keeping retrieval consistent through a partial update — is the keystone build.

On every save:

• Mechanics (code, cheap, deterministic): serialize the editor state to full markdown → write to S3 → diff against the prior markdown to identify changed sections (markdown headings make this a clean section diff) → recompute source_ranges for the whole doc (offsets shift downstream of an edit, but recomputing them is a pure pass, no model calls).
• Semantics (LLM/embeddings, kept surgical): only the changed sections re-chunk and re-embed. Unchanged sections keep their exact chunks, embeddings, IDs, and section_ids.

Atomicity — the keystone (red-team's central finding). Grounding showed the current substrate embeds whole-doc at finalize, chunk_index is document-global, and there is no chunk-level staging — so a naive in-place section swap (delete old chunks → insert new → embed asynchronously) leaves a window where retrieval returns the section missing or un-embedded, breaking the consistency guarantee the shipped whole-doc atomic flip provides. The build must therefore stage the changed section's new chunks + embeddings out of the live set, then flip section-level visibility atomically — the chunk/section-granular analog of supersedeAndFlip + the superseded partial index. Retrieval only ever sees the old section or the fully-embedded new one, never an in-between. This staging machinery is net-new and is precisely the versioning system, not overhead.

Versioning & changelog:

• Each save records a version that captures doc-state and comment-state together, producing a full edit + review changelog — "what changed, who commented, when."
• Explicit/named checkpoints can tag meaningful versions; these reuse the session-25 supersede/flip/preserve-all lifecycle (now extended to section granularity). An edit is an explicit version event, which fits the session-25 re-scope cleanly — no content auto-detection needed.

Annotation stability & re-anchoring (G6):

• Unchanged sections keep their chunks and section_ids, so annotations anchored to them never move.
• A comment lives on the version it was made against; on the next version it is carried forward to the edited section by best-effort fuzzy match into the new text, and flagged for review if its span no longer resolves. The changelog makes the original context recoverable.

Edges (for the requirements contract):

• Boundary changes — editing a heading that splits one section into two (or merges two) mints a new section_id; needs a defined chunk/annotation reassignment rule.
• Downstream offset shift — an early edit shifts char offsets for later chunks' source_ranges; the whole-doc range recompute handles it cheaply (mechanical), so "unchanged" chunks still get a metadata (not embedding) update.

UI/UX and the user experience#

Surface (D3): a new left-sidebar entry, "Foundry," opens a standalone document authoring/review tool inside Autri, re-themed to Autri's design system, keeping Foundry's UX. This is the literal embodiment of "share the substrate, not the surface" — a distinct surface on the shared backend.

Relationship to the inspector: Autri's existing document inspector is the retrieval/debug view of a doc (pages, chunks, bbox, traces, the source_ranges source pane). The Foundry surface is the authoring/review view of the same S3-backed doc. Two views, one object. The inspector's existing source pane (which already renders the canonical per-page source with char ranges) is the proof that the anchoring coordinates exist; the Foundry surface renders that same source for editing + annotation.

Two roles, one surface:

• Reviewer (no editing required): open a doc, highlight text in the source view, leave a threaded comment, batch comments into a review, submit. This works on read-only ingested docs — it needs nothing beyond the annotation/review port and the source_ranges that already exist. It is the cheapest, highest-frequency value (the dev-memory + work-team review loop).
• Author: edit a section inline → save → versioned incremental re-embed (D2) → see "saving / re-indexing" then the updated doc; browse the version history / changelog (edits + comments over time); resolve annotations.

Anchor model (replaces Foundry's fragile one): annotations anchor to (section_id, char_start, char_end) into the section's canonical source, plus a snapshot of the quoted text for display and best-effort recovery. Section_id is heading-derived and stable for markdown across re-ingest; char ranges come from source_ranges. This structurally avoids the heading_path-substring-match orphaning that plagues Foundry today.

Identity & access: authorship uses Autri's user_id (Cognito sub); author_type is web=human / MCP=agent (D6). Everything is private and Autri-auth-scoped (D5) — adding a collaborator is an Autri library-access action, not a per-doc ACL.

Positioning & tiering: "Autri Read" (inspect/retrieve) vs "Autri Author" (the Foundry layer), one backend. Author is a tier/add-on, or bundled into a vertical framing like "Autri for agentic dev." Exact packaging is an open question for the requirements contract.

Latency UX: re-embed is async through the worker today; the editing experience needs explicit "saving / re-indexing" states, or a faster synchronous single-section re-embed path. Defining the target (how fast must a save feel) is an open question.

Scope of work — the full conversion, phased#

Blue-team locked the v1 scope (session 26) — see the requirements contract projects/autri/requirements/foundry-integration, which is authoritative on scope. v1 = the full read-write loop on markdown (Phases 0–3) + a curated MCP authoring surface built behind a local tool-testing harness (Phase 4, pulled into v1) + a one-time docs→S3 migration; GitHub (Phase 5) is dropped entirely. The phases below are the design map; the contract makes the in/out calls.

The complete conversion, dependency-ordered into workable chunks, built in-house through the normal process (D7). Tags: [substrate] core plumbing; [app] loosely-coupled surface — coupling/risk markers for sequencing, not ownership. Phasing is ordering, with the cheap/near-term value first and the harder/gated build later.

• Phase 0 — Lock the design. Blue-team this doc into a requirements contract (done — see above). Lock the section-level atomic stage-then-flip mechanism (the D2 keystone), and decide the changelog/snapshot UX, the latency target, the existing-corpus migration + annotation policy, and the cutover plan. Output: the scope contract everything else is graded against.
• Phase 1 — Annotation + review domain on Autri (read-only docs) [substrate]. Re-implement Foundry's 8-module service layer + annotation/review schema on Autri's Postgres + the Cognito/MCP auth context — a faithful async re-implementation (Autri is async pg + S3, not Foundry's sync SQLite + filesystem; signatures and transactions change), keeping the proven domain logic + error contract. New anchor model (section_id + char-range via source_ranges); author_type at the boundary (D6); everything private (D5). No editing yet — this delivers review on already-ingested docs, the near-term value, lower-ambiguity.
• Phase 2 — Authoring/review UI on Autri [app]. The standalone re-themed "Foundry" surface, rebuilt native in Next.js (D3) against the Phase-1 API: lift the ~3,800 LOC of portable React components, rebuild the ~880 LOC Astro shell, build the char-offset annotation renderer. Ship the edit-free reviewer experience first (highlight → comment → batch → submit), then layer the author + changelog affordances. Visual, testable, contract-bounded (~2.5–3 weeks of focused build).
• Phase 3 — Editable source of truth + in-app versioning (doc = S3 object) [substrate]. The deliberate D2 build: in-app markdown editing → re-publish to S3 → incremental section re-embed with section-level atomic stage-then-flip → a full edit + comment changelog. The keystone substrate work (the per-section re-chunk/re-embed + atomic visibility flip does not exist today and is the core of this phase). Markdown's deterministic, stable sectioning makes this tractable; non-markdown editability would depend on the segmenter stabilizing (Track 1).
• Phase 4 — Curated MCP authoring surface + tool harness [substrate/app] (in v1). A curated MCP authoring toolset (document edit + annotate/review), reusing the Wave-2 write authz and fixing the known issues (D4) rather than porting them. Built behind a local testing harness that exercises the tool surface against real authoring tasks, optimizes the toolset, and irons out bugs before any prod ship. Local + no prod dependency, so it can start early / run in parallel and feed tool-shape decisions back into Phase 1. This is what makes agent-driven authoring (the dev-memory loop, the /ship spec hand-off) work on the new substrate.
• Phase 5 — Content/GitHub bridge — DROPPED (blue-team). No git relationship at all. The one-time existing-corpus import (Foundry markdown → S3) lives with the migration workstream (requirements M7), not as a git bridge.

Cross-track dependency: Phase 3 (and stable annotation anchoring for non-markdown docs) leans on the in-flight segmenter work (ingestion/units.ts detectAnchor, Track 1). Markdown docs are unaffected (deterministic code-route sectioning, grounded session 26), which is why markdown-first is the right entry.

Known authoring-tool issues (fix-on-port)#

Foundry's 15 open GitHub issues, tracked as port acceptance criteria (D4). The standout cluster is annotation anchoring — the same fragility this design replaces, already biting in production.

Annotation anchoring (root-cause fixed by the new anchor model + D2 stable chunks):

• #163 — annotations created via MCP tools always appear orphaned/stale in the UI.
• #161 — MCP annotations flip to orphaned seconds later; client-side drift detection fails a substring check when quoted_text contains markdown syntax.
• #127 — heading_path picks the wrong section for highlighted text.
• #135 — list_annotations doesn't surface nested replies.

get_page / section structure (resolved by Autri's section model):

• #123 — get_page returns inconsistent section structure via Anvil chunking.
• #136 — get_page response too large for tool-output limits on big docs.
• #137 — heading_path format ambiguous in tool descriptions.
• #118 — feature: add a heading-tree-only mode to get_page.

Tool correctness (re-implement clean):

• #120 — create_doc template 'epic' not found.
• #102 — insert_section level required param dropped by client schema cache.
• #129 — 8 pre-existing API test failures in reviews/annotations/search.
• (plus the dev-memory-logged grouping-header duplication on update_section for docs with empty grouping H2s.)

Sync / destructive (addressed in Phase 5):

• #111 — sync_to_github silently flattens + force-overwrites the target repo layout.

Auth / infra (subsumed by Autri's auth server / dropped under D5):

• #166 — CORS integration test for MCP + OAuth endpoints.
• #165 — design revision: drop DCR bearer gate (or replace with origin-based trust).

UI (Phase 2 polish):

• #126 — review panel drag-to-resize width with persistence.

Build approach#

Built in-house through the normal hl/CSDLC process (D7): each phase is scoped as an epic, red/blue-teamed into a requirements contract, then shipped via /hl:ship waves with the standard QA gates. No external contributor is in the plan; the [substrate]/[app] tags are sequencing/risk markers. The attention cost is Dan's review/direction bandwidth, mitigated by keeping the work off the critical path until Brehob + launch are done and by locking the D2 atomicity design before any Phase-3 build.

Open questions (for the requirements contract)#

The source-of-truth model (D1), the edit/versioning model (D2), the UI stack (D3), visibility (D5), author_type (D6), and the build approach (D7) are decided and out of scope for re-litigation. What remains:

• The section-level atomic stage-then-flip mechanism (Phase-3 keystone): granularity (per-chunk vs per-section), and exactly how it extends the shipped whole-doc superseded flag + supersedeAndFlip to keep a partial update atomic. The single highest-risk design item.
• Changelog / snapshot UX: how versions are presented, how doc-state + comment-state are shown together, what an explicit "named version" looks like vs every-save history.
• Edited-section re-anchoring details: the fuzzy carry-forward + flag-for-review policy (G6) — thresholds and the reviewer affordance.
• Boundary changes (split/merge): the chunk/annotation reassignment rule when a heading edit changes section structure.
• Latency target + sync vs async re-embed: how fast a save must feel; whether a synchronous single-section re-embed path is needed.
• Existing-corpus migration: one-time import of Foundry's git-backed markdown into S3-backed Autri docs, and re-anchoring existing annotations (heading_path → section_id + char-range). Effort + fidelity.
• Tiering/packaging: "Autri Author" as a separate plan, an add-on, or bundled into a vertical (e.g. "Autri for agentic dev").
• Standalone-surface deployment shape: a route inside the Next.js app vs. a separate sub-app; how it shares Autri's auth/session.
• PDF / non-markdown docs: editing is markdown-first; what is the story for annotate-only on PDFs (bbox anchors, no char source).
• Coexistence / cutover: does the existing Foundry deployment keep running standalone during migration (no big-bang cutover), and for how long.
• Real-time collaboration: multiple concurrent editors/reviewers — in scope for v1 or explicitly deferred.

Recommendation#

Lock the architecture as a native authoring module on the Autri substrate (share the substrate, not the surface), with D1 (doc = S3 object) and D2 (versioned in-app editing via incremental section re-embed + section-level atomic stage-then-flip + a full edit/comment changelog) as the spine, and decisions D3–D7 set. Run blue-team → requirements contract (Phase 0) next — it locks the D2 atomicity mechanism (the one high-risk design item) and produces the spec the build is graded against. Do not put the build on the critical path before Brehob + launch — but the substrate is already shaped (Wave-2 write core + session-25 versioning lifecycle + source_ranges), so this stays a natural extension rather than a rewrite, built in-house through the normal process.