All project documentation lives in design_docs/.

DOC_README.md is the authoritative first-reference document for documentation state.

It serves three goals:

1. Capture AI-agent insights and convert durable notes into Working Principles.
2. Provide the sole canonical index for active design_docs documentation and current project guidance.
3. Stay synchronized with current design_docs/ contents and reflect the latest active documentation state.

1. DOC_README.md
2. DOC_POLICY.md
3. PROJECT_DESCRIPTION.md
4. TERMINOLOGY.md
5. graphshell_docs/ — core app
6. verso_docs/ — Verso mod (web rendering + bilateral sync)
7. verse_docs/ — Verse mod (Tier 2 community network)
8. nostr_docs/ — NostrCore mod
9. matrix_docs/ — MatrixCore mod
10. graphshell_docs/comms/ — optional hosted communication surfaces inside Graphshell hosting
11. archive_docs/

• Verify claims against the code/docs before repeating them as facts.
• Keep active docs in the appropriate mod directory (graphshell_docs/, verso_docs/, verse_docs/, nostr_docs/, matrix_docs/), with hosted communication-surface docs under graphshell_docs/comms/; move superseded material to archive_docs/ checkpoints.
• Prefer updating an existing doc over creating a new one unless the scope clearly requires a new category/resource.
• Do not edit PROJECT_DESCRIPTION.md unless explicitly requested.
• Keep this index aligned with folder structure and status in the same session as any doc changes.
• If an AI note/memory adds a durable project principle, record it here under Working Principles.
• If another index conflicts with this file, this file is authoritative and the others should be aligned.
• Keep scaffold markers ([SCAFFOLD:<id>]) synchronized with the scaffold registry when integration status changes.
• Migration Strategy: Iterative Replacement
• • Since there are no active users, we prioritize code cleanliness over backward compatibility. We will replace subsystems directly rather than maintaining parallel legacy paths.
• When designing a new feature, ask:
• • Is the way you want this system to work consistent with our architectural guarantees (modularity, parallelization, access through intents and not direct state mutation, componentization as opposed to consolidation into monolithic core files, centralization of testing + diagnostic threading to automate testing)?
• • How can we refine the integration to meet our feature goals but respect our architecture?
• Implementation feedback loop (DOC_POLICY §13): every implementation is also a design probe. After each implementation pass, disseminate structural learnings to the relevant plans/docs in the same session. If a carrier model, API surface, or data shape changes, check which downstream plans depend on the old shape and add dependency notes or blocking guards before the next dependent step proceeds. It is acceptable for a plan to describe something not yet fully implemented — it is not acceptable for a plan to be silent about an architectural problem visible in code.
• For smolweb and middlenet content, prefer faithful protocol rendering plus optional assistive enrichment. Do not silently erase source protocol semantics in the name of convenience or polish.
• For smolweb expansion, prioritize browser-maturity capabilities such as trust UX, subscription/source health, source/page tools, retention boundaries, and wayfinding before widening protocol surface area for its own sake.
• Treat parallelization as an execution-class problem, not a blanket "more processes" goal: distinguish main-thread host authority, host-supervised workers, guest/sandbox runtimes, engine-owned process models, and external helpers, then pick the right substrate per host envelope.

Last updated: April 24, 2026 Project status source: ../README.md

• DOC_POLICY.md - Documentation policy and lifecycle rules.
• PROJECT_DESCRIPTION.md - Maintainer-owned product vision and long-term scope.
• DOC_README.md - AI context and canonical documentation index.
• TERMINOLOGY.md - Canonical project terminology and definitions.

• graphshell_docs/research/2026-02-18_graph_ux_research_report.md - Graph UI/UX research and synthesis.
• graphshell_docs/research/2026-02-20_edge_traversal_model_research.md - Edge traversal model research.
• graphshell_docs/research/2026-02-24_visual_tombstones_research.md - Research backlog for Ghost Nodes (deleted-but-preserved nodes; formerly "visual tombstones").
• graphshell_docs/research/2026-02-24_interaction_and_semantic_design_schemes.md - Research on interaction patterns, physics-as-semantics, and lens-based UX.
• graphshell_docs/research/2026-02-24_diagnostics_research.md - Diagnostics system research: three-registry model (ChannelRegistry/AnalyzerRegistry/TestRegistry), probe vs. analyzer vs. test classification, current gaps, pane improvements, and priority order.
• graphshell_docs/research/2026-02-27_viewer_state_matrix.md - Declared vs runtime-wired vs actually-rendered viewer matrix for migration planning.
• graphshell_docs/research/2026-02-27_all_docs_context_bootstrap.md - High-signal AI bootstrap summary of active+archive documentation context, priorities, invariants, and execution guardrails.
• graphshell_docs/research/STANDALONE_EXTRACTION.md - Standalone extraction notes.
• graphshell_docs/research/2026-03-01_webrender_wgpu_renderer_research.md - WebRender wgpu renderer: spec, feasibility, QA strategy, upstreaming model, and upstream community state (byo-renderer, Mozilla wgpu-hal direction, GLSL→SPIR-V recommendation). Closes the technical definition of #180 and feeds #183 readiness gates.
• graphshell_docs/research/2026-03-01_servo_script_engine_alternatives.md - Long-horizon research: Nova (Rust JS engine) + Cranelift JIT as a mozjs/SpiderMonkey replacement in Servo. Covers mozjs architecture, Nova DOD design, JIT options, ohim/Wasm plugin track, Servo AI policy, and scope comparison vs. WebRender wgpu work.
• graphshell_docs/research/2026-03-02_ux_integration_research.md - UX integration research: file tree + tile tree + UX tree. Seven-area gap analysis (IA, interaction semantics, predictability, discoverability, feedback/recovery, accessibility, density/overflow), priority matrix, five deliverable specs (Command Semantics Matrix, Interaction Contract, Surface Behavior Spec, Accessibility Baseline Checklist, UX Telemetry Plan).
• graphshell_docs/research/2026-03-04_standards_alignment_report.md - Canonical standards adoption register. Maps adopted vs. referenced-only external standards to every Graphshell domain. Resolves contradictions (ActivityPub vs. W3C VC/DID, RFC 6902 vs. CRDTs, rkyv vs. dag-cbor for Verse wire format, UUID v4/v7 namespace split, WCAG 2.2 vs. EN 301 549). All subsystem specs cite their adopted standards from this document. Read this before designing any new subsystem or Verse protocol.
• graphshell_docs/research/2026-03-27_ambient_graph_visual_effects.md - Ambient canvas visual effects: temporal decay, graphlet halos, rhythm/pulse, warm-node particle emission, tidal influence, edge tension arcs. Default-on/off split, configurability model, and open design questions.
• graphshell_docs/research/2026-03-29_graph_interaction_brainstorm.md - Validated graph interaction ideas: gravity wells, reading river, knowledge decay, constellation templates, merge detection, breadcrumb trails, orbital ego graphlets, portal nodes, filesystem projection, git-like branching, variable node size, citation overlap, sonification.
• graphshell_docs/research/2026-04-09_smolweb_graph_enrichment_and_accessibility_note.md - Smolweb opportunity note covering Bubble, CAPCOM, Antenna, Cosmos, Spacewalk, GUS, IRC, Wander, history-tree, irchiver, HTML vs Markdown, and the "faithful render plus optional assistive enrichment" recommendation.
• graphshell_docs/research/2026-04-09_smolweb_browser_capability_gaps.md - Capability-gap note for maturing Graphshell as a smolweb browser: trust/certificate UX, subscription and source health, source/page tools, discovery separation, wayfinding surfaces, retention boundaries, hosted comms, mutation/publication loops, explainable routing, and host-aware degradation.
• graphshell_docs/research/2026-04-10_ui_framework_alternatives_and_graph_tree_discovery.md - UI framework comparison (Makepad, iced, xilem, gpui, slint, custom), wgpu-gui-bridge demo findings, crate recommendations (vello as bridge), and discovery of GraphTree as graphlet-native tile tree replacement.
• graphshell_docs/research/2026-04-14_wasm_portable_renderer_feasibility.md - Feasibility study for a fully-WASM portable web renderer: html5ever + Stylo + Taffy + WebRender-wgpu + Boa stack, GPU path via wasi-gfx/WebGPU, WIT component architecture, tiered worlds (rss-viewer/article-reader/full-web), feasibility levels 1–5, and 10 novel architectural properties enabled by WASM snapshotting + async compositing (parallel CoW rendering, speculative pre-rendering, deterministic replay, progressive rendering with layout commitments).
• graphshell_docs/research/2026-04-24_iced_renderer_boot_and_isolation_model.md - Synthesis of three parallel surveys (iced 0.14 renderer architecture, Firefox/Chromium/Servo process-isolation models, middlenet integration surface) addressing how to mount content inside iced graph node panes. Findings: iced 0.14 is architecturally closed around wgpu::Device; iced uses wgpu 27 vs Servo's wgpu-29 fork; middlenet's CPU-side RenderScene needs no wgpu device. Recommendation: middlenet-first content surface (M1) before any wgpu interop work; use screenshot-loop (Option A) for first Servo render; defer shared-wgpu (Options B/C — HAL interop or forked iced) to post-prototype. Process-isolation recommendation: shared GPU + thread-level origin grouping in v1, origin-bucketed Servo instances in v2; node lifecycle (active/warm/cold) modeled on Firefox's tab unloader keyed on (graph_distance × staleness).

• graphshell_docs/technical_architecture/ARCHITECTURAL_OVERVIEW.md - Current architecture and component boundaries.
• graphshell_docs/technical_architecture/GRAPHSHELL_AS_BROWSER.md - Browser semantics and behavioral model; universal content viewer (MIME detection, ViewerRegistry selection, non-web renderers, tags/badges, UDC semantic physics).
• graphshell_docs/technical_architecture/2026-04-22_browser_subsystem_taxonomy_and_mapping.md - Synthesis map of canonical browser subsystems (content pipeline, networking, process/isolation, storage, navigation/history, chrome, input/a11y, devtools, extensions, security, telemetry, distribution, sync) onto Graphshell's crate/module topology with ✅/🔨/📋/🔭/⛔/❓ status, Graphshell-unique axes (graph truth, workbench, navigator, registries, six-track focus, semantic layer, distillery, mods), by-design exclusions vs undecided gaps, and crate/module quick reference. Contributor orientation + gap-analysis surface.
• verso_docs/technical_architecture/VERSO_AS_PEER.md - Verso mod: web capability (Servo + wry viewers, protocol handlers) and Verso peer agent (Ed25519 identity, SyncWorker, pairing, graph/workbench context sharing).
• graphshell_docs/technical_architecture/codebase_guide.md - Active module-orientation guide and debugging entry points for reducer/workbench/render boundaries.
• graphshell_docs/technical_architecture/BUILD.md - Build instructions and dependency notes.
• graphshell_docs/technical_architecture/QUICKSTART.md - Fast-start command reference.
• graphshell_docs/technical_architecture/unified_view_model.md - Canonical five-domain architecture model: Shell host, Graph truth, Navigator projection, Workbench arrangement, Viewer realization, and graph-bearing surfaces.
• graphshell_docs/technical_architecture/graphlet_model.md - Canonical graphlet semantics: derived vs pinned graphlets, graphlet shapes, ownership split, and UI expressions.
• graphshell_docs/technical_architecture/graph_tree_spec.md - GraphTree crate API design: framework-agnostic graphlet-native tile tree replacing egui_tiles, collapsing Navigator/Workbench projection gap via ProjectionLens, taffy layout, UxTree integration.
• graphshell_docs/technical_architecture/domain_projection_matrix.md - Canonical catalog of named projections across Graphshell domain pairs (Graph → Navigator/Workbench/Viewer/Canvas; Substrate → consumers; Graph+Substrate+WAL → Cartography; History/WAL → surfaces; specialty/scoped projections). Flags structurally-present-but-unnamed projections (Viewer resolution, canvas rendering), distinguishes the Lens concept (Layout+Theme+Physics+Filter) from ProjectionLens (Shape-stage mechanism for tree-family projections), and catalogs implementing mechanisms (projection pipeline, ProjectionLens, LayoutMode, NavAction, GraphTreeRenderer, CompositorAdapter, LensCompositor).
• graphshell_docs/technical_architecture/domain_interaction_scenarios.md - End-to-end scenarios showing how the five domains collaborate in concrete user flows.
• graphshell_docs/technical_architecture/2026-02-18_universal_node_content_model.md - Universal node content model vision.
• graphshell_docs/technical_architecture/2026-02-27_presentation_provider_and_ai_orchestration.md - Provider capability contract, node facet taxonomy, and tiered AI orchestration (tiny local model + retrieval + optional large-model escalation).
• graphshell_docs/technical_architecture/2026-03-01_dependency_inventory.md - Full direct-dependency inventory: active, transitional (wgpu migration drops), pre-staged (15 unused reserved deps), build-only, and platform-specific. Includes pre-staged→planned-feature mapping and wgpu migration group summary.
• graphshell_docs/technical_architecture/2026-03-29_middlenet_engine_spec.md - Middlenet protocol/content-space definition and phased delivery baseline, now updated with the partially landed extraction baseline (middlenet-core / middlenet-adapters / middlenet-render / facade middlenet-engine) and native Direct Lane feed/article surface.
• graphshell_docs/technical_architecture/2026-04-16_middlenet_lane_architecture_spec.md - Active Middlenet lane architecture: canonical semantic-document core, Direct Lane renderer, deferred HTML lane, Servo fallback lane, shared-host direction, deterministic lane selection, and 2026-04-20 implementation notes from the landed crate split.
• graphshell_docs/technical_architecture/2026-04-20_graphshell_gpu_spec.md - Skeleton spec for future graphshell-gpu crate: single GPU resource authority (one adapter, separate render/compute devices), shared font/image caches, offscreen worker pool, priority-queue frame scheduler, cross-renderer TextureBridge (Servo webview → graph node face), WASM envelope parity. Responsibility boundaries, core types sketched, trigger conditions for when the skeleton becomes an actionable extraction plan.

• graphshell_docs/implementation_strategy/PLANNING_REGISTER.md - Canonical execution register: active lane sequencing, stabilization bug register, issue-seeding guidance, and subsystem/lane prioritization.
• graphshell_docs/implementation_strategy/domain_interaction_acceptance_matrix.md - Compact PR-review acceptance matrix for cross-domain scenario IDs and evidence expectations.
• graphshell_docs/implementation_strategy/subsystem_ux_semantics/2026-03-01_ux_execution_control_plane.md - Consolidated UX execution control-plane: baseline done-gate, current milestone checklist, and issue-domain map.
• graphshell_docs/implementation_strategy/2026-02-28_ux_contract_register.md - Cross-spec UX ownership register and contract map.
• graphshell_docs/implementation_strategy/2026-03-01_ux_migration_lifecycle_audit_register.md - UX migration lifecycle register: current/planned/speculative audit with pre/post renderer/WGPU and networking timing gates plus UxTree automation readiness.
• graphshell_docs/implementation_strategy/2026-03-01_complete_feature_inventory.md - Complete cross-doc feature inventory with implemented/planned/speculative status and WGPU migration issue categorization.
• graphshell_docs/implementation_strategy/2026-03-02_scaffold_registry.md - Canonical machine-readable scaffold inventory ([SCAFFOLD:<id>]) and closure criteria.
• graphshell_docs/implementation_strategy/subsystem_storage/2026-03-11_graphstore_vs_client_storage_manager_note.md - Short architecture note separating Graphshell app durability (GraphStore) from future WHATWG-style browser-origin storage coordination (ClientStorageManager), with a Rust trait sketch for pluggable backends.
• graphshell_docs/implementation_strategy/subsystem_storage/2026-03-11_client_storage_manager_implementation_plan.md - Phased P0–P5 execution plan for a future Servo-compatible ClientStorageManager: runtime seam, metadata loading, bucket lifecycle, endpoint registration, async deletion, and session/private-scope closure.
• graphshell_docs/implementation_strategy/viewer/2026-03-02_filesystem_ingest_graph_mapping_plan.md - Filesystem ingest feature plan with viewer-readiness gate, files→nodes / folders→frames mapping, and phased acceptance criteria.
• graphshell_docs/implementation_strategy/viewer/2026-04-03_clipping_viewer_follow_on_plan.md - Active follow-on viewer plan for remaining clipping work after the landed 2026-02-11 clipping slice was archived.
• graphshell_docs/implementation_strategy/viewer/2026-03-08_servo_text_editor_architecture_plan.md - Servo-backed text editor architecture: editor-core (WASM-clean) + Servo surface split, IME composition contract, crate layout, phases, and acceptance criteria.
• graphshell_docs/implementation_strategy/viewer/universal_content_model_spec.md - Canonical UCM interaction contract: viewer trait, selection policy, MIME detection, non-web viewer types, FilePermissionGuard, core/host split.
• graphshell_docs/implementation_strategy/viewer/2026-03-02_unified_source_directory_mapping_plan.md - Unified local/network/web directory-domain auto-mapping plan, gated by filesystem-ingest readiness.
• graphshell_docs/implementation_strategy/2026-03-11_boa_scripting_engine_plan.md - Boa JS engine as a Graphshell-native scripting layer: graph queries, reactive automation, custom action registration, and JS mod tier. Four-phase plan (read-only queries → event hooks → ES module mods → async runtime).
• graphshell_docs/implementation_strategy/2026-04-20_middlenet_direct_lane_v1_5_plan.md - Middlenet Direct Lane v1.5 milestone: PreparedDocument/SemanticDocument raw-vs-distilled split, middlenet-transport/middlenet-formats crate extraction, streaming DocumentDelta + RenderLifecyclePhase + CancelToken, shell-authority/viewer-interpreter trust UX, product-grade viewer:middlenet with AccessKit projection, cross-surface reuse (Phase 1 ad-hoc), and verso scaffold pulling Servo/Wry out of Middlenet's lane enum.
• archive_docs/checkpoint_2026-04-21/graphshell_docs/implementation_strategy/system/2026-04-21_verso_shell_authority_refactor_plan.md (archived 2026-04-21) - Completed refactor that promoted verso into the Shell's routing authority for engine/viewer/pane ownership and renamed mods/native/verso to the web_runtime provider bundle. PRs 1–7 landed; viewer-id string-authority hardening noted as follow-on.
• graphshell_docs/implementation_strategy/aspect_render/2026-03-12_compositor_expansion_plan.md - GL parent-render compositor expansion: content signature enrichment, lifecycle → overlay affordance, lens-driven Pass 3 descriptor, tile activity diagnostics channel, focus delta latching, EmbeddedEgui z-order fix, and generic viewer callback path.
• graphshell_docs/implementation_strategy/aspect_render/2026-03-01_webrender_wgpu_renderer_implementation_plan.md - WebRender wgpu renderer implementation plan (P0–P12). The egui-wgpu UI cut has landed; the remaining plan concerns deeper WebRender/runtime bridge convergence.
• graphshell_docs/implementation_strategy/subsystem_ux_semantics/ux_event_dispatch_spec.md - Canonical UxTree event dispatch contract (capture/target/bubble/default, modal isolation, authority routing, diagnostics/test gates).
• graphshell_docs/implementation_strategy/subsystem_ux_semantics/2026-04-05_command_surface_observability_and_at_plan.md - Active companion closure lane for Shell command-surface provenance diagnostics, UxTree/probe/scenario modeling, and Shell command-bar / omnibar AT validation.
• graphshell_docs/implementation_strategy/aspect_command/radial_menu_geometry_and_overflow_spec.md - Canonical radial geometry/overflow/readability contract with deterministic ring assignment and CI test expectations.
• graphshell_docs/implementation_strategy/workbench/workbench_frame_tile_interaction_spec.md - Canonical interaction contract for the workbench/frame/tile model.
• graphshell_docs/implementation_strategy/workbench/WORKBENCH.md - Workbench domain spec: arrangement and activation authority within the five-domain model.
• graphshell_docs/implementation_strategy/workbench/workbench_backlog_pack.md - Workbench execution backlog including cross-domain scenario-track IDs.
• graphshell_docs/implementation_strategy/workbench/graphlet_projection_binding_spec.md - Workbench-specific binding model for linked vs detached graphlet arrangements.
• graphshell_docs/implementation_strategy/workbench/2026-04-10_graph_tree_implementation_plan.md - GraphTree implementation plan: phased migration from egui_tiles, Navigator projection collapse, arrangement-edge consumption, 7-phase execution with code impact map and rollup of absorbed Navigator backlog items.
• graphshell_docs/implementation_strategy/workbench/2026-03-20_arrangement_graph_projection_plan.md - Plan to make tile tree a projection of arrangement graph truth: HostedSurface bridge object, ArrangementRelation sub-kinds (tab-order-next, group-member, split-child, etc.), Navigator faithfulness contract, workbench invocation via arrangement mutations, and 5-phase migration plan.
• graphshell_docs/implementation_strategy/workbench/pane_presentation_and_locking_spec.md - Canonical contract for tiled/docked presentation and PaneLock behavior.
• graphshell_docs/implementation_strategy/workbench/workbench_layout_policy_spec.md - Semantic layout policy: WorkbenchLayoutConstraint (role-keyed anchor splits), UxConfigMode (per-surface unlock/configure/lock flow), SurfaceFirstUsePolicy (first-use preference prompts), and WorkbenchLayoutPolicyEvaluator (pure (UxTreeSnapshot, WorkbenchProfile) → Vec<WorkbenchIntent>).
• graphshell_docs/implementation_strategy/navigator/NAVIGATOR.md - Navigator domain spec: graphlet derivation, scoped search, specialty navigation layouts, and projection authority.
• graphshell_docs/implementation_strategy/navigator/navigator_projection_spec.md - Canonical five-stage Navigator projection contract: Scope -> Shape -> Annotation -> Presentation -> Portal, plus composition rules, annotation registry, portal gesture taxonomy, projection diff identity, time-axis specialty behavior, layout inheritance, and cost classification.
• graphshell_docs/implementation_strategy/navigator/navigator_backlog_pack.md - Navigator execution backlog including cross-domain scenario-track IDs. Includes Navigator Chrome Drift Analysis: 6 drift points between spec and live code (render_navigation_buttons removal, focused_content_status parameter, dead imports, WorkbenchChromeProjection nav field, §12 acceptance criterion, WorkbenchPaneEntry presentation_mode).
• graphshell_docs/implementation_strategy/navigator/navigator_interaction_contract.md - Canonical Navigator click grammar and node-vs-structural row interaction rules.
• graphshell_docs/implementation_strategy/shell/SHELL.md - Shell domain spec: Graphshell's only host and app-level orchestration boundary.
• graphshell_docs/implementation_strategy/shell/2026-04-03_shell_command_bar_execution_plan.md - Active Workstream A closure lane for Shell command-bar authority, omnibar session/mailbox state, focused-target routing, and legacy command-path cleanup.
• graphshell_docs/implementation_strategy/shell/2026-04-17_chrome_port_cleanup_plan.md - M6 prelude: chrome surface inventory (toolbar, omnibar, tab strip, sidebar, dialogs, toasts, radial, command palette, settings, context menu), five cross-cutting mess areas to attack first, host-neutral uxtree / accessibility port / diagnostics-coverage gates as M6 blockers, "Firefox where equivalent / own voice where novel" adoption rule, and explicit non-goals.
• graphshell_docs/implementation_strategy/shell/2026-04-24_graphshell_runtime_crate_plan.md - Active extraction lane for a lightweight graphshell-runtime crate. Slice 1 moves the tick-owned toast/clipboard ports into a portable workspace crate and rebinds GraphshellRuntime::tick to that narrower boundary.
• graphshell_docs/implementation_strategy/shell/2026-04-24_iced_content_surface_scoping.md - Scoping plan for mounting content (middlenet documents, then Servo webviews) inside iced graph node panes. Revised after the 2026-04-24 renderer-boot research: middlenet-first content surface (M1), screenshot-loop for first Servo render (C3, Option A), shared-wgpu interop (C3.5, Options B/C — HAL or forked iced) deferred to post-prototype. M1.1 landed 2026-04-24 (in-tree) and refactored 2026-04-25 into a standalone crates/iced-middlenet-viewer workspace crate (no Servo/webrender deps; 6 tests + runnable demo example).
• graphshell_docs/implementation_strategy/shell/2026-04-24_blitz_shaped_chrome_scoping.md - Long-horizon alternative to iced chrome: Stylo + Taffy + Parley + WebRender stack rendering HTML/CSS chrome through the same WebRender as the graph canvas and Servo content. Eliminates the iced↔Servo wgpu version split permanently. ~3.5–5 months end-to-end. Component inventory, sliced execution plan B0–B7, risks, decision criteria for when to start. Not the next slice; documents the option so it's startable when iced limitations bite hard enough.
• graphshell_docs/implementation_strategy/shell/2026-04-27_gpui_host_integration_plan.md - Long-run host framework target: GPUI via Glass-HQ fork (wgpu 29, shared device with Vello + WebRender). Covers the three-part custom renderer patch (device exposure + WgpuTexture PaintSurface + wgpu blit), Glass-HQ PR strategy, three-layer architecture (GPUI chrome + Vello graph canvas + WebRender Navigator surfaces), migration gate from iced, and Xilem monitor conditions. iced remains active target until Phase 3 gate is met.
• graphshell_docs/implementation_strategy/shell/2026-04-28_iced_jump_ship_plan.md - Active iced lane. Egui treated as broken; iced built to a refined UX target, not egui parity. Resumed 2026-04-29 with the canonical TERMINOLOGY.md refactor folded in (§0 reconciliation, §3.2.1 host-neutral necessities, §4.5 Frame/Split/Pane vocabulary reconciled, §4.7 Presentation Buckets, §4.8 canvas instances + four-tier layout, §4.9 uphill rule). S2 TERMINOLOGY.md correction pass complete; first concrete S2 deliverable (composition skeleton) landed 2026-04-29.
• graphshell_docs/implementation_strategy/shell/2026-04-29_gpui_research_lanes.md - GPUI research closure (Lanes 0-9): tiny GPUI lab app, raw GPUI vs gpui-tea comparison, multi-canvas hosting criterion (N=8-16 swatch instances) added to Lane 2 as a separate pass/fail. Closed; learnings folded into the iced jump-ship plan.
• graphshell_docs/implementation_strategy/shell/iced_composition_skeleton_spec.md - Iced parallel to shell_composition_model_spec.md: slot model (CommandBar / NavigatorTop / NavigatorLeft / FrameSplitTree / NavigatorRight / NavigatorBottom / StatusBar), Frame split tree as pane_grid::State<Pane>, single GraphCanvasProgram shared across main canvas / canvas Panes / swatches / base layer, three Navigator Presentation Bucket surfaces, Active/Inactive toggle UI in Tree Spine. Canonical interaction constraint: Splits are created implicitly by drag (Zed/VSCode pattern), never by Split-direction buttons. First concrete S2 deliverable for the iced jump-ship plan. Patched 2026-04-29 with idiomatic-iced Application skeleton (Elm triad), Stage A-F mapping, canvas::Program trait shape, subscribe-don't-poll anti-pattern.
• graphshell_docs/implementation_strategy/shell/iced_omnibar_spec.md - Revised 2026-04-29 to URL-entry + breadcrumb display only. Per the omnibar-split simplification, the omnibar no longer dispatches commands or graph searches — those go to the Command Palette and Node Finder respectively. Two modes (Display / Input; Fullscreen retired). CommandBarFocusTarget retired; each surface stores its own focus_token. Submission emits one OpenAddress for URL-shaped input or routes non-URL queries to the Node Finder. Reuses NavigatorContextProjection, BreadcrumbPath, HostRequestMailbox. S2 sub-deliverable.
• graphshell_docs/implementation_strategy/shell/iced_node_finder_spec.md - Added 2026-04-29 by the omnibar-split simplification. Modal Ctrl+P fuzzy graph-node search (Zed/VSCode-shaped). Searches across (title, tag, address, content snapshot); empty-query shows recently-active nodes; activation emits WorkbenchIntent::OpenNode with WorkbenchProfile destination rule. Footer fallbacks ("Open as URL…" routes to omnibar, "Search the web for X" config-gated). AccessKit role mapping; coherence guarantee restated. Sibling to omnibar (URL-shaped) and Command Palette (action-shaped); each owns one verb.
• graphshell_docs/implementation_strategy/shell/iced_command_palette_spec.md - Revised 2026-04-29 to the simplified two-surface model: Command Palette (Modal + text_input + flat ranked list, Zed/VSCode-shaped) and Context Menu (iced_aw::ContextMenu with flat list). Search/Context palette mode distinction, two-tier rendering, and Radial Palette Mode are retired. Canonical aspect_command/command_surface_interaction_spec.md revised in the same commit to match. Reuses ActionRegistry action source and verb-target wording; adds iced widget choices, Message contract, focus dance with omnibar, ConfirmDialog gate for destructive actions, disabled-reason rendering, AccessKit roles, provenance trace integration. S2 sub-deliverable for the iced jump-ship plan.
• graphshell_docs/implementation_strategy/shell/iced_agent_pane_spec.md - Agent pane for AgentRegistry agents — tool pane hosting conversation transcript, proposed-intent inspector with explicit user confirmation, agent-context display showing read-grants, input field with @-references and /-slash-commands. Agents propose GraphReducerIntent sequences; users review/confirm; every applied intent records ActionOrigin::Agent { agent_id, conversation_id, turn_id } provenance through Activity Log and WAL. Context grants explicit/visible/revocable; agent never reads beyond grant set. Closes the AI-enabled-graph-scripting use case.
• graphshell_docs/implementation_strategy/shell/search_providers_and_fuzzy_spec.md - Two related primitives shared across iced surfaces: a SearchProvider trait + atomic registry (URL completion / web search / graph search / agent references / Verse community future) and a shared FuzzyRanker built on nucleo (Helix's pure-Rust fuzzy crate; consistent matched-indices for highlight rendering). Consumed by omnibar / Node Finder / Command Palette / Agent Pane @-references. Provider HTTP flows through graphshell-net; allowlists follow the settings spine.
• graphshell_docs/implementation_strategy/shell/iced_browser_amenities_spec.md - Per-amenity specs for the eight browser amenities reshaped to the graph paradigm (History, Bookmarks, Find-in-page/in-graph, Downloads, Devtools, Sessions/restore, Profiles, Multi-window) plus the Frametree implicit ninth. Each section answers: Presentation Bucket, surface, data source, intent flow, verso:// address. History "what constitutes a visit" + Bookmarks graphlet-tag schema answered. Closes the composition-skeleton §10 Frametree-visualization open item. Closes the last explicit S2 checklist item.

These workspace crates make the iced host's portable surface testable + demoable without graphshell main's Servo/webrender dep tree. Pattern: portable widget/host crate + thin shim in graphshell main + standalone demo binary.

• crates/iced-middlenet-viewer/ - Iced widget that paints middlenet RenderScenes (Gemini, RSS, Markdown, plain text) using iced primitives. Self-emits MiddlenetViewerEvent::LinkActivated for click→HostIntent::CreateNodeAtUrl round-trips. 6 tests + runnable demo example.
• crates/iced-graph-canvas-viewer/ - Iced canvas::Program for graph-canvas ProjectedScenes with pan/zoom + camera state. Includes painter submodule (was iced_canvas_painter in graphshell main). 9 tests + runnable demo with hand-built nodes/edges.
• crates/iced-wry-viewer/ - WryHost that mounts wry::WebView overlays as children of the iced window via iced::window::run raw-handle extraction. Depends on verso with the wry-engine feature (per the wry-into-verso lane). 7 tests + runnable demo opening example.com in a fixed overlay region.
• crates/verso/ - Routing/dispatch layer (EngineChoice, HostCapabilities, DispatchOutcome, ViewerHandle) + the wry_engine submodule (manager, frame_source, types) under the wry-engine feature. Phase A2 (2026-04-25) moved the ~800-line wry implementation in from graphshell/mods/native/web_runtime/. 22 tests including 8 wry_engine tests.
• graphshell_docs/implementation_strategy/shell/shell_backlog_pack.md - Shell execution backlog including overview, routing, and interruption scenario-track IDs.
• graphshell_docs/implementation_strategy/shell/shell_overview_surface_spec.md - Concrete Shell overview surface for graph/workbench/runtime summary and cross-domain routing.
• graphshell_docs/implementation_strategy/graph/GRAPH.md - Graph domain spec; the canvas is its primary rendered surface, not the domain name.
• graphshell_docs/implementation_strategy/graph/node_badge_and_tagging_spec.md - Canonical interaction contract for node badges, tag assignment surface behavior, icon resources, and Knowledge Registry integration.
• graphshell_docs/implementation_strategy/graph/2026-04-03_node_glyph_spec.md - Canonical node glyph spec: visual form of a node on the canvas, resolved via rule-matching pipeline from node data through theme application. Owns body, content imagery, LOD presentation, and user-authored glyph rules. Orthogonal to PMEST facets.
• graphshell_docs/implementation_strategy/graph/2026-04-03_physics_preferences_surface_plan.md - Follow-on execution lane for the page-backed physics settings surface: scope-aware controls, preset portability, advanced overrides, and dependency triage for graph/view-local physics preferences.
• graphshell_docs/implementation_strategy/graph/2026-04-03_physics_region_plan.md - Follow-on execution lane for authored physics regions: spatial-rule objects distinct from frame-affinity, with explicit creation, overlap, scope, persistence, and divergent-view commit semantics.
• graphshell_docs/implementation_strategy/graph/graph_node_edge_interaction_spec.md - Canonical interaction contract for graph, node, edge, and camera semantics on graph-bearing surfaces including the canvas.
• graphshell_docs/implementation_strategy/graph/2026-03-21_edge_family_and_provenance_expansion_plan.md - Edge vocabulary expansion plan: keeps the current five relation families, adds a dedicated Provenance family, and proposes broader semantic/traversal/containment/arrangement/imported sub-kind vocabularies for prototype-era knowledge capture.
• graphshell_docs/implementation_strategy/graph/2026-03-21_edge_payload_type_sketch.md - Rust-facing graph-model sketch for the next EdgePayload: split family from sub-kind, move traversal onto an explicit event carrier, and add typed Imported/Provenance sidecars.
• graphshell_docs/implementation_strategy/graph/2026-03-11_graph_enrichment_plan.md - Umbrella graph-enrichment plan unifying tags, badges, UDC classification, import/clip enrichment, provenance, and visible graph effects under the knowledge-capture lane.
• graphshell_docs/implementation_strategy/graph/2026-04-03_layout_backend_state_ownership_plan.md - Follow-on execution lane for widening the persisted layout carrier, stabilizing external layout IDs, and defining when Graphshell should move past the current upstream layout-state seam.
• graphshell_docs/implementation_strategy/graph/2026-04-03_damping_profile_follow_on_plan.md - Follow-on execution lane for damping profiles: named curve identities, deterministic registry lookup, explicit settle-shape policy, and profile-facing diagnostics.
• graphshell_docs/implementation_strategy/graph/2026-04-03_edge_routing_follow_on_plan.md - Follow-on execution lane for edge routing: post-layout path policy, readability-driven suggestions, low-cost first-slice routing, and bounded bundling strategy.
• graphshell_docs/implementation_strategy/graph/2026-04-03_semantic_clustering_follow_on_plan.md - Follow-on execution lane for semantic clustering: attributable semantic inputs, out-of-band cluster computation, explicit layout consumption, and user-visible explanation.
• graphshell_docs/implementation_strategy/graph/2026-04-03_layout_transition_and_history_plan.md - Follow-on execution lane for layout morphing, bounded position snapshots, and view-owned spatial undo/redo that stays separate from graph-topology history.
• graphshell_docs/implementation_strategy/graph/2026-04-03_layout_variant_follow_on_plan.md - Follow-on execution lane for built-in layout variants beyond FR/Barnes-Hut: widened state carrier, analytic first wave, portfolio integration, and second-wave admission bar.
• graphshell_docs/implementation_strategy/graph/2026-04-03_wasm_layout_runtime_plan.md - Follow-on execution lane for sandboxed runtime-loaded layouts: host adapter, guest ABI, fallback behavior, and snapshot-safe degradation.
• graphshell_docs/implementation_strategy/graph/2026-04-03_twod_twopointfive_isometric_plan.md - Narrowed execution lane for TwoD, TwoPointFive, and Isometric projection modes that preserve 2D layout truth without assuming full free-camera 3D.
• graphshell_docs/implementation_strategy/graph/2026-04-11_graph_canvas_crate_plan.md - Phased extraction plan for graph-canvas crate: framework-agnostic scene derivation, camera, projection, interaction, hit testing, and backend selection.
• graphshell_docs/implementation_strategy/graph/2026-04-13_graph_canvas_phase0_plan.md - Active execution: Phases 0–1 — crate scaffold, portable types, projection math, and derive_scene() pipeline. Iced migration context.
• graphshell_docs/technical_architecture/graph_canvas_spec.md - graph-canvas crate API design: scene derivation, camera/projection, interaction/hit testing, backend contract, and diagnostics.
• graphshell_docs/implementation_strategy/graph/faceted_filter_surface_spec.md - Canonical faceted-filter contract: PMEST schema, operator semantics, Lens integration, omnibar/palette parity, and diagnostics/test gates.
• graphshell_docs/implementation_strategy/graph/facet_pane_routing_spec.md - Canonical facet-rail routing contract: single-node facet navigation, Enter-to-pane destination resolution, focus return, and UxTree exposure.
• graphshell_docs/implementation_strategy/aspect_command/command_surface_interaction_spec.md - Canonical interaction contract for command surfaces and unified action invocation.
• graphshell_docs/implementation_strategy/aspect_input/input_interaction_spec.md - Canonical interaction contract for hardware input routing: context stack, binding resolution, chord/sequence recognition, remapping, cross-surface routing, and gamepad input.
• graphshell_docs/implementation_strategy/aspect_control/2026-03-02_graphshell_profile_registry_spec.md - General persisted GraphshellProfile contract (default profile, user-created profiles, persistence/migration/diagnostics).
• graphshell_docs/implementation_strategy/aspect_render/render_backend_contract_spec.md - Canonical backend abstraction contract: bridge mode enum, capability probe, Glow GL state isolation, wgpu texture handoff, fallback routing, Glow retirement conditions, and feature guardrails. §12: Servo RenderingBackendBinding cleanup plan (enum design, zero-copy render_to_view, WebGL stubs, Painter cleanup). §13: WebRender WgpuHal backend extension (escalatory wrapper model, factory-based variant, composite_output_hal accessor).
• graphshell_docs/implementation_strategy/aspect_render/frame_assembly_and_compositor_spec.md - Canonical frame composition pass model (Chrome → Content → Overlay), TileRenderMode enum, CompositorAdapter GL state isolation and callback ordering, Embedder decomposition seam (EmbedderCore / RunningAppState boundary), frame loop coordination contract. §8: C4 render pass sharing design — take/put-back encoder pattern, new WgpuDevice methods, per-target render pass coalescing.
• graphshell_docs/implementation_strategy/aspect_render/2026-03-27_egui_retained_state_efficiency_and_physics_worker_evaluation_plan.md - Per-GraphViewId retained state isolation plan: GraphViewRenderRuntime carrier, VisualProjectionFlags for incremental selection/badge/crash/theme projection, single-owner physics (Phase C), conditional worker (Phase E), baseline benchmarks (Phase D). Includes cross-stack integration requirements and ownership receipts table.
• graphshell_docs/implementation_strategy/aspect_render/2026-03-23_webrender_wgpu_backend_implementation_plan.md - WebRender wgpu backend implementation plan (Servo #37149): feature flag design, GpuDevice trait extraction, naga GLSL→WGSL shader translation, bind group layout, render pass restructuring, swapchain integration, 5-phase rollout, and full proof-of-correctness strategy (pixel diffs, WPT, CI matrix, validation layers, Criterion benchmarks).
• graphshell_docs/implementation_strategy/aspect_render/2026-04-10_wgpu_gui_bridge_interop_architecture_plan.md - wgpu-gui-bridge broader interop architecture: decouple GL import from surfman (Layer 1 raw import primitives, Layer 2 producer adapters, RawGlFrameProducer), Windows Vulkan NT handle path (Phase 2a), DX12 deferred (Phase 2b), demo/testing phase. Used in Graphshell's Servo integration to avoid the GL backend.
• graphshell_docs/implementation_strategy/subsystem_focus/focus_and_region_navigation_spec.md - Canonical focus authority and region navigation contract.
• graphshell_docs/implementation_strategy/viewer/viewer_presentation_and_fallback_spec.md - Canonical viewer presentation, fallback, and degraded-state contract.
• graphshell_docs/implementation_strategy/viewer/node_lifecycle_and_runtime_reconcile_spec.md - Canonical lifecycle/reconcile contract for Active/Warm/Cold/Tombstone and RuntimeBlocked behavior.
• graphshell_docs/implementation_strategy/viewer/webview_lifecycle_and_crash_recovery_spec.md - Canonical runtime contract for webview attach/detach/crash/recovery behavior.
• graphshell_docs/implementation_strategy/aspect_control/settings_and_control_surfaces_spec.md - Canonical settings/history/control-surface contract.
• graphshell_docs/implementation_strategy/aspect_control/settings_and_permissions_spine_spec.md - Five-scope hierarchy for layered settings and permission grants (default → persona → graph → view/tile → pane), libcosmic-config-shape storage, narrowing-only permission rule, Servo-aligned web-permission boundary, persona-supersedes-profile migration. Data layer underneath the settings_and_control_surfaces_spec UI layer.
• graphshell_docs/implementation_strategy/aspect_render/2026-04-30_renderer_and_host_refactor_plan.md - Five directional decisions from the 2026-04-30 architectural review: (1) Vello for canvas, WebRender for web/document tiles, don't rely on Servo/WebRender stabilization for fundamentals; (2) Wry + upstream Servo + smolnet (middlenet) as the application-fundamentals path right now; (3) middlenet refactor from Blitz-top + webrender-wgpu to Stylo + Taffy + Parley + Vello (all Linebender + Servo-component crates, no WebRender dependency); (4) EmbeddedHost render-mode audit + retirement (replaced by plain iced widget trees for tool/diagnostic panes); (5) decomposition target lowered from 600 → 500 LOC for portable-crate files. Reader modes use the middlenet stack to render extracted Servo-page content.
• graphshell_docs/implementation_strategy/aspect_render/theme_and_tokens_spec.md - Token-based theming for Graphshell. Five token categories (color, typography, density, motion, elevation), GraphshellTheme as Application::Theme, hand-rolled gs::* widget consumption, libcosmic-theme name alignment, cosmic-time animation hook keyed on motion tokens, WCAG 2.2 AA contrast + focus + target-size encoded in defaults. Resolves through the settings spine; surface specs reference this for tokens.
• graphshell_docs/implementation_strategy/system/graphshell_net_spec.md - graphshell-net subsystem. Unifying boundary for Graphshell-originated outbound network traffic: downloads, uploads, prefetch / DNS prefetch / preconnect, push notifications, provider HTTP (URL completion / search / import), agent LLM traffic, mod traffic. Single policy layer for permission gating (per the spine), scope tracking, transport trust verification, audit logging, cancellation. Servo and Wry retain their own per-page networks; this subsystem covers everything else. NetIntent satisfies the idempotence + replay contract.
• graphshell_docs/implementation_strategy/system/system_architecture_spec.md - Top-level system architecture and layer decomposition.
• graphshell_docs/implementation_strategy/system/register_layer_spec.md - Register layer as a system component.
• graphshell_docs/implementation_strategy/system/registry_runtime_spec.md - RegistryRuntime composition-root contract.
• graphshell_docs/implementation_strategy/system/control_panel_spec.md - ControlPanel async coordination contract.
• graphshell_docs/implementation_strategy/system/signal_bus_spec.md - SignalBus / signal-routing contract.
• graphshell_docs/implementation_strategy/system/register/SYSTEM_REGISTER.md - Register hub/index and historical implementation guide.
• graphshell_docs/implementation_strategy/system/2026-03-12_workspace_decomposition_and_renaming_plan.md - GraphWorkspace god-struct decomposition: split into DomainState (graph truth), GraphViewRuntimeState (per-view physics/culling/egui), WorkbenchSessionState (tile tree, arrangement), ChromeUiState (palette, search). Includes arrangement reconciler entrypoint (ArrangementSnapshot/ArrangementGraphDelta), intent handler phasing (4 phase-handler functions), and cache cleanup consolidation (on_node_deleted).
• graphshell_docs/implementation_strategy/system/2026-03-05_cp4_p2p_sync_plan.md - CP4 ControlPanel integration plan: p2p_sync_worker supervision, ApplyRemoteDelta/MarkPeerOffline intent variants, version vector persistence, reducer handling, and done gates.
• graphshell_docs/implementation_strategy/system/2026-03-05_network_architecture.md - Network protocol layer assignments: iroh (Coop/Device Sync transport), libp2p (Verse swarm), Nostr (identity/social/event bus). Covers public profile/follows, DMs, relay posture, Blossom, NIP-72/29 as Verse primitives, Nostr mod plugin surface, and iroh/libp2p/Nostr interoperability notes.
• graphshell_docs/implementation_strategy/system/2026-03-06_foundational_reset_implementation_plan.md - Active foundational reset execution plan. Tracks landed CLAT progress, remaining state-layer work, command/planner follow-ons, and verification gates.
• graphshell_docs/implementation_strategy/system/2026-03-06_reducer_only_mutation_enforcement_plan.md - Migration plan from trusted-writer boundary to compiler-enforced reducer-only graph mutation, including GraphMutation staging, replay alignment, side-effect isolation, and acceptance gates.
• graphshell_docs/implementation_strategy/system/2026-04-23_execution_isolation_and_worker_runtime_plan.md - Cross-cutting execution taxonomy and worker-runtime plan: main-thread host authority, supervised host workers, guest/sandbox runtimes, engine-owned process models, and external helper processes. Aligns Servo multiprocess, AsyncSpawner, WASM guest runtime direction, and browser-host Web Worker realization.
• graphshell_docs/implementation_strategy/system/register/protocol_registry_spec.md - Registry spec family starts here; protocol resolution and handler floor.
• graphshell_docs/implementation_strategy/subsystem_mods/SUBSYSTEM_MODS.md - Canonical Mods subsystem policy authority: built-in/native/WASM split, capability boundaries, and lifecycle ownership.
• graphshell_docs/implementation_strategy/subsystem_mods/mod_lifecycle_integrity_spec.md - Canonical lifecycle-integrity contract for mod admission, activation ordering, rollback/quarantine, unload, and diagnostics obligations across native and future WASM mods.
• nostr_docs/implementation_strategy/nostr_core_registry_spec.md - Canonical NostrCore provider profile: capability IDs, diagnostics channel descriptors, and initial native ModManifest shape. (moved to nostr_docs)
• nostr_docs/implementation_strategy/2026-03-10_nostr_nip_completion_plan.md - Phased plan for NIP-19/21/02/05/11/25/51/65/17 coverage; dependency order and crate strategy for completing the Nostr client layer. (moved to nostr_docs)
• graphshell_docs/implementation_strategy/workbench/ - Workbench specs and workbench-specific plans.
• graphshell_docs/implementation_strategy/graph/ - Graph domain specs and graph-specific plans; use canvas for the rendered surface terminology within those docs.
• graphshell_docs/implementation_strategy/viewer/ - Viewer specs and viewer/backend plans.
• graphshell_docs/implementation_strategy/system/ - System-level specs, registry architecture, and register component docs.
• graphshell_docs/implementation_strategy/subsystem_history/ - History subsystem specs: traversal, node navigation, node audit, temporal replay, unified architecture plan, and mixed-timeline contract.
• graphshell_docs/implementation_strategy/subsystem_history/2026-04-17_graph_memory_architecture_note.md - Current graph-memory architecture note: history-tree lineage, Entry/Visit/Owner/Binding substrate, snapshot/persistence shape, and the boundary to future graph-facing hotspot/overlap projections.
• graphshell_docs/implementation_strategy/subsystem_history/2026-04-21_graph_runtime_projection_layer_plan.md - Completed plan for Graph Cartography / GC, the §8.1 graph-facing runtime projection layer from the graph-memory architecture note. Defines the workspace-scoped aggregate layer over substrate + live graph + WAL that fills Navigator projection pipeline scorer / parent-picker / annotation slots. Names substrate §8.3 prerequisites (workspace-global instantiation, opaque EntryKey, real X), freezes the v1 aggregate/cache inventory, splits deterministic aggregates from learned-affinity caches, defers agent prediction to AgentRegistry, forbids a shadow BehaviorDerived edge taxonomy, and declares LocalOnly/DeviceSync/Shared privacy scope per aggregate/cache. Companion to the Navigator projection pipeline spec.
• graphshell_docs/implementation_strategy/subsystem_history/2026-04-02_bookmarks_import_plan.md - Current bookmark-import plan: imported provenance/import-record integration, bookmark-folder semantics, and ActionRegistry-backed command entry.
• graphshell_docs/implementation_strategy/subsystem_history/2026-04-02_browser_history_import_plan.md - Current browser-history import plan: imported-data seeding without violating live traversal/history authority.
• graphshell_docs/implementation_strategy/social/2026-04-12_host_abstractions_plan.md - Protocol-Agnostic P2P Graph Views & Host Abstractions Plan: transition from unified semantic protocol to host-first browser, including Identity Ring, Git-like persistence, Verso canvas sync, and host-side storage capability boundaries for private replication versus shared-service durability.

• graphshell_docs/design/KEYBINDINGS.md - Keyboard interaction reference.
• graphshell_docs/design/command_semantics_matrix.md - Canonical D1 command semantics matrix across keyboard, palette, radial, toolbar, and omnibar surfaces.
• graphshell_docs/design/2026-03-10_command_keybinding_accounting_plan.md - Gap analysis and phased plan for aligning command matrix, keybinding docs, and ActionRegistry; establishes C1–C4 usability work sequence post-Sector-H/G.
• graphshell_docs/design/surface_behavior_spec.md - Canonical D3 surface behavior policy for scroll, overflow, resize, empty/loading/error states, and floating lifecycle.
• graphshell_docs/design/accessibility_baseline_checklist.md - Canonical D4 WCAG 2.2 A/AA checklist by surface, with initial screen-reader test matrix.
• graphshell_docs/design/ux_telemetry_plan.md - Canonical D5 UX telemetry metric register with diagnostics/probe mapping and baseline targets.
• graphshell_docs/testing/2026-03-02_accessibility_closure_bundle_audit_301.md - #301 closure evidence for reduced-motion guardrails, contrast/target-size audits, and keyboard-trap validation.
• graphshell_docs/testing/2026-03-02_graph_canvas_keyboard_focus_audit_298.md - #298 closure evidence for deterministic graph keyboard traversal and graph canvas accessibility naming baseline.

• graphshell_docs/testing/test_guide.md - Active testing entry guide covering baseline commands, scope rules, and acceptance checks.
• graphshell_docs/testing/scenario_back_forward_burst.html - Navigation scenario fixture.
• graphshell_docs/testing/scenario_hash_change.html - Hash change scenario fixture.
• graphshell_docs/testing/scenario_spa_pushstate.html - SPA pushState fixture.
• graphshell_docs/testing/scenario_window_child.html - Child window scenario fixture.
• graphshell_docs/testing/scenario_window_open.html - window.open scenario fixture.
• graphshell_docs/testing/delegate_trace_back_forward_burst_http.log - Delegate trace log.
• graphshell_docs/testing/delegate_trace_hash_change_http.log - Delegate trace log.
• graphshell_docs/testing/delegate_trace_hash_change.log - Delegate trace log.
• graphshell_docs/testing/delegate_trace_redirect.log - Delegate trace log.
• graphshell_docs/testing/delegate_trace_spa_pushstate_http.log - Delegate trace log.
• graphshell_docs/testing/delegate_trace_spa_pushstate.log - Delegate trace log.
• graphshell_docs/testing/delegate_trace_window_open_http.log - Delegate trace log.

Verso mod: web rendering (Servo + Wry) and bilateral P2P sync (Tier 1). See DOC_POLICY.md for boundary definition.

• verso_docs/technical_architecture/VERSO_AS_PEER.md - Verso mod: web capability (Servo + wry viewers, protocol handlers) and Verso peer agent (Ed25519 identity, SyncWorker, pairing, graph/workbench context sharing).
• verso_docs/technical_architecture/VERSO_SERVO_ARCHITECTURE.md - Verso/Servo integration architecture.

• verso_docs/implementation_strategy/2026-02-22_verse_implementation_strategy.md - Verso/Verse implementation strategy and Tier 1 / Tier 2 split framing.
• verso_docs/implementation_strategy/2026-02-23_verse_tier1_sync_plan.md - Canonical Verso Tier 1 sync plan (iroh transport, sync units, pairing/sync phases, deterministic sync-logic simulator matrix).
• verso_docs/implementation_strategy/2026-02-25_verse_presence_plan.md - Post-Phase-5 collaborative presence plan: ghost cursors, remote selection, follow mode, and presence stream policy.
• verso_docs/implementation_strategy/coop_session_spec.md - Canonical co-op session authority: host-led co-presence, roles, sharing, approval workflow, snapshot, session UI, intent surface, flock model (§14), Nostr identity (§15), and wallet integration (§16).
• verso_docs/implementation_strategy/2026-03-27_session_capsule_ledger_plan.md - Session Capsule Ledger: WASM-safe portable session archive format (SessionCapsule, SessionLedger, ArchiveReceipt), CID addressing, AES-256-GCM encryption, UCAN delegation, and Verso bilateral sync integration. 5-slice implementation plan A.1–A.5.
• verso_docs/implementation_strategy/2026-03-28_gemini_capsule_server_plan.md - Small protocol capsule servers (Gemini/Gopher/Finger): serve Graphshell content and personal profiles over TCP. SimpleDocument ↔ text/gemini/Gophermap/plain-text serializers, content routers, GraphIntent wiring for all three protocols.
• verso_docs/implementation_strategy/2026-03-28_cable_coop_minichat_spec.md - Cable wire protocol as co-op minichat substrate: identity/cabal-key derivation, post type mapping, moderation integration (host as admin seed + subjective guest layer), in-memory ephemeral store, iroh transport (skip Noise), Comms lane positioning, 4-phase rollout.
• verso_docs/implementation_strategy/PHASE5_STEP5.1_COMPLETE.md - Phase 5 Step 5.1 completion record.
• verso_docs/implementation_strategy/PHASE5_STEP5.2_COMPLETE.md - Phase 5 Step 5.2 completion record.
• verso_docs/implementation_strategy/PHASE5_STEP5.3_COMPLETE.md - Phase 5 Step 5.3 completion record.

• verso_docs/research/2026-03-28_permacomputing_alignment.md - Permacomputing alignment: 10-principle audit, gaps (resource awareness, intentional forgetting, constrained hardware, small-web publishing, content portability), curated project index (Cable, Uxn, Coalescent Computer, Solar Protocol, snac, Cerca), and design posture summary.
• verso_docs/research/2026-03-28_smolnet_follow_on_audit.md - Suitability audit for post-Gemini/Gopher/Finger smallnet follow-ons: admission bar for native Verso support, capability-family split (SimpleDocument bridge boundary, discovery vs messaging vs document lanes), and recommendations for Titan, Spartan, Misfin, Nex, and Guppy.
• verso_docs/research/2026-03-28_smolnet_dependency_health_audit.md - Dependency-health rubric for follow-on smallnet protocol crates: when to prefer local implementations, when external Rust crates may be justified, and what still requires external ecosystem validation for Titan, Spartan, Misfin, Nex, and Guppy.
• verso_docs/research/2026-04-16_smolnet_capability_model_and_scroll_alignment.md - Broader smolnet capability-model note: transport-plus-format adapter architecture, capability-family routing, Tier A/B/C/D protocol priorities, messaging/data-transfer posture, and why Scroll is strategically interesting because of its UDC alignment with Verse.

---

Verse mod: public decentralized community network (Tier 2, long-horizon research). Not a Phase 5 dependency.

• verse_docs/technical_architecture/VERSE_AS_NETWORK.md - Verse as the optional community-scale network layer, with explicit boundary against Verso bilateral sync/co-op and Comms hosted surfaces.
• verse_docs/technical_architecture/2026-02-23_verse_tier2_architecture.md - Long-horizon Tier 2 architecture: dual transport, VerseBlob, FLora, Proof of Access, crawler economy, and open research questions.
• verse_docs/technical_architecture/2026-04-17_verse_graph_contribution_protocol_v0_1.md - Current canonical Verse protocol spec: graph-native contributions, Entry/Visit/Owner projection boundary, attestation-aware aggregation, and community ranking over accepted graph contributions.
• verse_docs/technical_architecture/2026-03-05_verse_nostr_dvm_integration.md - How Nostr (NIP-72 community surface, NIP-90 DVMs), FLora checkpoints, distributed indices, and Proof of Access economics compose: feed curation, context-aware traversal suggestions, graph node summarisation, Lightning/receipt tokenomics, and Tier 2 rollout sequence.
• verse_docs/technical_architecture/2026-03-05_verse_economic_model.md - Coherent economic model: no native Verse token (sats for compute, FIL for storage, reputation for governance); storage staking/bonds; sats operational budget; FIL treasury; full browsing→review→hosting→compute→settlement value loop; contributor/reviewer/bootstrap staking types; anti-plutocracy guarantees; open problems.

• verse_docs/implementation_strategy/self_hosted_model_spec.md - Self-hosted model spec: capability contracts, model/engram classification, cooperative multi-model execution, mini-adapter flow, and UI-facing behavior contracts.
• verse_docs/implementation_strategy/lineage_dag_spec.md - Canonical lineage graph structure shared by Engrams and FLora checkpoints: ancestry links, append-only chain commitments, traversal policy, trust filtering, revocation semantics, and lineage-shaping operations.
• verse_docs/implementation_strategy/2026-03-09_agent_wal_and_distillery_architecture_plan.md - Agent write-ahead log (AWAL) and Distillery pipeline: intelligence-native durability layer bridging graph/history storage to Verse/FLora artifacts; canonical experience unit; typed memory, retrieval, evaluation, and engram outputs.
• verse_docs/implementation_strategy/2026-03-28_decentralized_storage_bank_spec.md - Decentralized storage bank: peer storage economy for Verse Tier 2; storage credit model, placement policy, redundancy/health/repair protocol, fallback hierarchy (community → bilateral → self-hosting), and §14 design rationale covering retroactive credit, long-tail death problem, and lazy payment.
• verse_docs/implementation_strategy/2026-04-06_sync_badge_verse_controls_plan.md - Sync badge → Verse controls expansion: interaction contract for the ambient sync status badge, Verse connection state surface, and progressive disclosure toward community controls.
• verse_docs/implementation_strategy/2026-02-26_intelligence_memory_architecture_stm_ltm_engrams_plan.md - STM/LTM, MemoryExtractor/MemoryIngestor, engram storage, and intelligence memory plumbing.
• verse_docs/implementation_strategy/engram_spec.md - Canonical Engram / TransferProfile schema: envelope, memory classes, validation classes, redaction, trust, and FLora submission rules.
• verse_docs/implementation_strategy/verseblob_content_addressing_spec.md - Canonical VerseBlob schema and content-addressing policy: CID defaults, attachment model, retrieval rules, and safety limits.
• verse_docs/implementation_strategy/flora_submission_checkpoint_spec.md - Canonical FLora flow: engram submission manifests, review, checkpoints, reward hooks, and anti-abuse policy.
• verse_docs/implementation_strategy/proof_of_access_ledger_spec.md - Canonical receipt and accounting model: off-chain ledger, reputation, epoch settlement, and optional payout channels.
• verse_docs/implementation_strategy/community_governance_spec.md - Canonical community policy model: roles, quorum, treasury controls, moderation, and appeals.
• verse_docs/implementation_strategy/self_hosted_verse_node_spec.md - Canonical private-by-default Verse node model: service surfaces, transport boundaries, quotas, and budget controls.
• verse_docs/research/VERSE.md - Original tokenization and peer-role vision (speculative research).
• verse_docs/research/SEARCH_FINDINGS_SUMMARY.md - Research and source synthesis.
• verse_docs/research/2026-02-22_aspirational_protocols_and_tools.md - Protocol ecosystem survey (IPFS, ActivityPub, Nostr, Gemini, Matrix) and crate index. Reference for Tier 2 and future protocol mod work.
• verse_docs/research/2026-02-23_storage_economy_and_indices.md - Speculative research on Proof of Access economy and composable Index Artifacts (Tier 2 research input).
• verse_docs/research/2026-04-13_storage_system_comparison_for_verse.md - Comparative analysis of Syncthing, Tahoe-LAFS, Storj, and Filecoin against Verse's storage-bank direction; recommends a hybrid model: Syncthing-like bilateral storage, Tahoe-like opaque encrypted hosting, Storj-like audit/accounting, and a much lighter-than-Filecoin first implementation.
• verse_docs/research/2026-02-23_modern_yacy_gap_analysis.md - Gap analysis for decentralized search: Index Artifact format (tantivy segments), local vs. remote query, crawler bounty economy (Tier 2 research input).
• verse_docs/research/2026-03-28_libp2p_nostr_synergy_for_verse.md - Control-plane / data-plane analysis: Nostr as discovery/governance/social layer, libp2p as bulk content transfer. Covers community bootstrap, GossipSub trust scoring, NIP-29 swarm gating, dual-rail publication, and embedded relay as unified service endpoint.
• verso_docs/research/2026-03-28_rss_feed_graph_model.md - RSS/Atom as consumption + publication capability: feed graphlet chain topology, capacity eviction, post harvesting with ghost node proxies, workbench opening semantics, Atom capsule server, feed-rs/atom_syndication crates, feed poll worker.

---

NostrCore mod: Nostr protocol integration.

• nostr_docs/technical_architecture/nostr_relay_spec.md - Embedded Nostr relay server: three operating modes (Personal/Flock/Community), fjall event store schema, NIP-01/09/11/42/29 coverage, NostrCore ownership model, GraphIntent wiring, and rollout plan.

• nostr_docs/implementation_strategy/2026-03-05_nostr_mod_system.md - NostrCore native mod system: capability surface, relay infrastructure, event routing, and NIP baseline.
• nostr_docs/implementation_strategy/2026-03-10_nostr_nip_completion_plan.md - Phased plan for NIP-19/21/02/05/11/25/51/65/17 coverage; dependency order and crate strategy for completing the Nostr client layer.
• nostr_docs/implementation_strategy/nostr_core_registry_spec.md - Canonical NostrCore provider profile: capability IDs, diagnostics channel descriptors, and initial native ModManifest shape.
• nostr_docs/implementation_strategy/nostr_runtime_behavior_spec.md - Nostr runtime behavior contract: relay lifecycle, event dispatch, signing boundary, and NIP-44 DM handling.

---

MatrixCore mod: Matrix room protocol for durable room membership and shared-space context.

• matrix_docs/implementation_strategy/2026-03-17_matrix_core_adoption_plan.md - Phase-by-phase execution plan for MatrixCore: session lifecycle, room projection, allowlisted graph events, and optional Nostr bridge affordances.
• matrix_docs/implementation_strategy/2026-03-17_matrix_event_schema.md - Concrete graphshell.room.* event schema for Matrix-backed rooms: payload families, validation rules, and reducer/workbench routing boundaries.
• matrix_docs/implementation_strategy/2026-03-17_matrix_layer_positioning.md - Places Matrix as the durable room contextual substrate within the three-context + two-fabric network model; defines room hosting gradient, cross-carrying rules, and concept resurfacing.
• matrix_docs/implementation_strategy/2026-03-17_matrix_core_type_sketch.md - Rust-facing type sketch for MatrixCoreRegistry, supervised worker commands, normalized Matrix events, and bounded proposal routing.
• matrix_docs/implementation_strategy/matrix_core_registry_spec.md - Canonical MatrixCore provider profile: capability IDs, room model, and diagnostics channel descriptors.

---

Graphshell social-domain docs cover hosted communication surfaces and related shell-side coordination rules without absorbing protocol authority from Verso, MatrixCore, NostrCore, or Verse.

• graphshell_docs/implementation_strategy/social/COMMS_AS_APPLETS.md - Canonical positioning note for Comms as a Graphshell-hosted applet/surface family spanning Matrix rooms, Nostr social lanes, and Verso bilateral co-op/chat surfaces.
• graphshell_docs/implementation_strategy/social/comms/2026-04-09_irc_public_comms_lane_positioning.md - Positions IRC as a public Comms lane for smolweb/community spaces: narrow first slice, hosted applet boundary, link capture into Graphshell, and opt-in retention only.
• graphshell_docs/implementation_strategy/social/profile/PROFILE.md - Canonical social profile surface spec: host-side profile composition, publication lanes, and boundary between public identity profile vs GraphshellProfile app/workflow configuration.
• graphshell_docs/implementation_strategy/social/profile/CAPSULE_PROFILE.md - Canonical publication mapping spec from social profile cards into concrete Nostr kind 0, Finger text, and Gemini/Gopher capsule profile documents.
• graphshell_docs/implementation_strategy/social/profile/2026-03-28_social_profile_type_sketch.md - Rust-facing type sketch for SocialProfileCard, CapsuleProfile, disclosure policy carriers, GraphshellProfile associations, and secret-provider references.
• graphshell_docs/implementation_strategy/social/profile/serve_profile_on_all_protocols_spec.md - Execution contract for ServeProfileOnAllProtocols: lane fanout, reducer/workbench/runtime boundary split, per-lane receipts, and minimum guard tests.
• graphshell_docs/implementation_strategy/social/contacts/CONTACTS.md - Canonical contacts (flock) spec: ContactEntry/ContactTag/UserIdentity data model, opt-in suggestion flow from co-op sessions and Cable cabals, fjall schema, cross-feature usage (co-op approved-guest list, Nostr relay Flock allow-list, Cable cabal invites), and 4-phase rollout.

• archive_docs/checkpoint_2026-01-29/
• archive_docs/checkpoint_2026-02-01/
• archive_docs/checkpoint_2026-02-04/
• archive_docs/checkpoint_2026-02-09/
• archive_docs/checkpoint_2026-02-10/
• archive_docs/checkpoint_2026-02-11/
• archive_docs/checkpoint_2026-02-12/
• archive_docs/checkpoint_2026-02-14_no_legacy_cleanup/
• archive_docs/checkpoint_2026-02-16/
• archive_docs/checkpoint_2026-02-17/
• archive_docs/checkpoint_2026-02-19/
• archive_docs/checkpoint_2026-02-20/
• archive_docs/checkpoint_2026-02-23/ — registry_migration_plan.md, 2026-02-23_registry_architecture_critique.md (consolidated into 2026-02-22_registry_layer_plan.md)
• archive_docs/checkpoint_2026-02-24/ — consolidated-plan redirects: 2026-02-24_input_surface_polish_plan.md, 2026-02-24_workspace_routing_polish_plan.md, 2026-02-24_sync_logic_validation_plan.md; GRAPHSHELL_P2P_COLLABORATION.md (pre-intent-model P2P design, superseded by verso_docs/technical_architecture/VERSE_AS_NETWORK.md and the Tier 1 sync plan)
• archive_docs/checkpoint_2026-02-27/ — archived stale active docs: technical_architecture/DEVELOPER_GUIDE.md, technical_architecture/CODEBASE_MAP.md, testing/VALIDATION_TESTING.md; superseded by active codebase_guide.md and test_guide.md.
• archive_docs/checkpoint_2026-03-01/ — bridge spike receipts and embedder-debt records for #180 and #183.
• archive_docs/checkpoint_2026-03-05/ — 2026-03-05_camera_navigation_fix_postmortem.md: root-cause and fix record for longstanding camera pan/zoom bug (dead metadata slot + every-frame fit reset).
• archive_docs/checkpoint_2026-03-07/ — foundational reset receipt consolidation: archived 2026-03-06_foundational_reset_architecture_vision.md, 2026-03-06_foundational_reset_migration_governance.md, 2026-03-06_foundational_reset_demolition_plan.md, and 2026-03-06_clat_domain_state_core_extraction.md after consolidating active policy/progress into system_architecture_spec.md, 2026-03-06_foundational_reset_implementation_plan.md, and 2026-03-06_foundational_reset_graphbrowserapp_field_ownership_map.md.
• archive_docs/checkpoint_2026-03-10/ — archived graphshell_docs/implementation_strategy/viewer/2026-02-26_composited_viewer_pass_contract.md after consolidating active compositor contract authority into implementation_strategy/PLANNING_REGISTER.md §0 and implementation_strategy/aspect_render/frame_assembly_and_compositor_spec.md; retained Appendix A future-work ideas live in PLANNING_REGISTER.md §0.10.
• archive_docs/checkpoint_2026-03-18/ — completed registry/sector plans (system/2026-02-22_registry_layer_plan.md, system/register/ Sectors A/D/F), stabilization progress receipt, C+F backend bridge receipt, foundational-reset GraphBrowserApp field ownership snapshot, and superseded wgpu/WebRender deferred strategy docs (aspect_render/2026-02-27_egui_wgpu_custom_canvas_migration_strategy.md, aspect_render/2026-03-01_webrender_readiness_gate_feature_guardrails.md).
• archive_docs/checkpoint_2026-03-27/ — archived completed graphshell_docs/technical_architecture/ARCHITECTURAL_CONCERNS.md after its open items were resolved and its historical references were superseded by active specs and overview docs.
• archive_docs/checkpoint_2026-04-01/ — archived completed node-tagging plan history: graphshell_docs/implementation_strategy/graph/2026-02-20_node_badge_and_tagging_plan.md and graphshell_docs/implementation_strategy/graph/2026-03-31_node_badge_and_tagging_follow_on_plan.md; active authority remains graphshell_docs/implementation_strategy/graph/node_badge_and_tagging_spec.md.
• archive_docs/checkpoint_2026-04-02/ — archived split-note compatibility redirects and superseded implementation-plan history, including graphshell_docs/implementation_strategy/subsystem_history/2026-02-11_bookmarks_history_import_plan.md after splitting it into the active bookmark-import and browser-history-import plans.
• archive_docs/checkpoint_2026-04-03/ — archived graphshell_docs/implementation_strategy/viewer/2026-02-11_clipping_dom_extraction_plan.md as the landed clipping execution-slice record after splitting remaining viewer-lane work into the active graphshell_docs/implementation_strategy/viewer/2026-04-03_clipping_viewer_follow_on_plan.md.
• archive_docs/checkpoint_2026-04-06/ — archived graphshell_docs/implementation_strategy/subsystem_ux_semantics/2026-03-23_navigator_host_runtime_naming_plan.md after the host-oriented runtime naming migration landed in workbench host state, persistence, and immediate desktop UI consumers; active chrome/host semantics remain in graphshell_docs/implementation_strategy/subsystem_ux_semantics/2026-03-13_chrome_scope_split_plan.md and the Navigator / Shell / Workbench specs.
• archive_docs/checkpoint_2026-04-15/ — archived 8 completed implementation plans: system/2026-03-08_graph_app_decomposition_plan.md (all stages + 8 Stage 5 cleanup slices landed; scope-based selection store is sole authority), aspect_render/2026-03-08_render_mod_decomposition_plan.md (exit target met: 1,342 lines), workbench/2026-04-11_graph_tree_egui_tiles_decoupling_follow_on_plan.md (complete 2026-04-11), graph/2026-03-05_hybrid_graph_view_overview_atlas_plan.md (closed 2026-04-01; authority in multi_view_pane_spec.md and NAVIGATOR.md), system/register/2026-03-08_sector_h_signal_infrastructure_plan.md (SignalBus with 5 topics, typed signals, async observers), system/register/2026-03-08_sector_c_identity_verse_plan.md (Ed25519 + secp256k1 + NIP-46 + relay backend; follow-on: browser-signer UX), system/register/2026-03-08_sector_e_workbench_surface_plan.md (WorkbenchSurfaceRegistry + WorkflowRegistry live; follow-on: transaction/rollback semantics), system/register/2026-03-08_sector_g_mod_agent_plan.md (ModRegistry + AgentRegistry + ThemeRegistry struct-complete; follow-on: WASM host, mod-provided agents, OS-theme detection).
• archive_docs/checkpoint_2026-04-23/ — archived completed producing/implementation plans: graphshell_docs/implementation_strategy/navigator/2026-04-21_navigator_projection_pipeline_plan.md after the canonical navigator_projection_spec.md landed, and graphshell_docs/implementation_strategy/shell/2026-04-22_m5b_trait_extraction_plan.md after trait extraction landed and its cross-cutting worker-runtime findings were folded into graphshell_docs/implementation_strategy/system/2026-04-23_execution_isolation_and_worker_runtime_plan.md.