diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..6fccbcb
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,37 @@
+# Model exploration and authored views
+
+Language for understanding a SysML project and choosing how to inspect its content. These terms distinguish model content from its storage and graphical presentation.
+
+## Language
+
+**Source file**:
+An authoring document containing SysML declarations. A file boundary is not necessarily a package or system boundary.
+_Avoid_: Model, system, diagram when referring to a file.
+
+**Project model**:
+The logical model resolved from a project's source documents together. It can contain several systems, reusable definitions and packages.
+_Avoid_: Full system when referring to all project content.
+
+**Applied model**:
+The last accepted, validated model revision. Unapplied draft source can differ from the source of this revision.
+
+**Scope**:
+The model content being inspected, such as the project, a package or a particular system usage. A definition and its individual usages are distinct subjects.
+
+**Representation**:
+The graphical form used to inspect a scope, such as an overview or internal structure. Representation choice does not define the underlying system.
+_Avoid_: Named view when only the graphical form is meant.
+
+**Exploration**:
+A temporary browsing context consisting of a scope and representation, without requiring an authored SysML view declaration.
+_Avoid_: View usage, saved view.
+
+**Named view**:
+An authored SysML view usage specifying a repeatable presentation of model content through its declared scope, exposure, filters and representation semantics.
+_Avoid_: Diagram tab, temporary exploration.
+
+**Diagram presentation**:
+The visual arrangement of symbols for a particular graphical context. Geometry does not establish semantic ownership, connectivity or usage identity.
+
+**Camera**:
+The viewport position and zoom through which a diagram is inspected. Camera movement does not change model-space geometry.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9dd6706..9d1ecb6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
# Contributing
-Start with [current capabilities](docs/capabilities.md), [next steps](docs/next-steps.md), [architecture](docs/architecture/README.md) and the [design system](docs/design-system.md). The current milestone is a small assembly that can be understood and edited from source or diagram while preserving layout and unrelated source content. Reviewed part renames, bounded source-edit preservation and typed part/connection creation now share the transaction path. Start with their [acceptance criteria](docs/next-steps.md#21-preserve-layout-through-reviewed-part-renames) and [authoring limits](docs/architecture/graphical-authoring.md) before extending the next everyday-editing tasks.
+Start with the [documentation index](docs/README.md), [current capabilities](docs/capabilities.md) and [next steps](docs/next-steps.md). The source/assembly editing workflow and explicit entry shell are implemented within their documented limits. Automatic read-only model exploration is the next feature priority; follow its [acceptance criteria](docs/architecture/model-exploration.md#first-implementation-slice). Before extending semantic editing, read the [authoring limits](docs/architecture/graphical-authoring.md) and [identity policy](docs/architecture/identity-reconciliation.md).
## Get started
diff --git a/README.md b/README.md
index 868963e..508855c 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
-
+
-
SysML v2 View Editor
+
OpenMBEE View Editor
Work with SysML v2 source and diagrams in your browser.
@@ -31,7 +31,7 @@
> **Sandbox stage** — Actively iterating on the design and implementation. Features, interfaces and workflows may change. Not intended for production use.
-SysML v2 View Editor brings source editing, named model views and reviewed graphical authoring into one local workbench. Open a multi-file model, inspect its structure and connections, review supported edits, then download the source and compatible diagram positions as one project.
+OpenMBEE View Editor brings source editing, named model views and reviewed graphical authoring into one local workbench. Open a multi-file model, inspect its structure and connections, review supported edits, then download the source and compatible diagram positions as one project.
**Source owns model semantics. Presentation owns geometry.** Renaming a part or connecting ports produces a reviewed source transaction; moving a symbol changes its position. The application runs locally in browser workers and requires no application backend.
@@ -72,18 +72,22 @@ npm run dev -- --host 127.0.0.1
Open the URL printed by Vite. The first dev/build verifies and prepares checksum-pinned browser engines. It needs network access, `tar` and disk space for the Go build cache. Linux x64 can download the pinned Go 1.25.11 toolchain into ignored `sandbox/`; on other platforms, set `SYSML_GO` to that Go version's binary. Later runs verify and reuse prepared assets. See [engine preparation](engine-bridge/README.md).
-### 2. Explore the startup model
+Vite excludes generated `sandbox/` contents and prepared `static/vendor/` binaries from development watching; app sources remain watched. If an older dev process reported `ENOSPC` from those directories, restart it with the current configuration.
-**Smart air workshop** opens automatically in Diagram mode. Its nine source files and fourteen named views cover reusable definitions, specialization, attributes, constraints, requirements, actions, states, use cases, sequences and geometry.
+### 2. Open the app or try an example
+
+The landing page offers **Open app** and **Try an example**. `/app` opens a project launcher with **New project**, **Open files or project**, **Load example** and **Local recovery**. No model loads implicitly. New projects stay marked modified until downloaded.
+
+Choose **Load example** to open **Smart air workshop** in Diagram mode. Its nine source files and fourteen named views cover reusable definitions, specialization, attributes, constraints, requirements, actions, states, use cases, sequences and geometry.
The starting **pneumatics** view shows the pump, tank, regulator, relief valve and pressure sensor, with thirteen ports and four connections:
-1. Select another named view in Explorer to explore its contents.
+1. Select another named view in Explorer or the diagram’s **Named view** selector to explore its contents.
2. Choose **Split** to see source beside the diagram; selecting a source file keeps the active view open.
3. Edit source and choose **Apply source**. Invalid drafts retain the previous applied model and appear in **Issues**.
4. Choose **Download project** to save your work before closing or reloading.
-Six startup views have partial structural/definition/tree rendering. The other eight evaluate through the engine and display an explicit unavailable-renderer message. The [model guide](examples/air-compressor/README.md) lists each view's current support.
+Six example views have partial structural/definition/tree rendering. The other eight evaluate through the engine and display an explicit unavailable-renderer message. The [model guide](examples/air-compressor/README.md) lists each view's current support.
### 3. Try graphical authoring
@@ -102,7 +106,7 @@ Open all `.sysml` files from one example folder together. Each project has its o
| Project | Explore |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| [Smart air workshop](examples/air-compressor/README.md) | A complete nine-file example spanning structure, requirements, behavior and geometry; the startup project |
+| [Smart air workshop](examples/air-compressor/README.md) | A complete nine-file example spanning structure, requirements, behavior and geometry; the built-in launcher example |
| [Nested assembly](examples/assembly/) | Nested ownership, repeated usages, inherited ports, a connection and reference notation; the focused authoring fixture |
| [Parts](examples/parts/), [ports](examples/ports/) and [packages](examples/packages/) | Shared definitions, usage contexts, conjugation, imports and exposure |
| [Requirements](examples/requirements/), [use cases](examples/use-cases/), [actions](examples/actions/), [states](examples/states/) and [sequences](examples/sequences/) | Source constructs and named views, including explicit unavailable-renderer cases |
@@ -127,6 +131,10 @@ React Flow draws the interactive diagrams and ELK supplies automatic layout. The
## Projects and workspace
+Use **Projects** to return to the launcher and **Resume project** to continue. The live workbench stays mounted while you browse the launcher or landing page, retaining source drafts, accepted history, selection and diagram state. A full reload starts at the launcher; existing browser recovery is offered explicitly. Landing and app share one appearance preference controller.
+
+Folder write-back, Flexo project/branch checkout and automatic diagrams for models without named views remain planned. Opening source imports copies; it does not connect to a folder or remote branch.
+
**Download project** saves one `.sysml-project.json`; **Open** accepts that bundle or multiple `.sysml` files. Downloads do not write back to the imported folder. **Local recovery** keeps one recovery copy in this browser using IndexedDB, including applied source, unapplied drafts, diagram positions and the active file/view. On reload, choose **Restore recovery** or **Discard recovery** before new work can replace that copy. The dialog can disable local saving or retry storage failures. Browser storage can be cleared; retain downloaded projects as portable backups. Restored work remains modified until downloaded. With saving enabled, returning to a clean project clears this session’s older recovery; a competing tab cannot silently overwrite a newer copy.
| Data | Where it lives |
@@ -168,34 +176,25 @@ npm run preview -- --host 127.0.0.1
Functional checks can use installed Chrome with `PLAYWRIGHT_BROWSER_CHANNEL=chrome npm run test:e2e -- --project=functional`. Visual comparisons always use bundled Chromium and reviewed platform-specific baselines. The browser suite starts its own fresh production server; port **4175** must be free. See [browser testing and baseline review](docs/testing.md).
+Production hosting must serve `index.html` for direct `/app` navigation while retaining normal asset paths; use the SPA fallback for your hosting provider. `/app/?example=1` is canonicalized to `/app` before the explicitly requested example opens, and reload does not repeat that opening action.
+
For example changes, run `npm run test:examples`; use `npm run examples:index` after updating the catalog. `npm run format` formats owned source and docs; `npm run lint` checks formatting and architectural imports. Keep temporary files, reports and captures under ignored `sandbox/`.
## Documentation
-| Guide | What you will find |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| [Capabilities](docs/capabilities.md) | Supported workflows and current limits |
-| [Architecture](docs/architecture/README.md) | Module ownership, engine boundaries and source transactions |
-| [Project format](docs/architecture/project-format.md) | Source, drafts, identity and presentation serialization |
-| [Graphical authoring](docs/architecture/graphical-authoring.md) | Reviewed creation/rename, command validation and failure behavior |
-| [Layout preservation](docs/architecture/identity-reconciliation.md) | Verified correspondence, bounded source edits and unsafe mappings |
-| [Workbench panels](docs/architecture/workbench-layout.md) | Resizing, focus, toolbar layout and browser preferences |
-| [Design system](docs/design-system.md) | Shared controls, typography, appearance and registry workflow |
-| [Testing](docs/testing.md) | Real-engine scenarios, visual comparisons and failure artifacts |
-| [Verification](docs/verification.md) | Local results, retained evidence and skipped coverage |
-| [Next steps](docs/next-steps.md) | Implemented milestones and planned work, including Flexo MMS integration |
+Start with the [documentation index](docs/README.md) for current capabilities, architecture contracts, design conventions, testing evidence and planned work. Engine preparation and provenance live in the [engine guide](engine-bridge/README.md); model fixtures and visualization targets live in the [example library](examples/README.md).
## Scope
This implementation supports a bounded source/structure editing workflow. It does not claim complete SysML v2 language, notation, execution or interchange conformance. Owned-port boundary notation, effective conjugated directions, behavior renderers and broader editing commands remain explicit gaps.
-Flexo MMS checkout and publishing are planned; the current workbench uses local project files. Read the [integration research](docs/research/openmbee-flexo-mms.md) and [roadmap](docs/next-steps.md#future-integrations-planned) for the proposed direction.
+Flexo MMS checkout and publishing are planned; the current workbench uses local project files. Read the [integration research](docs/research/openmbee-flexo-mms.md) and [roadmap](docs/next-steps.md#3-flexo-checkout-then-reviewed-publication) for the proposed direction.
## Contributing
The default branch, `develop`, holds ongoing sandbox work. Feature PRs target `develop`; releases and hotfixes follow the [Git Flow workflow](docs/git-workflow.md). `main` requires a code-owner approval and passing CI.
-Start with the [contribution guide](CONTRIBUTING.md), [architecture decisions](docs/decisions/0001-foundation.md) and the acceptance criteria in [next steps](docs/next-steps.md). Keep changes focused, preserve license/provenance notices and request approval before adding production dependencies. Use the [project repository](https://github.com/Open-MBEE/sysml_view_editor) for bugs and feature requests.
+Start with the [contribution guide](CONTRIBUTING.md), [architecture](docs/architecture/README.md) and the acceptance criteria in [next steps](docs/next-steps.md). Keep changes focused, preserve license/provenance notices and request approval before adding production dependencies. Use the [project repository](https://github.com/Open-MBEE/sysml_view_editor) for bugs and feature requests.
## Security
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..5df8c1b
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,37 @@
+# Documentation
+
+OpenMBEE View Editor is a sandbox browser workspace for SysML v2 source and named views. This index separates current behavior, implementation contracts and planned work. Setup and everyday use live in the [project README](../README.md).
+
+## Start here
+
+| Guide | Purpose |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| [Capabilities and limits](capabilities.md) | What the application supports today |
+| [Next steps](next-steps.md) | Current priorities and the gates for future work |
+| [Architecture](architecture/README.md) | Module ownership, engine boundaries and transaction rules |
+| [Design system](design-system.md) | Shared shadcn controls, themes and UI conventions |
+| [Testing](testing.md) | Running checks, reviewing baselines and diagnosing failures |
+| [Verification](verification.md) | Latest recorded results, regression evidence and coverage limits |
+| [Git workflow](git-workflow.md) | Branches, PR targets and release integration |
+
+## Implementation contracts
+
+| Guide | Purpose |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| [Application shell](architecture/application-shell.md) | Landing, launcher, navigation and session preservation |
+| [Workbench layout](architecture/workbench-layout.md) | Panels, toolbar alignment, model tree and editor lifetime |
+| [Source editing and recovery](architecture/source-assistance-recovery.md) | Draft queries, issue navigation and browser recovery |
+| [Structural views](architecture/structural-views.md) | Hierarchy, ports, connections and geometry projection |
+| [Graphical authoring](architecture/graphical-authoring.md) | Reviewed semantic commands and supported endpoint rules |
+| [Identity and layout preservation](architecture/identity-reconciliation.md) | Identity domains, verified edits and conservative invalidation |
+| [Project format](architecture/project-format.md) | Portable version-1 data and compatibility rules |
+
+## Planned work and research
+
+- [Model exploration](architecture/model-exploration.md): agreed behavior for browsing models without authored views; not implemented.
+- [Exploration engine investigation](research/automatic-exploration-contract.md): pinned renderer/WASM evidence and the next contract boundary.
+- [Flexo MMS integration](research/openmbee-flexo-mms.md): dated source research and unresolved interchange/concurrency gates; not implemented.
+
+Related sources: [domain glossary](../CONTEXT.md), [engine preparation and provenance](../engine-bridge/README.md), [example library](../examples/README.md), [contribution guide](../CONTRIBUTING.md).
+
+Keep current behavior in capabilities and owning contracts; put future acceptance criteria in the roadmap or exploration plan. Verification records observations, not promises. Superseded milestone narratives remain available in Git history rather than parallel archive documents. Local `sandbox/` evidence paths are ignored artifacts and may be absent from another checkout.
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 33a0ac2..6cd5a45 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -1,5 +1,7 @@
# Architecture
+See the [documentation index](../README.md) for the detailed implementation contracts and planned work.
+
One static browser application contains a framework-independent workspace and a React workbench. There is one npm project. Internal modules expose small interfaces; extraction into separately published packages requires a concrete second consumer.
## Ownership and direction
@@ -32,6 +34,8 @@ The [identity investigation](identity-reconciliation.md) compares real worker ou
## Views
+The [agreed exploration direction](model-exploration.md) separates temporary scope/representation browsing from authored named views. It is planned; the current implementation described below requires a named view. The [domain glossary](../../CONTEXT.md) defines these terms.
+
Named views are actual SysML usages. Open existing views without authoring another declaration. New view takes a subject, representation and name; package ownership is advanced configuration. Definitions, exposure and filters remain source content. The canvas is a derived artifact and does not serialize the model.
Semantic subject identity, usage context and symbol identity remain distinct. Geometry changes never imply semantic containment or connectivity. The bounded structural projection consumes engine parent IDs, typed inherited ports and explicit connection endpoints; port selection retains its usage context. `moveSymbols` validates a complete presentation batch before publishing it, so moving a group and its descendants keeps version-1 absolute coordinates consistent without a source transaction. [Structural projection, engine trace and limits](structural-views.md).
@@ -51,3 +55,5 @@ Unit tests exercise workspace interfaces with controlled engine responses. These
The [panel shell](workbench-layout.md) composes resizable tools and editors, with validated browser layout preferences and accessible icon actions. It owns no semantic transactions or portable-project fields. Divider movement retains camera/model-space geometry; explicit editor mode changes retain the existing fit-to-pane behavior.
[Source assistance and local recovery](source-assistance-recovery.md) describes draft-bound language queries, supported edits, the independent recovery envelope and concurrency policy.
+
+The [application shell](application-shell.md) separates the public landing, explicit launcher and live workbench. The workbench session remains mounted during internal launcher/home navigation; full reload offers recovery explicitly. Entry pages use shared appearance state and defer engine work until a project-opening action.
diff --git a/docs/architecture/application-shell.md b/docs/architecture/application-shell.md
new file mode 100644
index 0000000..431559c
--- /dev/null
+++ b/docs/architecture/application-shell.md
@@ -0,0 +1,40 @@
+# Application shell
+
+Current implementation, updated 2026-11-01. The application uses the shared Geist/Lucide/shadcn controls and appearance tokens. Product identity is **OpenMBEE View Editor**, at **Sandbox** stage; legal and third-party attribution remains in the repository notices.
+
+## Entry and opening
+
+- `/` presents the product, documentation/feedback/license links, **Open app** and **Try an example**.
+- `/app` starts an empty launcher with **Load example**, **New project**, **Open files or project** and **Local recovery**. An existing live session adds **Resume project**.
+- `/app/?example=1` requests the example once and is canonicalized to `/app` before opening; reload does not repeat the example action. Static hosting must serve the SPA fallback for `/app` while preserving asset paths.
+
+No model loads implicitly. The built-in example opens its pneumatic named view in Diagram mode. New projects open source and remain modified until downloaded. Imports are copies; Download exports a portable bundle. Recovery is a separate browser copy, not a disk save.
+
+Applied source is validated before replacing the project. Replacing dirty work requires confirmation. Cancelled or failed replacement retains current source, drafts, model, history and compatible presentations. Failed operations remain visible and can be retried.
+
+## Session and focus
+
+The workbench is created on entry, but source/diagram panels mount only after a successful opening. Once opened, they remain mounted while the launcher or landing is displayed; hidden surfaces are inert. Home, Resume and browser Back/Forward retain the live source editor/selection, history, Inspector selection, camera and diagram positions. A full reload creates a new session and offers stored recovery explicitly; it does not restore session history or camera.
+
+One appearance provider owns preferences across all surfaces. Dialogs close when their owning surface becomes inactive; focus returns to a visible trigger or the current heading/workspace. The workbench Save shortcut is active only while the workspace is visible and ready. Unsaved-work unload protection remains active while internal navigation hides the workspace.
+
+## Workbench grouping
+
+The app bar groups product/home navigation, Projects, project name/origin and persistence/settings actions. Source transaction history, apply/discard and Code/Split/Diagram controls use the measured toolbar layout. Sidebar toggles belong to their tools. The diagram header selects an actual **Named view**, displays its supported representation and applied/draft status, and keeps authoring actions nearby. Source-file selection does not replace the diagram's named view.
+
+See [layout contracts](workbench-layout.md), [source/recovery policies](source-assistance-recovery.md) and [project format](project-format.md). [Testing](../testing.md) and [verification](../verification.md) own checks and observed results.
+
+## Future opening workflows
+
+These are capability gates, not shipped controls:
+
+| Workflow | Required before delivery |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Automatic exploration | Validated read-only projection with scope/representation independent of files and authored views; see the [exploration plan](model-exploration.md) |
+| Local folder import | Explicit membership/exclusions/limits, permission handling and file-import fallback |
+| Folder write-back | Exact write set, permissions, external-change detection and preservation on failure |
+| Flexo project/branch | Select a deployment/auth flow, prove interchange/identity, resolve branch to immutable commit and label generated source; see [integration research](../research/openmbee-flexo-mms.md) |
+| Remote publication | Reviewed change set, repository identity retention, server-enforced concurrency and ambiguous-outcome recovery |
+| Recent projects/context | Validated persistence, permission renewal and schema compatibility; navigation references are not backups |
+
+The [roadmap](../next-steps.md) defines the next sequence. Resolve folder scope and Flexo deployment/authentication when their implementation slices begin.
diff --git a/docs/architecture/engine-identity-sources.md b/docs/architecture/engine-identity-sources.md
deleted file mode 100644
index fc7b896..0000000
--- a/docs/architecture/engine-identity-sources.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Engine identity source findings
-
-Recorded 2026-10-26 for the identity/layout investigation. This note records the original source inspection at `fd54b67`; runtime comparisons and implemented reconciliation supply separate evidence. The current production policy is documented in [identity reconciliation](identity-reconciliation.md). The inspected engines are OpenSysML `0.10.0` at `08ef397841767b829e492bbecf6d723483b4421e` and SysML Toolkit `0.10.10` at `339ef0e073d06e553e81c079755ddfcd224e4b92`. The [engine preparation guide](../../engine-bridge/README.md) and preparation scripts own those pins and generated provenance.
-
-## The application has several different identity domains
-
-| Value | What the inspected source defines | Consequence for matching revisions |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| OpenSysML `modelHash` | SHA-256 of conformance mode, document count and each ordered document's name, language and full content | Identifies the complete parser input. Comments, filenames, document order and unrelated file changes can change it. It is not an element identity. |
-| Normalized model element `id` | `GetSymbol` returns the symbol's fully qualified name; the worker copies it into the model record | Renaming an element or its owner changes this name. Reusing the name can identify a different declaration. |
-| Evaluated `correspondence.subject.id` | The bridge formats a located declaration as `file@offset:length` | Identifies a recorded source span within a revision. Insertion, replacement, file moves and changes inside enclosing declarations can change it. A same-length replacement can reuse it. |
-| Evaluated `correspondence.context` | The bridge collects ancestor declaration origins and appends the node's origin; inherited-port correspondence adds its declaration origin | Distinguishes occurrences of the same inherited port in a particular usage chain within a view. The origin keys remain sensitive to source edits. |
-| Diagram node/port `symbol` | A renderer traversal counter (`n0`, `n1`, …), with port ordinal appended to the node ID | Identifies an artifact entry in that rendering. A new traversal can assign the same string to a different element. |
-| Toolkit `idMap` | An edit result's old/new IDs in Toolkit's own session; its public element APIs also expose interchange IDs | The inspected application does not expose a mapping from these IDs to OpenSysML origins, model names or diagram symbols. A join must be demonstrated rather than assumed. |
-
-Sources for the hash and model names are the pinned upstream [parser input key](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/frontend/engine/engine.go#L527), [hash function](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/frontend/engine/engine.go#L1035), [GetSymbol lookup](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/frontend/core/core.go#L335) and [symbol facts](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/frontend/symbolfacts/facts.go#L110). The worker preserves `symbol.id`, ownership and resolved type IDs in [semantic.worker.ts](../../src/lib/engines/opensysml/semantic.worker.ts#L96).
-
-The retained bridge defines [subject/origin fields](../../engine-bridge/opensysml/evaluate_view.go#L18), [origin lookup and subject construction](../../engine-bridge/opensysml/evaluate_view.go#L88), [usage-context construction](../../engine-bridge/opensysml/evaluate_view.go#L149) and [origin-key spelling](../../engine-bridge/opensysml/evaluate_view.go#L209). `QualifiedName` is looked up using a source origin; it is not a persistent ID assigned by this bridge.
-
-The upstream renderer [starts a new structural counter for a rendering](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/ir/view/interconnection.go#L20), [allocates IDs while visiting features](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/ir/view/interconnection.go#L111), [emits counter names](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/ir/view/view.go#L769) and [names ports by ordinal](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/ir/view/behavior.go#L820). Therefore stability observed in one fixture must not be promoted to a guarantee that those IDs persist across edits or views.
-
-The cached upstream sources were inspected under `sandbox/opensysml-build/source/` with the paths shown in those immutable links. That directory is ignored and reconstructed by preparation. Bridge overlays are retained separately in this repository; they are not claimed to exist in upstream source at that commit.
-
-## Toolkit edit evidence at the original investigation revision
-
-The prepared Toolkit JavaScript wrapper documents `checkEdit` as a dry run of splice, reparse, rebuild and reference checks, returning `wouldCommit`, `idMap`, findings and splices. It documents successful `edit` as rebuilding the session, invalidating outstanding handles, and returning old/new ID pairs plus splices in **pre-commit byte offsets per unit**. These descriptions were inspected at generated `static/vendor/sysml-toolkit/sysmlv2.js:465–476` and `:746–763`. The prepared wrapper's SHA-256 is `3c4d015fdce693a103c5a3d6c880c5d930a72bb6fb8cd54ce638abc38aaab52b`, recorded in its generated provenance and verified by [Toolkit preparation](../../scripts/prepare-sysml-toolkit.mjs). Its `elementById`/`elementId` APIs describe interchange UUIDs at `:787–805`; this does not prove that any such UUID is an OpenSysML ID.
-
-At `fd54b67`, the transformation worker checked refusal/findings and returned only full sources; its interface was `Promise`. The current [transformation result](../../src/lib/workspace/editing/evidence.ts) now includes validated source-bound splices and optional owner extent. The [adapter](../../src/lib/engines/toolkit/transform.worker.ts) still does not treat Toolkit UUID maps as OpenSysML identity. The semantic worker reparses source in a new disposable worker for each request; [worker lifetime](../../src/lib/engines/workers/request.ts#L1) terminates the worker on completion. The application cannot rely on retaining an engine session's in-memory handles across these operations.
-
-Source inspection establishes an available direction for a rename investigation: capture the actual edit report, associate each splice unit with a filename, replay the byte splices against the exact before sources, and compare the result with the returned after sources. The resulting offset relation can then be checked against both versions of the OpenSysML origins. This is a proposed use of the evidence; these sources alone do not establish that every declaration or context can be reconciled.
-
-JavaScript string offsets count UTF-16 code units, so using them directly for the wrapper's documented byte positions would be unsafe for Unicode source. Any adapter must prove UTF-8 byte handling, offset bounds, unit/file association, nonoverlapping splice replay and the exact before/after source binding before publishing correspondence.
-
-## Requirements implied by these contracts
-
-These are deductions from the inspected contracts, not a claim that reconciliation is implemented:
-
-1. Keep model revision, view identity, declaration identity, usage chain and artifact symbol distinct. The same inherited-port declaration appears under multiple usage chains; declaration-only matching can attach the right port to the wrong instance.
-2. Establish declaration lineage from verified edit evidence before using names or origin spans to join old/new artifacts. Exact names and equal spans are useful checks, but neither proves continuity after arbitrary source replacement.
-3. Require a unique match in both directions, and validate all relevant ancestor contexts. When origins are missing, duplicated or ambiguous, discard the affected mapping rather than choosing a same-label candidate.
-4. Resolve old and new symbols separately in each view. The renderer-local IDs and traversal ordering provide no cross-view identity guarantee.
-5. Distinguish a verified transformation from a free-form draft. Toolkit can report how it performed a known edit; the current source-apply interface receives replacement text without an edit report. A conservative policy is still needed for arbitrary drafts, deleted/recreated declarations, moved files and changed owners.
-6. Recheck source/model/view compatibility after mapping and before accepting positions. A successful source transformation does not prove a complete or renderable view.
-
-The investigation revision deliberately cleared presentations on source application and proposal acceptance. The current [workspace](../../src/lib/workspace/createWorkspace.ts) reconciles compatible positions using the [implemented policy](identity-reconciliation.md). The [version-1 project format](project-format.md) remains unchanged; source inspection alone is still not evidence of application preservation.
-
-## Runtime evidence and remaining work
-
-The [runtime investigation](identity-reconciliation.md) now compares unchanged reparses, Toolkit definition/usage renames, an unrelated-file edit, offset-shifting edits, reordering, insertion, file/owner moves and changed types. It retains Unicode/splice evidence and tests distinct repeated-port contexts in both views. Reordering equal-length usages supplies a concrete same-location identity counterexample. The implementation now adds a conservative draft policy, stale-source/presentation rejection and separate browser preservation/authoring checks through undo/redo and fresh import. General arbitrary-replacement identity and independent layout undo remain gaps. See [verification](../verification.md) for actual application results.
diff --git a/docs/architecture/identity-reconciliation.md b/docs/architecture/identity-reconciliation.md
index 632cc2e..0fc6096 100644
--- a/docs/architecture/identity-reconciliation.md
+++ b/docs/architecture/identity-reconciliation.md
@@ -1,6 +1,6 @@
# Identity across source revisions
-Investigation recorded 2026-10-26; implementation policy updated 2026-10-29. The original comparisons below establish the identity hazards and bounded rename join. Production preservation now uses that evidence for reviewed commands and a conservative policy for free-form source edits; actual checks are recorded in [verification](../verification.md).
+Investigation recorded 2026-10-26; current implementation reviewed 2026-11-01. The original comparisons below establish the identity hazards and bounded rename join. Production preservation now uses that evidence for reviewed commands and a conservative policy for free-form source edits; actual checks are recorded in [verification](../verification.md).
## Findings
@@ -8,7 +8,22 @@ No currently exposed identifier is a persistent cross-revision identity. An unch
There is a viable bounded path for verified renames: Toolkit supplies actual edit splices and changed interchange IDs. Replaying the splices against the exact old UTF-8 sources reproduces the worker's returned sources. Transporting recorded OpenSysML declaration spans and every ancestor context through those verified name edits identifies unique counterparts in both assembly views, including repeated inherited ports. The probe checks model rename postconditions as well. The original experiment proves its tested rename. The implementation policy below defines the production subset; it does not establish persistent identity for arbitrary text replacement.
-The [source-contract findings](engine-identity-sources.md) explain the distinct identity domains and cite the pinned engine sources. The retained [browser investigation](../../tests/e2e/identity.spec.ts) supplies runtime evidence with production worker bundles and the actual prepared WASM engines. It sends validated worker requests and validates model/evaluation replies; it does not substitute engine responses.
+The retained [browser investigation](../../tests/e2e/identity.spec.ts) supplies runtime evidence with production worker bundles and the actual prepared WASM engines. It sends validated worker requests and validates model/evaluation replies; it does not substitute engine responses.
+
+## Identity domains
+
+| Value | Meaning and limit |
+| --------------------------- | --------------------------------------------------------------------------------------------- |
+| `modelHash` | Hash of the complete ordered parser input; comments and unrelated edits can change it |
+| Model element `id` | Qualified name; changes on rename and can be reused by another declaration |
+| `correspondence.subject.id` | Located source declaration, spelled `file@offset:length`; revision-bound |
+| `correspondence.context` | Complete ancestor/usage origin chain; distinguishes repeated occurrences within a revision |
+| Diagram `symbol` | Renderer-local traversal counter/port ordinal; no cross-view or cross-edit identity guarantee |
+| Toolkit UUID / `idMap` | Toolkit's interchange/session identity domain; not an OpenSysML origin or renderer symbol |
+
+The retained [bridge](../../engine-bridge/opensysml/evaluate_view.go), [semantic worker](../../src/lib/engines/opensysml/semantic.worker.ts) and [transformation worker](../../src/lib/engines/toolkit/transform.worker.ts) own normalization. Immutable upstream references describe the [input hash](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/frontend/engine/engine.go#L1035) and [renderer IDs](https://github.com/Open-MBEE/OpenSysML/blob/08ef397841767b829e492bbecf6d723483b4421e/internal/ir/view/view.go#L769). Engine pins/checksums are owned by [preparation and provenance](../../engine-bridge/README.md), not duplicated here.
+
+Toolkit splice units name files; numeric `session.units()` handles are separate. Splices use pre-edit UTF-8 byte offsets, while JavaScript strings use UTF-16. Exact replay, valid code-point boundaries and source digests must be verified before using edit evidence. Disposable workers provide no persistent engine handles. The demonstrated join below uses verified source edits and complete OpenSysML origins; it does not establish a general UUID join or arbitrary-replacement continuity.
## Comparison matrix
@@ -58,7 +73,7 @@ Mapped presentations are prepared with the semantic candidate, then published at
The version-1 bundle shape is unchanged. It stores sources/drafts/compatible positions, while edit evidence and origin joins remain transient. Fresh import reparses source and restores only hash-compatible positions. New symbols receive deterministic automatic layout until moved; existing renderer bounds checks may arrange incompatible coordinates again with a notice. Manual overlap avoidance, interactive parent resizing, file-moving controls and general persistent identity remain outside this implementation.
-The [structural authoring contract](graphical-authoring.md) describes part and connection commands built on this path. The [roadmap](../next-steps.md) distinguishes delivered slices from remaining notation, language-assistance and recovery work.
+The [structural authoring contract](graphical-authoring.md) describes part and connection commands built on this path. The [roadmap](../next-steps.md) distinguishes delivered slices from remaining exploration, integration and usability work.
## Reproduction and evidence
diff --git a/docs/architecture/model-exploration.md b/docs/architecture/model-exploration.md
new file mode 100644
index 0000000..090920c
--- /dev/null
+++ b/docs/architecture/model-exploration.md
@@ -0,0 +1,44 @@
+# Model exploration and named views
+
+Agreed direction, 2026-11-01. This document describes planned behavior, not an implemented capability. Current diagrams still require named SysML view usages.
+
+Opening is exploration; creating a named view is authorship. Users should be able to inspect an imported project without first changing its source. The [domain glossary](../../CONTEXT.md) distinguishes source files, the project model, scopes, representations, explorations, named views, diagram presentations and cameras.
+
+## Opening experience
+
+- For a new import with one unambiguous top-level system subject, open its supported structural representation.
+- For multiple systems, packages or ambiguous roots, open a project overview and let the user choose a scope. Do not equate all packages with one instantiated system.
+- When reopening saved work, restore its valid previous browsing context when that context is supported by the saved format; otherwise use the appropriate opening fallback.
+
+Expose scope and representation as separate choices. Switching the active source file must not silently replace the diagram scope. Existing named views remain directly accessible. Browsing can lead to an explicit, reviewed action to create a named view where the exploration's scope and representation can be expressed faithfully in SysML.
+
+The system-root criterion needs evidence from the resolved model and example fixtures. Do not guess a system from its filename, display name or first package. Where the criterion is uncertain, prefer the project overview. The initial overview may show project/package contents; it must not imply that unrelated packages form one connected system.
+
+## Ownership and preservation
+
+Files organize source; the applied model resolves their meaning together. Unapplied or invalid drafts remain distinct from the last valid model shown by diagrams. Browsing should identify the revision it represents.
+
+Temporary scope and representation are workbench navigation state. Named-view declarations, exposures and filters remain source-owned semantics. Diagram geometry and camera are separate concerns. Exploring must not add hidden declarations to project sources, mark a project modified, add semantic history or overwrite saved named-view geometry.
+
+Use shared evaluation, rendering, correspondence and selection contracts for exploration and named views. Trace the actual engine contracts before choosing a read-only exploration interface. If evaluation requires temporary engine input, isolate it from applied source, drafts and serialization, and verify its identity correspondence rather than assuming synthetic IDs are equivalent. Scope changes and stale or failed evaluations must retain current work.
+
+## First implementation slice
+
+Implement read-only automatic exploration for an imported model with no view declarations, using only representations supported by the pinned engines and current renderers. Prove a project/package overview and a bounded structural subject before extending representation families or enabling graphical semantic edits within exploration.
+
+Acceptance:
+
+- A model without view usages opens a useful overview or an unambiguous system structure immediately.
+- A multi-file fixture resolves as one project model; a multi-system fixture offers an overview rather than choosing an arbitrary system.
+- Scope and representation controls distinguish definitions from repeated usages. Unsupported representations explain their limits.
+- Existing named views still open normally and retain independent saved positions. Source-file navigation remains independent of diagram scope.
+- Browsing and failed or superseded requests retain exact applied source, drafts, semantic history and saved presentations; valid scope changes do not inherit another subject's geometry.
+- Real-engine browser checks establish the projection contract and preservation outcomes. Inspect desktop/narrow, light/dark captures and keyboard focus behavior.
+
+The first slice keeps exploration navigation transient. Persisting an exploration across reloads or portable reopen is a later explicit storage decision: the current recovery envelope records only an active file and named-view identity, and the portable bundle has no exploration field. Any persistence change must follow the owning schema, versioning and compatibility-fixture requirements.
+
+Follow-up slices are explicit creation of a named view from exploration, storage/restoration of browsing context, and additional representation families supported by actual engine and renderer evidence. State and action representations require independent engine and renderer verification.
+
+## Engine evidence
+
+The [pinned-engine investigation](../research/automatic-exploration-contract.md) executed the current WASM boundary and native renderer. Declaration-free project/package rendering has a promising underlying seam, but the browser contract still requires named views. A typed system usage did not automatically unfold its definition’s internals. The first delivered exploration must therefore use an overview until structural subject/usage expansion is proven, rather than promise an inferred full-system diagram.
diff --git a/docs/architecture/source-assistance-recovery.md b/docs/architecture/source-assistance-recovery.md
index 4b7552e..9b0ac6b 100644
--- a/docs/architecture/source-assistance-recovery.md
+++ b/docs/architecture/source-assistance-recovery.md
@@ -1,9 +1,21 @@
-# Source assistance and local recovery
+# Source editing, assistance and recovery
The workbench composes a separate Toolkit language adapter in `shell/session.ts`. Language queries are read-only and use every current draft source file, including unapplied text. Each request runs in a disposable worker against the pinned Toolkit library and negotiates UTF-16 positions. Normalization converts between raw source offsets and protocol positions, including CRLF and astral Unicode characters.
Completion is explicit with Control+Space. Only supported single plain-text edits are offered; snippets, additional edits and commands are excluded. Hover and F1 display plain text. F12 navigates to one exact project-file definition; unavailable, ambiguous and library-only targets explain their limits. The editor rejects results after draft, session, file or busy-state changes and rechecks completion validity when applying it. Queries do not apply source, change model history or replace views.
+## Issue navigation
+
+OpenSysML's pinned ParseSources response supplies diagnostic `span.file` and one-based `span.startLine`. The existing semantic worker normalizes those to optional `file` and `line`. The workbench selects a whole reported line, retaining raw UTF-16 offsets and CRLF/CR/LF boundaries; it does not claim a column or token range that this transport does not carry.
+
+`WorkspaceState.diagnosticDocuments` records the exact source documents associated with visible diagnostics. Failed draft application and rejected semantic candidates retain their respective inputs; accepted model diagnostics use applied documents. This transient state is independent of the version-1 portable project. Draft edits clear obsolete diagnostics and their inputs.
+
+`workbench/issues/navigation.ts` resolves a diagnostic only when its file belongs to the current project and that file's current draft text exactly matches the diagnosed text. A known file without a line opens at the beginning with no text selected and an explicit explanation. Unknown files, unavailable snapshots and out-of-range lines expose a reason instead of a source action. A candidate error must not lend its location to the old live source.
+
+The click handler rechecks current diagnostic membership and resolves against the current workspace snapshot before changing source focus. Source reveal preserves Code/Split mode, opening Split when the source was hidden in Diagram mode. The open named view, selected semantic element, source text and saved geometry remain independent of issue browsing. Explicit editor-mode changes retain the existing diagram-fit policy.
+
+The browser scenarios combine actual pinned-engine errors with controlled normalized responses for unavailable locations and rejected-candidate evidence. Unit checks cover raw line bounds, Unicode, line endings and stale snapshots. These are navigation and preservation guarantees, not complete diagnostic or SysML conformance.
+
## Recovery storage
Local recovery uses one IndexedDB record per browser origin: database `sysml-view-recovery`, store `recovery`, key `latest`. A separately validated version-1 recovery envelope contains a serialized portable project, save time and active file/view. The portable project format remains version 1. Recovery includes applied source, drafts and saved presentation geometry; it does not include canvas camera or undo history.
diff --git a/docs/architecture/source-navigation.md b/docs/architecture/source-navigation.md
deleted file mode 100644
index fc2564c..0000000
--- a/docs/architecture/source-navigation.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Source issue navigation
-
-OpenSysML's pinned ParseSources response supplies diagnostic `span.file` and one-based `span.startLine`. The existing semantic worker normalizes those to optional `file` and `line`. The workbench selects a whole reported line, retaining raw UTF-16 offsets and CRLF/CR/LF boundaries; it does not claim a column or token range that this transport does not carry.
-
-`WorkspaceState.diagnosticDocuments` records the exact source documents associated with visible diagnostics. Failed draft application and rejected semantic candidates retain their respective inputs; accepted model diagnostics use applied documents. This transient state is independent of the version-1 portable project. Draft edits clear obsolete diagnostics and their inputs.
-
-`workbench/issues/navigation.ts` resolves a diagnostic only when its file belongs to the current project and that file's current draft text exactly matches the diagnosed text. A known file without a line opens at the beginning with no text selected and an explicit explanation. Unknown files, unavailable snapshots and out-of-range lines expose a reason instead of a source action. A candidate error must not lend its location to the old live source.
-
-The click handler rechecks current diagnostic membership and resolves against the current workspace snapshot before changing source focus. Source reveal preserves Code/Split mode, opening Split when the source was hidden in Diagram mode. The open named view, selected semantic element, source text and saved geometry remain independent of issue browsing. Explicit editor-mode changes retain the existing diagram-fit policy.
-
-The browser scenarios combine actual pinned-engine errors with controlled normalized responses for unavailable locations and rejected-candidate evidence. Unit checks cover raw line bounds, Unicode, line endings and stale snapshots. These are navigation and preservation guarantees, not complete diagnostic or SysML conformance.
diff --git a/docs/architecture/structural-views.md b/docs/architecture/structural-views.md
index e2346cc..ec34508 100644
--- a/docs/architecture/structural-views.md
+++ b/docs/architecture/structural-views.md
@@ -33,4 +33,16 @@ Children remain within their displayed owner's content area. Group movement carr
Browser tests load the shared sources through the actual pinned workers. They check nested bounds, reference notation, explicit port labels, SVG endpoints against the correct physical port handles, keyboard port selection/source reveal, distinct inherited-port contexts, parent and child movement, view switching and save/reopen with exact source retention. Light/dark snapshots cover the assembly in diagram-only mode. Unit tests exercise malformed topology, projection and absolute-coordinate restoration; the retained Go test checks the engine contract directly.
-This slice establishes the fixture's nested interconnection workflow. GeneralView remains a flat tree. Broader owned-port boundary notation, effective directions through conjugated types, modeled layouts/routes, behavior/sequence/geometry rendering, large-model performance and full notation/language conformance remain outside the verified scope. Reviewed typed part creation and explicit directed, same-type port connections are available through diagram/Inspector actions; [the authoring contract](graphical-authoring.md) records restrictions. See [verification](../verification.md) for commands actually run and [next steps](../next-steps.md) for the remaining milestone.
+This slice establishes the fixture's nested interconnection workflow. GeneralView remains a flat tree. Broader owned-port boundary notation, effective directions through conjugated types, modeled layouts/routes, behavior/sequence/geometry rendering, large-model performance and full notation/language conformance remain outside the verified scope. Reviewed typed part creation and explicit directed, same-type port connections are available through diagram/Inspector actions; [the authoring contract](graphical-authoring.md) records restrictions. See [verification](../verification.md) for commands actually run and [next steps](../next-steps.md) for planned extensions.
+
+## Planned edge interactions and routing
+
+This follow-up is not implemented. Context7 MCP documentation was checked against the installed React Flow implementation on 2026-11-01.
+
+Current projections use ELK node placement and React Flow `smoothstep` edges; they do not consume ELK edge sections. The structural layout does not pass actual port geometry to ELK, and saved node positions can replace the initially calculated coordinates. Adopting initial ELK routes without reconciling those positions would leave stale paths.
+
+Start with controlled edge selection, keyboard focus/selection styling and descriptive endpoint labels across structural and tree/definition views. `Diagram.tsx` currently wires node changes but not `onEdgesChange`; verify edge selection through the controlled state using [applyEdgeChanges](https://reactflow.dev/api-reference/utils/apply-edge-changes). Keep selection transient and source/history/presentations unchanged. Any future reconnect/delete action must use a reviewed semantic command rather than direct canvas mutation; those commands are not implemented.
+
+Built-in smoothstep edges already pass the [path helper's label coordinates](https://reactflow.dev/api-reference/utils/get-smooth-step-path) to SVG labels, and [BaseEdge](https://reactflow.dev/api-reference/components/base-edge) already supplies an invisible 20 px hit area. Measure selection at representative zoom levels before choosing a larger hit width. Keep plain labels in SVG; use [EdgeLabelRenderer](https://reactflow.dev/api-reference/components/edge-label-renderer) only for richer or interactive HTML, with explicit pointer events and `nodrag nopan`. Complete [edge descriptions and focus behavior](https://reactflow.dev/learn/advanced-use/accessibility) without implying full accessibility coverage.
+
+Obstacle-aware routing requires a separate contract: accurate port coordinates/directions, nested coordinate transforms, parallel edges, labels on sufficiently long clear segments and rerouting after saved-position restoration or movement. Rerouting must retain manually positioned nodes. Test exact endpoint attachment, source/history preservation, pointer/keyboard movement and save/reopen before adopting those routes. Rounded corners alone do not provide obstacle avoidance.
diff --git a/docs/architecture/workbench-layout.md b/docs/architecture/workbench-layout.md
index 314c14c..4f1e30e 100644
--- a/docs/architecture/workbench-layout.md
+++ b/docs/architecture/workbench-layout.md
@@ -20,7 +20,7 @@ The canvas waits for measured dimensions and initialized nodes before fitting. E
Reads and writes tolerate blocked browser storage. A failed save retains the live layout for the visit and reports the failure under Workspace layout. Reset applies responsive defaults. Preferences are specific to a browser origin; they are not part of the portable project.
-Panel changes do not invoke workspace transactions, reparse source, alter diagram geometry, mark the project modified or add undo history. Source and Diagram remain mounted through mode changes. Project bundles retain their existing version-1 format and still require download to preserve source/drafts across reloads; remembering panel preferences is not work recovery.
+Panel changes do not invoke workspace transactions, reparse source, alter diagram geometry, mark the project modified or add undo history. Source and Diagram remain mounted through mode changes. Project bundles retain their existing version-1 format. Download provides a portable copy; the separate local recovery workflow offers explicit restore/discard after reload. Remembering panel preferences is not work recovery.
## Source editor
@@ -55,7 +55,7 @@ Lucide icons use the shared shadcn Button sizes, theme roles and focus indicator
Apply and Download retain visible labels; frequent compact actions retain precise names such as Undo source. CodeMirror draft undo/redo is distinct from accepted source transaction history. Standard editor/search shortcuts are documented in the README; Tab retains focus navigation. Existing kind labels remain visible alongside Explorer icons; those icons do not establish SysML notation support.
-[Browser testing](../testing.md) describes verification; [verification](../verification.md) records actual outcomes and remaining gaps. Full tab docking, floating windows, semantic language assistance and complete accessibility certification remain separate work.
+[Browser testing](../testing.md) describes verification; [verification](../verification.md) records actual outcomes and remaining gaps. Full tab docking, floating windows and complete accessibility auditing remain separate work. Engine-backed language queries are documented in [source editing and recovery](source-assistance-recovery.md).
## Model ownership tree
@@ -66,3 +66,11 @@ Apply and Download retain visible labels; frequent compact actions retain precis
Navigation follows the [WAI-ARIA tree pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/): arrows move through visible rows and fold/unfold branches, Home/End reach the visible extremes, typed prefixes find visible names, and Enter/Space select the focused declaration. Focus and selection are separate. One treeitem participates in Tab order; shared focus styling distinguishes it from the inspected row.
Diagram selection opens the selected declaration's owner chain without taking focus from the diagram. A UI request counter handles a second selection of the same symbol after its branch has been folded. These are reveal requests, not semantic revisions or identity reconciliation. Selecting a tree row retains the existing Inspector behavior; source-range reveal still requires diagram correspondence. Expansion is not portable project data or automatic work recovery.
+
+## Entry and session lifetime
+
+The public landing lives at `/`; `/app` starts with a project launcher. Source/diagram panels are created on first successful project opening and remain mounted while the launcher or landing is displayed. Inactive workbench surfaces are hidden and inert, retaining the live source editor, history and camera. Appearance state belongs to one application provider. Modal controls close when their owning route becomes inactive, and focus returns to visible controls or the current route heading. A full browser reload is a new session with an explicit recovery choice.
+
+## Shell code ownership
+
+`Workbench.tsx` retains the live session, project-opening validation, selection and reviewed-command orchestration. `ProjectHeader.tsx` and `SourceToolbar.tsx` render shell controls through explicit callbacks. `projectFiles.ts` owns local bundle construction, file reading and browser download preparation; workspace validation and saved-state tracking retain their existing contracts. Panel controls and preferences remain in `WorkbenchPanels.tsx` and `layout.ts`. Surface CSS is imported through `ui/theme.css`; see the [design-system ownership table](../design-system.md#ownership).
diff --git a/docs/assets/readme-header.svg b/docs/assets/readme-header.svg
index 435f9e8..166361f 100644
--- a/docs/assets/readme-header.svg
+++ b/docs/assets/readme-header.svg
@@ -1,5 +1,5 @@
+