pmx-canvas 0.8.2 → 0.9.0

package/dist/types/server/spatial-analysis.d.ts

@@ -68,8 +68,8 @@ export interface SpatialContext {
     }[];
     annotations: SpatialAnnotationContext[];
 }
-/** Euclidean distance between two node centers */
-export declare function centerDistance(a: CanvasNodeState, b: CanvasNodeState): number;
+/** Gap distance — how far apart two nodes are edge-to-edge (0 if overlapping) */
+export declare function gapDistance(a: CanvasNodeState, b: CanvasNodeState): number;
 /**
  * Detect proximity clusters using single-linkage clustering.
  * Two nodes are "close" if their edge-to-edge gap is within the threshold.
@@ -78,9 +78,12 @@ export declare function centerDistance(a: CanvasNodeState, b: CanvasNodeState):
  */
 export declare function detectClusters(nodes: CanvasNodeState[], proximityThreshold?: number): SpatialCluster[];
 /**
- * Find the nearest unpinned nodes to each pinned node.
+ * Find the nearest unpinned nodes by their edge-to-edge gap from each pin.
+ * The inclusive distance limit is in world pixels, independent of card size.
  */
 export declare function findNeighborhoods(nodes: CanvasNodeState[], pinnedIds: Set<string>, maxNeighbors?: number, maxDistance?: number): SpatialContext['pinnedNeighborhoods'];
+/** Shared lexical relevance for cards and library metadata. Scores are ranking details. */
+export declare function searchRelevance(title: string, fields: Array<[string, number]>, query: string): number;
 /**
  * Full-text search across node titles and content.
  * Returns matching nodes with relevance score.

package/dist/types/server/tour-control.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Driving a board tour: the shared stop cursor and eased camera moves.
+ *
+ * Navigation, not editing: nothing here records undo history, and the cursor
+ * is in-memory (like presence) — a restart or board switch starts over at the
+ * first stop. The browser animates; the server only decides WHERE to go and
+ * broadcasts it, so an agent and every presenting viewer agree on the stop.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { type Camera, type Tour, type TourStop } from '../shared/tour.js';
+export type TourStep = number | 'next' | 'previous';
+export interface TourStepResult {
+    index: number;
+    total: number;
+    stop: TourStop;
+}
+export declare function currentTour(): Tour;
+/** The stop the tour is on for the active board, or null when not touring. */
+export declare function tourPosition(tour?: Tour): number | null;
+/** Move the shared cursor. `next`/`previous` clamp at the ends; an explicit index must exist. */
+export declare function goToTourStop(step: TourStep): TourStepResult;
+export declare function exitTour(): void;
+/**
+ * Resolve an eased camera move and store its end camera as the board viewport
+ * (unrecorded). The size is the last window a browser reported, so this is the
+ * server's best estimate; the browser re-resolves against its real canvas area.
+ */
+export declare function moveCamera(input: unknown): {
+    stop: TourStop;
+    viewport: Camera;
+};

package/dist/types/server/wiki-links.d.ts

@@ -0,0 +1,14 @@
+import type { MemoryTarget, WikiLink } from '../shared/memory-graph.js';
+export declare function wikiReferences(content: string): string[];
+export interface WikiBoard {
+    id: string;
+    name: string;
+    cards: Array<{
+        id: string;
+        title: string;
+    }>;
+}
+/** IDs win over names; title matches must be unique. Never retarget an already bound link. */
+export declare function resolveWikiLinks(content: string, previous: WikiLink[], boards: WikiBoard[]): WikiLink[];
+/** Only server-owned bindings may navigate; the client still sanitizes rendered HTML. */
+export declare function renderWikiMarkdown(content: string, links: WikiLink[], exists: (target: MemoryTarget) => boolean): string;

package/dist/types/server/workbench-auth.d.ts

@@ -1,3 +1,5 @@
 /** Per-process capability used only to distinguish workbench clicks from HTTP agents. */
 export declare const workbenchToken: string;
 export declare function isWorkbenchToken(value: string | null): boolean;
+/** Refuse an old tab's writes after a daemon restart, without downgrading its actor. */
+export declare function refuseStaleWorkbenchWrite(req: Request): Response | null;

package/dist/types/shared/agent-context.d.ts

@@ -5,6 +5,8 @@ export interface AgentContextNode {
     kind: string;
     title: string | null;
     content: string | null;
+    /** Context excerpts do not serialize the card's complete incident relations. */
+    linksComplete?: false;
     metadata?: Record<string, unknown>;
     position?: {
         x: number;

package/dist/types/shared/agent-presence.d.ts

@@ -45,20 +45,28 @@ export interface AgentPresence {
     opCount: number;
     /**
      * The agent's REAL context window, when its host reports it (tokens used /
-     * window size). Null when no adapter reports — the top-bar meter then shows
-     * the pinned-context estimate against the configured budget instead, and
-     * says so.
+     * window size). Null when no adapter reports — the context chip then shows
+     * the brief's size against its budget instead.
      */
     contextUsage: {
         used: number;
         total: number;
     } | null;
     lastSeenAt: string;
+    /**
+     * What this session has done since it attached (AgentContext.dc.html lens:
+     * "Claude · this session"): ids of the cards read, created, edited and
+     * pinned on the open board. Only on attached presences; counts every agent
+     * on the board, like the receipt.
+     */
+    session?: SessionTouches;
 }
-export interface ContextBudget {
-    /** Estimated tokens of the pinned-context payload. */
-    used: number;
-    total: number;
+export interface SessionTouches {
+    startedAt: string;
+    read: string[];
+    created: string[];
+    edited: string[];
+    pinned: string[];
 }
 /**
  * One agent write, as the External Steering activity feed lists it. Derived
@@ -79,7 +87,6 @@ export interface AgentActivityEntry {
 }
 export interface AgentPresenceSnapshot {
     presences: AgentPresence[];
-    budget: ContextBudget;
     /** True when any presence is attached — the master gate for agent chrome. */
     sessionActive: boolean;
     /** Most recent agent writes, newest first (bounded by MAX_ACTIVITY_ENTRIES). */
@@ -98,8 +105,6 @@ export declare const PRESENCE_TOOLING_SETTLE_MS = 4000;
  * "Thinking" chips on a silent board. */
 export declare const PRESENCE_THINKING_SETTLE_MS: number;
 export declare const MAX_PRESENCES = 16;
-/** Default `budget.total` when `PMX_CANVAS_CONTEXT_BUDGET_TOKENS` is unset. */
-export declare const CONTEXT_BUDGET_DEFAULT_TOKENS = 32000;
 /**
  * Source labels that name a TRANSPORT, not an agent. A write arriving under
  * one of these while exactly one session is attached is the attached agent's
@@ -117,7 +122,5 @@ export declare const HUMAN_STARTED_SESSION_LABEL = "Agent session";
 export declare function isSessionActive(presences: readonly AgentPresence[]): boolean;
 /** Writers that are live but not attached — the External Steering mode. */
 export declare function externalWriters(presences: readonly AgentPresence[]): AgentPresence[];
-/** Rough token estimate for a JSON payload (chars / 4) — good enough for a meter. */
-export declare function estimateTokens(text: string): number;
 /** Chip label per phase — shared by the top-bar chip and the on-canvas cursor chip. */
 export declare function agentPhaseLabel(presence: Pick<AgentPresence, 'phase' | 'detail'>): string;

package/dist/types/shared/auto-arrange.d.ts

@@ -18,6 +18,7 @@ export interface ArrangeEdge {
     id: string;
     from: string;
     to: string;
+    toBoardId?: string;
 }
 export interface AutoArrangeResult {
     nodePositions: Map<string, ArrangePosition>;

package/dist/types/shared/boards.d.ts

@@ -1,6 +1,6 @@
-/** The Home category migrated 0.6 snapshots land on, so they do not bury the boards in use. */
-export declare const MIGRATED_SNAPSHOT_CATEGORY = "From old snapshots";
+/** The Home folder migrated 0.6 snapshots land on, so they do not bury the boards in use. */
+export declare const MIGRATED_SNAPSHOT_FOLDER = "From old snapshots";
 /** Slash-separated folder paths shared by the UI, HTTP/MCP and SDK. */
-export declare function normalizeBoardCategory(value: string | null): string | null;
+export declare function normalizeBoardFolder(value: string | null): string | null;
 /** Includes implicit parents, so a board in A/B can also be moved into A. */
-export declare function categoryAncestors(path: string): string[];
+export declare function folderAncestors(path: string): string[];

package/dist/types/shared/knowledge-lifecycle.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+/** The same policy contract validates workspace writes and browser drafts. */
+export declare const lifecycleSchema: z.ZodObject<{
+    decayType: z.ZodEnum<{
+        reality: "reality";
+        decision: "decision";
+        dependency: "dependency";
+        relevance: "relevance";
+    }>;
+    rate: z.ZodEnum<{
+        fast: "fast";
+        medium: "medium";
+        slow: "slow";
+        durable: "durable";
+    }>;
+    triggers: z.ZodArray<z.ZodString>;
+    revalidationMethod: z.ZodString;
+    cadenceDays: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const categorySchema: z.ZodObject<{
+    decayType: z.ZodEnum<{
+        reality: "reality";
+        decision: "decision";
+        dependency: "dependency";
+        relevance: "relevance";
+    }>;
+    rate: z.ZodEnum<{
+        fast: "fast";
+        medium: "medium";
+        slow: "slow";
+        durable: "durable";
+    }>;
+    triggers: z.ZodArray<z.ZodString>;
+    revalidationMethod: z.ZodString;
+    cadenceDays: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    name: z.ZodString;
+    glyph: z.ZodString;
+}, z.core.$strict>;
+export type Lifecycle = z.infer<typeof lifecycleSchema>;
+export type KnowledgeCategory = z.infer<typeof categorySchema>;

package/dist/types/shared/knowledge-presets.d.ts

@@ -0,0 +1,6 @@
+import type { KnowledgeCategory } from '../server/knowledge-lifecycle.js';
+/** Editable starter data. No runtime behavior depends on these names or ids. */
+export declare const KNOWLEDGE_PRESETS: Record<string, {
+    categories: KnowledgeCategory[];
+    folders: Record<string, string>;
+}>;

package/dist/types/shared/lifecycle-status.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryTarget } from './memory-graph.js';
+export interface SourceQualification extends MemoryTarget {
+    title: string;
+    reasons: string[];
+    unavailable?: true;
+    contentRevision?: number;
+    observedRevision?: number;
+    observedAt?: string;
+}
+export interface LifecycleQualification {
+    retired: boolean;
+    unknown: boolean;
+    due: boolean;
+    reasons: string[];
+    changedSinceRead: boolean;
+    lastReadAt: string | null;
+    lastValidatedAt: string | null;
+    contentRevision: number;
+    contentChangedAt: string | null;
+    /** The revisions a validating reviewer must have inspected, qualified by source relation. */
+    observations: Record<string, number | null>;
+    sources: SourceQualification[];
+    relevance: 'card-pinned' | 'board-pinned' | 'not-selected';
+}

package/dist/types/shared/memory-graph.d.ts

@@ -0,0 +1,53 @@
+/** Board-qualified identities: card IDs alone are not unique across a library. */
+export interface MemoryTarget {
+    boardId: string;
+    cardId?: string;
+}
+export interface WikiLink {
+    ref: string;
+    target?: MemoryTarget;
+}
+export declare function wikiLinksFromData(data: Record<string, unknown>): WikiLink[];
+export declare const memoryKey: (target: MemoryTarget) => string;
+export interface MemoryGraphNode extends MemoryTarget {
+    key: string;
+    kind: 'board' | 'card';
+    title: string;
+    summary: string;
+    folder: string | null;
+    inContext: boolean;
+    summaryOnly: true;
+    /** False when the focused view omits incident relations; cannot acknowledge all links. */
+    linksComplete?: boolean;
+    /** Card link revision captured with this projection. */
+    linksRevision?: number;
+    type?: string;
+    nodeCount?: number;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+export interface MemoryGraphEdge {
+    id: string;
+    from: string;
+    to: string;
+    kind: 'member' | 'portal' | 'wiki' | 'card' | 'previous';
+    relationKind?: string;
+    reason?: string;
+    label?: string;
+    type?: string;
+    source: MemoryTarget;
+    target: MemoryTarget;
+    missing: boolean;
+}
+export interface MemoryGraph {
+    nodes: MemoryGraphNode[];
+    edges: MemoryGraphEdge[];
+    unresolvedLinks: Array<{
+        source: MemoryTarget;
+        ref: string;
+    }>;
+    focus: string | null;
+    depth: number;
+}

package/dist/types/shared/relations.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+export declare const relationKindSchema: z.ZodString;
+export declare const relationReasonSchema: z.ZodString;
+export declare const relationDefinitionSchema: z.ZodObject<{
+    kind: z.ZodString;
+    ink: z.ZodEnum<{
+        supports: "supports";
+        contradicts: "contradicts";
+        cites: "cites";
+        derived: "derived";
+        informs: "informs";
+        related: "related";
+    }>;
+    directed: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const relationVocabularySchema: z.ZodArray<z.ZodObject<{
+    kind: z.ZodString;
+    ink: z.ZodEnum<{
+        supports: "supports";
+        contradicts: "contradicts";
+        cites: "cites";
+        derived: "derived";
+        informs: "informs";
+        related: "related";
+    }>;
+    directed: z.ZodBoolean;
+}, z.core.$strict>>;
+export type RelationDefinition = z.infer<typeof relationDefinitionSchema>;
+export declare const relationPresetSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    vocabulary: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        ink: z.ZodEnum<{
+            supports: "supports";
+            contradicts: "contradicts";
+            cites: "cites";
+            derived: "derived";
+            informs: "informs";
+            related: "related";
+        }>;
+        directed: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RelationPreset = z.infer<typeof relationPresetSchema>;
+export declare const RELATION_KINDS: RelationDefinition[];
+export declare const RELATION_PRESETS: Record<string, RelationDefinition[]>;
+export declare function relationPreset(vocabulary?: RelationDefinition[]): string | null;
+export declare function relationKind(edge: {
+    kind?: string;
+    type?: string;
+}): string;
+/** Direction is semantic, not inferred from ink or arrow decoration. */
+export declare function relationSourceEnd(edge: {
+    kind?: string;
+    type?: string;
+}): 'from' | 'to' | null;
+export declare function relationDefinition(edge: {
+    kind?: string;
+    type?: string;
+}, vocabulary?: RelationDefinition[]): RelationDefinition;
+/** Keep the authored label and the explanation, rather than treating a label as a kind. */
+export declare function relationText(edge: {
+    kind?: string;
+    type?: string;
+    label?: string | null;
+    reason?: string;
+}): string;

package/dist/types/shared/semantic-attention.d.ts

@@ -12,6 +12,7 @@ export interface SemanticWatchEdgeSummary {
     edgeType: CanvasEdge['type'];
     fromId: string;
     toId: string;
+    toBoardId?: string;
     fromTitle: string | null;
     toTitle: string | null;
 }
@@ -84,6 +85,7 @@ export interface SemanticAttentionSnapshot {
 }
 export declare function formatCompactWatchEvent(event: SemanticWatchEvent): string;
 export declare class SemanticWatchReducer {
+    private currentBoardId;
     private currentLayout;
     private currentPins;
     private previousSpatial;

package/dist/types/shared/tour.d.ts

@@ -4,9 +4,39 @@ export declare const cameraSchema: z.ZodObject<{
     y: z.ZodNumber;
     scale: z.ZodNumber;
 }, z.core.$strip>;
+/** A world-space box: `{ x, y }` is its top-left corner. */
+export declare const rectSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export declare const tourTargetSchema: z.ZodUnion<readonly [z.ZodObject<{
+    nodeId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    rect: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    viewport: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        scale: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strict>]>;
 export declare const tourStopSchema: z.ZodObject<{
     target: z.ZodUnion<readonly [z.ZodObject<{
         nodeId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        rect: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
     }, z.core.$strict>, z.ZodObject<{
         viewport: z.ZodObject<{
             x: z.ZodNumber;
@@ -27,6 +57,13 @@ export declare const tourSchema: z.ZodObject<{
     stops: z.ZodArray<z.ZodObject<{
         target: z.ZodUnion<readonly [z.ZodObject<{
             nodeId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            rect: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>;
         }, z.core.$strict>, z.ZodObject<{
             viewport: z.ZodObject<{
                 x: z.ZodNumber;
@@ -47,6 +84,7 @@ export declare const tourSchema: z.ZodObject<{
 export type Tour = z.infer<typeof tourSchema>;
 export type TourStop = z.infer<typeof tourStopSchema>;
 export type Camera = z.infer<typeof cameraSchema>;
+export type Rect = z.infer<typeof rectSchema>;
 export interface TourNode {
     id: string;
     type: string;

package/dist/types/shared/workspace-settings.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export declare const workspaceSettingsSchema: z.ZodObject<{
+    agentSessions: z.ZodBoolean;
+    knowledgeLifecycle: z.ZodBoolean;
+}, z.core.$strict>;
+export type WorkspaceSettings = z.infer<typeof workspaceSettingsSchema>;
+export declare const workspaceSettingsPatchSchema: z.ZodObject<{
+    agentSessions: z.ZodOptional<z.ZodBoolean>;
+    knowledgeLifecycle: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const DEFAULT_WORKSPACE_SETTINGS: WorkspaceSettings;

package/docs/RELEASE.md

@@ -10,6 +10,8 @@ single source of truth for the release dance — see also
 ## TL;DR
 
 1. Land all the changes you want in the release on `main` with green CI.
+   Run the tech-debt sweep (below) on everything since the last tag and fix what it finds
+   before bumping the version.
 2. Bump `package.json` `version`.
    Run `bun run build:plugin` to update the Agent Plugins manifest, canonical adapter runtime
    pin, and generated plugin copies. Publish that exact npm runtime version before advertising
@@ -63,6 +65,20 @@ following it copy-pasted a broken setup.
 grep -rn "pmx-canvas@0\." Readme.md docs/    # every hit must be the version you are about to ship
 ```
 
+**Sweep for tech debt before every release.** Read `git diff <last-tag>..HEAD` for what
+this release leaves behind, not just whether it works, and fix it before tagging rather
+than listing it for later:
+
+- **Orphans.** A surface removed but its data path kept: server work, env vars, protocol
+  fields, store signals, CSS, tests and docs that only served it.
+- **Duplicates.** A second helper, constant or type doing what an existing one does;
+  parallel code paths for the same job.
+- **Redundant work.** The same board, file or query read more than once per request; work
+  that runs on every event but whose result nobody uses.
+- **Stand-ins.** A field or revision reused for a meaning it was not built for, where the
+  design is still open: record it in the plan with the decision it waits on.
+- **Docs that describe what no longer exists**: `docs/`, skills, CLI help, Readme.
+
 **If this release touches CI or the release workflows, review that as
 release content.** A changed gate gets its first real run *on this
 release*: `e2e-cli` once launched Playwright without installing the
@@ -245,9 +261,11 @@ with `ok: true`, the published tarball is intact end-to-end.
   are workspace-local cache and must not be committed; they're gitignored
   but still appear in `git status`. Use `git restore --staged` if they
   sneak into a `git add -A`.
-- **`docs/screenshot.png`** updates whenever the showcase E2E runs.
-  Don't bake those updates into a release commit unless the screenshot
-  in `Readme.md` actually needs the refresh.
+- **Showcase screenshots** go to Playwright's per-test output directory as
+  `screenshot.png`, leaving tracked images unchanged. To intentionally refresh
+  the README image, copy that capture to `docs/screenshot.png`, run
+  `bun run build:plugin`, and commit both the source image and
+  `plugins/pmx-canvas/assets/preview.png` together.
 - **CHANGELOG dates**: use the actual publish date in the
   `## [version] - YYYY-MM-DD` header, not the day you wrote the entry.
 - **npm publish is asynchronous now**: a successful publish prints "Your

package/docs/adr-001-bun-only-runtime.md

@@ -4,6 +4,12 @@
 **Date:** 2026-06-12
 **Context for:** v0.2 stability release (docs/tech-debt-assessment-2026-06.md, Phase 2)
 
+**Scope clarified, 2026-10-15:** this decision applies to the local distribution and its
+Bun SDK. [ADR-002](adr-002-shared-product-separate-runtimes.md) records this narrowing and the
+[vision's separate-runtime direction](product-vision-2026-09.md#likely-repository-structure-shared-product-separate-runtimes)
+allows runtime-neutral shared product code and distinct Sites/Cloudflare adapters. It does
+not require a Node dual-build, compatibility shims or a cloud dependency for local use.
+
 ## Context
 
 pmx-canvas ships as TypeScript source executed directly by Bun. `package.json` points `main`/`exports` at `src/server/index.ts`, the `bin` entry is `src/cli/index.ts` with a `#!/usr/bin/env bun` shebang, and `engines` requires `bun >= 1.4.2`. There is no compiled JS distribution; `dist/` carries only the client bundle, the json-render viewer, and type declarations.
@@ -16,7 +22,7 @@ The decisive observation: nobody integrates with pmx-canvas by importing it. Age
 
 ## Decision
 
-pmx-canvas stays Bun-only for the SDK and runtime.
+The local pmx-canvas distribution stays Bun-only for the SDK and runtime.
 
 1. MCP (stdio) and the HTTP API are the universal integration surfaces. They are runtime-agnostic by construction: any client that can spawn a process or open a socket can use them.
 2. No Node dual-build (ESM + CJS dist of the server/SDK) will be produced. The package continues to ship TypeScript source executed by Bun.

package/docs/adr-002-shared-product-separate-runtimes.md

@@ -0,0 +1,93 @@
+# ADR-002: Shared product core, separate runtime editions
+
+**Status:** Accepted architectural direction; implementation remains staged
+**Date:** 2026-10-15
+**Context for:** Local PMX Canvas, ChatGPT Sites and the later standalone Cloudflare edition
+**Relationship:** Narrows [ADR-001](adr-001-bun-only-runtime.md) to the local runtime and SDK; does not replace it
+
+## Context
+
+The [product vision](product-vision-2026-09.md#likely-repository-structure-shared-product-separate-runtimes)
+keeps local PMX usable offline while adding hosted editions in stages. Boards, mutation
+rules, context compilation and renderers should remain one product across those editions.
+Sharing source code must not imply shared live state or a cloud dependency for local users.
+
+Today's application couples product behavior to Bun, synchronous SQLite, process-wide state
+and import-time wiring. Moving those modules into packages would not establish runtime
+independence. Conversely, separate product forks would duplicate rules and let editions drift.
+The architecture must separate runtime ownership without introducing distributed transactions
+between closely related board, context and relation operations.
+
+## Decision
+
+1. **Keep one modular product in one repository.** Reuse product rules and contracts across
+   editions. Establish package boundaries from demonstrated reuse, not a speculative folder
+   split. Shared contracts and rules must not depend on runtime entrypoints or concrete
+   storage; remote clients must not import local execution machinery.
+2. **Give each edition an explicit composition root.** Local, Sites and later standalone
+   Cloudflare entrypoints construct their dependencies and own startup, shutdown and recovery.
+   Importing shared code must not install global listeners or start local services.
+3. **Keep runtime capabilities behind explicit boundaries.** Authentication supplies a caller
+   and grants to shared permission rules. Persistence, temporary session services and external
+   effects belong to runtime adapters. Files, network fetches, subprocess MCP, builds and
+   browser automation are capabilities, not assumptions of the shared core. Document unsupported
+   behavior per edition; preserve distinct iframe sandbox and host-protocol requirements.
+4. **Keep ownership explicit.** Requests target a workspace, board and caller independently
+   of a viewer's navigation. Durable board state and audit records have different lifetimes
+   from presence, connections, timers and waits. Every supported writer follows the relevant
+   mutation policy and commit guarantees defined in the vision.
+5. **Share three contracts:** operation requests/results, the workbench request/event/asset
+   protocol, and the editable board archive. MCP adapts product operations to supported host
+   capabilities; common registration code does not establish support for every resource,
+   subscription or embedded application on every host.
+6. **Separate editions, not every domain into a service.** Keep board, context and relation
+   consistency together initially. A separate deployment needs a concrete security,
+   execution-lifetime, scaling or failure-isolation reason. Package boundaries alone do not
+   justify network boundaries.
+7. **Preserve independent editions.** Local retains Bun, SQLite and offline-capable local
+   features without hosted credentials. Sites and standalone hosting own their respective
+   storage and operational integrations. Boards move through deliberate export/import copies,
+   not automatic synchronization. Local is not a thin client, and Sites is not a disposable fork.
+
+## Consequences
+
+- Shared fixes can reach all editions, but each runtime needs contract and lifecycle checks.
+  Host support and platform limits must be verified on the actual platform, not inferred from
+  a portable build or simulated asynchronous storage.
+- ADR-001's rejection of a Node dual-build remains valid for the local distribution. This
+  decision permits runtime-neutral product code and hosted adapters, not compatibility shims.
+- Policy parity does not require every local SDK method to become asynchronous. Durable
+  completion across asynchronous storage is a separate contract; any SDK API change needs
+  its own versioned decision rather than a second permanent command implementation.
+- Exact packages, interfaces, storage mechanisms, journal schema and archive version/upgrade
+  policy remain scoped implementation decisions. This ADR does not select services or promise
+  indefinite format compatibility.
+
+## Alternatives considered
+
+- **Separate product forks per edition:** simpler initial porting, but duplicated permission,
+  revision and context behavior would drift. Rejected in favor of shared product rules.
+- **Microservices for boards, context and relations:** independent deployment at the cost of
+  network failures and cross-service consistency. Rejected without a demonstrated need.
+- **Package migration first:** creates release and import churn without proving isolation.
+  Rejected in favor of extracting a complete working slice first.
+- **Hosted backend required by local PMX:** reduces runtime variants by sacrificing offline
+  ownership and existing local workflows. Rejected by the product vision.
+
+## Delivery and revisit gates
+
+Owner acceptance remains first. Curation-effect runs and reruns are deferred to
+[plan 019](plans/plan-019-post-0.9-roadmap.md) step 6 (2026-10-19); preceding work is not
+evaluation-gated. Release and runtime-verification gates remain unchanged. Fix demonstrated
+defects narrowly; this ADR does not authorize a broad refactor, deployment or release.
+
+When the second runtime needs extraction, prove one read/edit/commit/reconnect slice with a
+browser and agent conflict, a lost-response retry, persistence failure, restart, independent
+board navigation and an unreadable linked source. Verify isolated runtime instances and the
+installed local offline path. Prove the slice on the target platform before expanding the port;
+package the boundaries once they are established.
+
+Revisit deployment boundaries when measured requirements justify separate security, scaling
+or execution lifetimes. Revisit adapter boundaries if a verified platform constraint cannot
+preserve the shared product guarantees. Neither trigger automatically authorizes product forks
+or a cloud dependency for local operation; changes require a new explicit decision.