DocAtlas independent Grounded Web workspace instructions

These rules apply to the independent web/ application in the official Harness integration checkout. Its TypeScript Core lives in packages/core/; Python is the local document sidecar. The original repository-root Python CLI/package/lock is independent and must not change as a side effect of Web work. Original video and sibling research checkouts, and every .sources/ checkout, are read-only inputs unless the user explicitly requests changes there. Historical DSH rules below describe compatibility boundaries, not a requirement to import that host. migration-source.json preserves the original migration provenance; later reviewed changes belong in this repository's Git history and audit notes.

Environment

• JavaScript uses Node 22.19.0 and pnpm 11.7.0 exactly. Run pnpm through scripts/pnpmw so the local pinned Node fallback is used when necessary.
• Python uses CPython 3.12.12 and uv 0.9.21 exclusively. Do not invoke pip, Poetry, Conda, or a system Python directly.
• Keep pnpm-lock.yaml and uv.lock synchronized with their manifests. CI and local verification use frozen/locked installs.
• The Azure Luna smoke uses a short-lived token from az account get-access-token; never print, persist, or commit that token. It is an opt-in network test and does not run in CI.

Architecture invariants

• ADR-021 supersedes the DSH-first target architecture. DocAtlas owns the product, application orchestration, domain truth, policy, and Web experience; Pi is its embedded Agent execution engine, not the product owner. Using Pi hooks internally does not make DocAtlas merely an optional extension.
• Preserve Pi's native tools, trusted resources, models, session branching, compaction, steering, cancellation, and extension capabilities. Do not reuse the legacy document-only DSH preset as the Pi baseline or overwrite Pi tool names with DocAtlas tools.
• The existing DSH implementation remains a buildable legacy baseline until migration gates pass. plugins/docatlas-dsh still uses package.json#dsh and cordis.patch.yml; do not add a Codex plugin manifest or dsh.plugin.json.
• Pi-specific code belongs in packages/runtime-pi; domain code belongs in packages/core. Core must not depend on Pi, DSH, React, or a host plugin. apps/web retains the interaction prototype beside an internal paired live client; runtime-pi has SDK composition/dispatch/checkpoints, and server has control storage, scheduling, scoped execution and HTTP/auth/SSE. Full execution/recovery boundaries, shared Reader and product deployment remain pending. Do not present the demo or internal tests as a deployed Pi product. The Pi npm patch is fingerprinted in compat/pi/patch-baseline.json; review any change and preserve native behavior.
• ADR-022 puts D0 prototype/UX review before large runtime/Core migration. Prototype answers/progress must be labeled simulated; local PDF bytes stay in the browser. Demo state is temporary, not a production wire/Memory implementation. The supported preview is authenticated and loopback-only, serving built fixture assets, never the workspace filesystem.
• Python is a document sidecar only. It must not own a second Agent Loop, conversation history, or model credentials.
• Pi worker IPC is worker-frame.v1, with directional handlers and inherited-pipe authority. Model credentials/real endpoints remain in the host broker; native/document effects are separately authorized. Keep exact consumption/source activation and private native checkpoint verification. ADR-029 is internal scope, not permission to expose unfinished HTTP/auth/resource/provider boundaries.
• Isolated Pi requires a scoped resource-trust.v1 approval for its immutable resource snapshot. Never mount the mutable original agent directory or expose ResourceStore filesystem capture to browsers. Official pi.exec uses the loader-scoped backend before factories execute; keep the 24-file v2 patch fingerprint. Native cancellation must wait for the actual PID namespace, including early bwrap startup, not just monitor exit (ADR-030).
• All Node namespace launches use the shared SandboxProcess guard; PDF/Flash use the Python pidfd guard. Do not reintroduce monitor-only cancellation. Product HTTP handlers use paired HttpOnly sessions, exact Origin/Host and CSRF; actor/workspace cannot come from a request body. ADR-031/032 cover internal tests, not deployment or permission to expose unfinished upload/approval/Reader routes.
• Conversation observations use generation/epoch/sequence identity, bounded replay and authenticated SSE. Observation loss triggers resync, never task replay or native cancellation. Snapshot history is a filtered projection of a verified native checkpoint prefix; never expose raw worker snapshots, thinking blocks, system/provider data or tool payloads (ADR-033). The public history window is not full cold restore/branch/history paging acceptance.
• apps/web/live.html is the internal real paired-chat entry; index.html remains the accepted simulation prototype. Never use Demo answers in the live client. Browser validators are generated static code from contracts (no eval). Keep uncertain outbox bodies/keys scoped to the tab and actor/workspace/conversation, and clear only on matching durable receipts or explicit discard/logout (ADR-034). No default live launcher, upload/Reader or full production acceptance is implied.
• RuntimeManager/RuntimeCatalog own bounded lazy runtimes and clean-restart seals (ADR-035). Claim before startup; release only after actual namespace/native join and native file+directory fsync. Resume the same Pi JSONL through the SDK; never rebuild it from product receipts. Do not clear an active catalog claim on PID/TTL guesses or expose a browser recovery override. Abrupt-host-death supervision, full branch/history controls and deployment remain open. Preserve the bwrap reaper while its known namespace still exists, even after a grace timer.
• Flash uses the reviewed finite vendor under python/docatlas-sidecar/src/docatlas_dsh_sidecar/_vendor/pageindex_flash; never edit those generated files manually. scripts/vendor_flash.py --check pins upstream bytes/functions. Raw/merge generations are immutable navigation, not Evidence. ADR-038 adds explicit Pi ModelRuntime summary/expand/full jobs, whole-job budgets and independently sealed navigation overlays; Python still has no credentials/loop. Read-only docatlas_enrichment rechecks the active source/frame and never starts a job. Full-quality/default-provider/recovery gates remain open. Keep legacy RPC unchanged unless its contracts/version are reviewed.
• Core document application/ports live in packages/core/src/document; Node discovery/assets/supervision live in packages/runtime-document. Keep legacy re-exports. Prepared scopes activate only on exact native consumption; revalidate authorization/hash/frame after async work and keep cancellation per conversation. ADR-028 isolates the new Node coordinator and all native PDF parsing in a separate one-file worker; keep cache-only readers/source grants/protected roots distinct. Never add an unsandboxed fallback. ADR-036 adds internal authenticated PDF upload/Library/original routes; public deployment and full R1/R3 gates remain open.
• UploadStore reserves bounded immutable bytes, not eligible sources. A Library import commit is required before submission admission. Same-name uploads do not overwrite history. Transfer staging is exclusive per reservation across processes; do not remove orphan staging on a TTL guess. Browser source selections are frozen into each request/hash, never inferred from the open Reader. Raw PDF preview is not evidence/citation/selection authority; keep the prototype independent and server-backed labels truthful.
• ADR-037 adds durable one-shot selection tickets. Core maps whitespace-only page text to verified source scalar positions, then resolves the exact same revision/page; missing/ambiguous/incomplete results are not tickets. Bind the whole group to one submission/hash, recheck policy/source/expiry at native consumption, and never reuse it for another submission on a TTL guess. Native quoted data is untrusted source content, not system instructions or saved Evidence. DSH transient markers stay unchanged; pin/Compare and structured Pi Answer citations remain pending. The Core answer compiler accepts host-projected successful Read receipts, not arbitrary browser/model metadata; legacy DSH keeps its adapter. Pi checkpoint/source lineage must be implemented before enabling product citations.
• ADR-039/040 supersede the earlier no-citation/no-launcher milestone notes: host Read attestations now bind native toolCallId/submission/scope to the same verified Pi checkpoint, and the loopback Pi Web beta is launched with scripts/run-docatlas-web.sh. Canonical manifests stay in SourceScopeStore; private publication links gate serving on the same completed ControlStore checkpoint. No arbitrary worker metadata, old/locate/tree results, unknown markers or provisional text becomes clickable evidence. Original-PDF focus rechecks source permission/hash; unique quote only, otherwise explicit page-only/ambiguous. Full geometry/compaction/steer attribution/research/public deployment gates remain open.
• The real local launcher binds only 127.0.0.1, displays a one-use pairing code, uses a separate ignored .cache/product state root and requires exact reviewed hashes for nonempty trusted resources. Preserve initial empty/no-model startup, private-vs-native roots, actual shutdown joins and clean native-file restore. Do not expose HTTP publicly or auto-clear unclean claims. The configured GPT-5.6 Luna host provider uses short-lived Azure CLI tokens without persisting them in DocAtlas; Azure CLI retains its existing login cache. Keep credentials out of worker/native/browser/errors, preserve the 4-request cap and token-process join, fixed HTTPS target, store:false and explicit function strict:false to retain Pi's optional tool arguments. No fake-provider fallback.
• contracts/ is the language-neutral wire source of truth. TypeScript and Python bindings must preserve its protocol version and JSON fields.
• ADR-041 adds Pi Record/Recall and authenticated Notebook on the existing Investigation journal. ResearchScopeSnapshots owns only immutable capture scopes, never text/representation/Evidence or document admission; no duplicate scope IDs across partitions. Install research frames only at exact native consumption and defer empty capture persistence until an authorized research tool actually uses it. ResearchJournal is private execution attribution/consent, not a second research content store. Filter source/original-conversation permissions before FTS/counts/cursors; unlinked Agent records are not visible leads. Save Note does not consume a question ticket; soft deletion retains history and must not be called privacy erasure.
• ADR-042 adds explicit personalization controls under an actor+workspace profile and separate protected root. Host supplies user identity; browser/model cannot pick a profile/actor or promote inferred memories. ADR-043 connects bounded host-ephemeral presentation at an exactly consumed submission through product-personalization-v2; v1 retains its not-connected meaning. Preserve native messages/tools/history and approved payload hooks. MemoryUse witnesses observed answer generation, not compliance/DOM/factual correctness; outcome remains unknown. Use revocation aborts and sticks to the submission until a new explicit question; contribution-only/export/idempotent replay must not revoke. Keep research and personalization switches orthogonal, privacy receipts truthful, and versioned mutation outboxes scoped/explicitly retried.
• ADR-044 extracts the human ClaimReviewApplication over existing M4 storage only. Trusted actor/source/Evidence/sign-off ports cannot be supplied by browsers/models; historical authorized scopes stay historical. This Core port does not imply live product Claim/Review/Publish routes or UI have been accepted.
• ADR-045 adds the bounded authenticated product-review workbench and six human commands over the same M4 journal. A selected historical human frame never changes Pi native source admission or relabels old Evidence. Resolve canonical Answer/selection captures with original Locator/scope/hash; reauthorize current sources and original conversations, and require Answer origins' private completed checkpoint publication. Note/Recall/Profile are not Evidence. Hash the whole product command into idempotency; keep exact tab-local outbox ownership/body/key and fence stale identities. Product Publish requires the latest verified journal-order human approval, never timestamp/ID sorting; an already-committed publication may replay only its exact original receipt. Keep this stricter product policy separate from legacy semantics. Derived-input gates are not arithmetic proof. Local publication does not complete Continuity, automatic learning, full recovery or public deployment; final acceptance remains in the tracker.
• ADR-046 adds explicit same-document revision imports, authorized historical original PDFs and a bounded human Continuity workbench. Freeze target/current-revision CAS and immutable bytes; filename matching is not a version relationship, same-current bytes may reuse, historical-byte reimport is not rollback. Status is strictly read-only and null is not success. Keep historical source/Answer/Claim/Artifact identity unchanged and never implicitly admit a new revision to Pi. Continuity follows complete canonical Answer/selection/derivation provenance and original publication authority; anchored Notes use the authorized ResearchScopeSnapshots adapter, never Note prose as Evidence. Comparative states require fresh two-sided Read Evidence and exact PDF resolution in one completed scope; freeze prior record version and the whole body/key, with original receipt-only replay. Bound scope enumeration before expensive verification, propagate integrity failures and distinguish historical-options truncation from selected-material truncation. Its Library follow-up atomically commits document/record receipt/job-success and permits only explicit, exact legacy-receipt repair; never infer success from latest revision or rerun ingest. Registry refresh failure cannot downgrade committed success and does not activate native sources. General crash recovery/impact discovery remain separate gates.
• ADR-047 connects a user-requested, single-axis answer-order Probe over one complete authorized published Answer. Core recomputes actual material/recipe hashes; do not trust matching declared digests or generate two factual answers. Keep Evidence/weakness/uncertainty/conflict sets intact; an empty actual M4 Claim set is valid, fabricated Claim IDs are not. Inspection is read-only; new controlled Probe/choice writes check contribution policy/CAS/profileEpoch inside the profile transaction. Choice/observation/pending candidate/original command receipt commit together, with one vote per controlled Probe. Only separate human confirmation creates MemoryVersion; use remains independently consented/observed, not proven utility. Keep reference-only profile records, full hash/epoch/original-answer outboxes, explicit replay and privacy-filtered JSON/Markdown export. Session-only choices cannot become future memory. Automatic triggers/inference, other axes and longitudinal quality remain unaccepted until their own gates pass.
• ADR-048 adds native model/thinking/queue controls and verified history paging without a new Pi patch or a second transcript. Preserve actual SDK capabilities, including supported max thinking. First-question-free persistence exclusively writes public SDK header/complete entries, never invented messages. Native intent/commit metadata and independently verified prefix proofs are required for success; full-body/approval/head/writer identity and a true stop-in-flight join barrier fence execution. Cold unresolved operations must be checked before SDK/extension factories, since model-free startup can still run pi.exec. Original-key cold reconciliation uses a metadata writer and clean catalog only, never factories/setters or unclean-claim takeover. History uses exact native parent/checkpoint and opaque scoped cursors; restore user text only through exact original-submission mapping, with unavailable placeholders after purge. Empty tool/thinking-only entries are not page anchors. Browser hashes/owner/head checks also fence late errors; do not fabricate snapshot native hashes or lose old PDF citation identity. Manual compaction/fork/selected-head and full parity/recovery remain separate gates.
• ADR-049 connects manual SDK compaction on the existing binding/session and native operation barrier. Only an actual compact entry/retained-entry/summary-hash proof establishes success; summaries are not Evidence or answer-generation MemoryUse. A joined compact rejection can settle failed only through its exact intent+terminal non-application proof; absent/ambiguous native effects remain unknown. Keep source grants invalidated, actual broker/native joins and late-effect admission fencing, whole-operation budgets, immutable historical Answer/PDF identity and exact-original-key cold recovery. Do not turn compaction into fake chat, privacy erasure, branch handoff or a new Pi patch. Automatic in-turn compact/steer attribution and full fork/selected-head lifecycle remain open.
• ADR-050 separates file-tail seals from actual SDK selected heads and adds real navigate/fork handoffs. Preserve native hooks, inherited IDs/labels/compaction remapping and actual per-session configuration. Reserve before effects, join actual ownership before installation/binding transfer, and finish only the exact original operation; GET never reconciles and unclean claims are never guessed safe. Catalog v2 keeps old rows/seals; ControlStore schema and canonical Answer/Evidence/Note/Profile remain unchanged. History uses original-human mappings and verified lineage, not fake question checkpoints or prepared editor text. Owned native chat is not current source authorization: canonical historical Answer/PDF access independently rechecks original/viewing conversations and sources. Full-tree previews do not grant cross-conversation off-branch Answer access; Probe remains in the original Answer conversation. Whole-product parity/recovery gates remain open.
• ADR-051 applies only the reviewed exact-hash numbered-heading guards through the Flash generator. Source admission verifies pinned HEAD, clean tracked/untracked inputs, finite Git tree and exact no-follow bounded blob bytes. Keep original upstream provenance and local patch hashes distinct, use the resulting new provider fingerprint and never rewrite old generations. Paired generated-PDF improvements do not establish real-corpus/OCR/full-model quality or a new upstream release.
• ADR-052 adds independent human Note/Question/Decision/Policy authoring and original-PDF annotations. Saving research must not mutate Ask drafts/tickets/source admission, invoke Pi or fabricate Agent calls/SelectionContexts/Evidence. Reuse SourceScopeStore's canonical journal with backup-first schema v5→v6; human effects and minimal whole-command receipts commit together. New human records, including Governance, require trusted commit context even through legacy mutation paths and retain original source/conversation/hash authority. Complete reads, exact-source overlays and original-key recovery reauthorize before disclosure; soft deletion is not privacy erasure. Policies are recorded intent, not automatically executed instructions or personal memory. Full research recovery and automatic learning remain separate gates.
• ADR-053 versions parallel Flash explicitly in each new request: absent recipe remains serial v1. V2 uses stable batches of at most two independent frontier/DAG tasks, reserves whole-job worst-case in-flight output and joins all real providers after failure/cancel before releasing ownership. Preserve original nodes/generations/Evidence and provider caps; concurrency is not proof of model/corpus quality or a new upstream release.
• ADR-054 adds default-off comparison invitations and a separate accumulated-learning path. Invitation permission, future contribution and preference use are independent. Only actual completed/published Answer transitions may reserve low-frequency invitations, never GET/reload/compaction; invitations are not observations. Count explicit eligible choices from at least three independent original Investigations in one mode/axis, retain counters, reauthorize every original Answer and require separate latest-digest human confirmation. Old null receipts/candidate snapshots are immutable; legacy raw/review APIs must not bypass new guards, and rejected/forgotten groups cannot recycle old votes. Use the existing profile journal with backup-first metadata v2→v3, reference-only provenance and complete erase/export verification. Do not claim passive behavioral inference, autonomous activation, drift relearning or full longitudinal efficacy.
• ADR-043 also fences product controls with a persistent non-content profileEpoch (profile metadata v2); privacy erasure increments it atomically. Old outboxes must never be re-epoched to recreate erased preferences/consent. Native request purpose uses a one-shot context+agent-signal association; compaction/branch/direct auxiliary model calls never create answer-generation MemoryUse. Keep native stream/options/hooks unchanged and do not infer purpose from prompt strings.
• Source revisions, evidence, claims, artifacts, and personal memory are distinct domains. Personalization never participates in evidence support.
• ADR-055 supersedes pairing requirements for the local product CLI at the user's explicit request: loopback-only login-free access, no code/cookie/expiry or account UI. Keep server-owned actor/workspace, exact Host/Origin, CSRF, Fetch Metadata and all document/native authorization. Generic paired HTTP remains a trusted compatibility interface, not a browser switch. Never expose login-free access publicly or to a shared proxy.
• Keep Pi transcripts, DocAtlas run/control records, Investigation journals, and Personalization ledgers distinct. Domain writes commit before successful results; runtime events alone do not prove durability. Each conversation has one runtime writer; managed child runs require explicit lineage, budgets, and cancellation.
• Do not introduce unknown persisted event types in the legacy DSH adapter. Its standard tool events remain unchanged. Pi mapping and new browser/run contracts require explicit review, not a rename of old event fields.
• Legacy routes remain behind DSH Connection authentication. New DocAtlas routes require product-owned authentication and authorization before exposure; never accept arbitrary browser filesystem paths. Native shell/file tools must respect the actual process/workspace boundary, not only document-tool scope checks.
• docs/implementation-plan.md is the canonical living execution plan. research/ records evidence and alternatives; implementation must not silently resolve an item that the plan leaves for ADR/contract review.
• Note, Review, and Memory are orthogonal product capabilities. Canonical trees remain immutable; working, research, and personalized state use typed journals/overlays rather than mutating source structure.
• ADR-065 limits runtime security maintenance to the independent Web. Preserve Pi's exact release/24-file patch and installed native provider peer capabilities. Flash's separate five-file pypdf import patch must go through the exact-hash generator with otherwise identical ASTs; never hand-edit the vendor or conflate it with the numbered-heading patch. Pin the maintained parser in the provider fingerprint, create new generations and preserve old data. Audit the actual sidecar workspace member, not the empty uv root. Original CLI dependencies require a separate reviewed update.

Change discipline

• Keep independent Web changes on an explicit branch and preserve the official GitHub origin. Compare/rebase upstream deliberately. Do not write through a symlink or mutate the original CLI, sibling checkouts or video-source workspace as an incidental maintenance step.
• Keep the scaffold buildable before adding product behavior.
• Preserve the DSH plans in docs/archive/dsh/ and track every reused module in docs/migration/dsh-to-core.md. Do not delete, move, or duplicate durable stores as part of a cosmetic folder reorganization. Do not rename this workspace or touch sibling workspaces without explicit direction.
• Add focused tests for every durable/wire parser and lifecycle transition.
• Run bash scripts/check.sh before handoff. Report the exact checks run.
• The root check builds the declared dependency graph once (check:build) before check:types and tests. Only these aggregate commands disable pre/post hooks; standalone package commands keep theirs. Keep the explicit packaged-sidecar check and mirror any future non-build hook checks in the aggregate path. Never use unordered parallel builds or rebuild shared lib/dist while tests read them.
• Generated outputs and dependency caches stay ignored; do not commit local .sources, .cache, .venv, node_modules, or lib directories.