feat: preserve nested source projects across desktop and REST

README.md

@@ -67,9 +67,16 @@ Connections start with orthogonal routes that avoid cards and container headers.
 arcadia 3;
 project harbor "Harbor assistance" {
     oa_entity control "Harbor control" {}
-    oa_activity assess "Assess assistance" {}
+    oa_activity respond "Respond to requests" {
+        oa_activity assess "Assess assistance" {}
+    }
     allocation performs "Performs" { source @control; target @assess; }
     sa_system service "Harbor assistance system" {}
+    sa_actor operator "Harbor operator" {
+        sa_port radio "Radio" {
+            contract { Component { kind Standard; orientation Unset; }; };
+        }
+    }
     sa_function evaluate "Evaluate assistance request" {}
     trace assessment_trace "Operational realization" {
         oa @assess; sa @evaluate; kind Refinement;
@@ -79,8 +86,12 @@ project harbor "Harbor assistance" {
 
 New declarations may omit IDs; Apply inserts assigned UUIDs into their source. Keep existing identity clauses to preserve objects. Stable `@aliases` survive display-name changes and support forward references. The [normative specification](docs/language.rst) covers every supported declaration, typed constructor, relationship and persisted diagram field.
 
+Nested elements inherit their enclosing element as semantic parent. Allocation remains an explicit relationship: nesting a function inside a System would confuse containment with responsibility and is rejected. An explicit `parent` on a nested declaration must agree with its enclosing owner. Flat declarations with `parent @alias` remain supported. Open [the six-file source project](examples/source-project/project.arcadia) for a complete OA/SA example with typed ports, matching functional and boundary exchanges, allocations and saved views.
+
 Applying valid source commits the reachable source bundle as one model transaction. Graphical edits update the owning declarations while preserving unaffected formatting and comments. Invalid source remains in its file buffer with located diagnostics, including while another file is open. **Undo text** and **Undo model** are distinct: model Undo/Redo restores the accepted model and its exact source documents together. JSON export carries model semantics; comments and source-file organization belong to the source project. Version 1 source/JSON is migrated explicitly without inventing SA content.
 
+Reparenting a nested element through Properties moves its declaration, descendants and attached comments to the new owner's body, including across files. Existing flat declarations retain their file organization. New children appear inside their owner's source body. Separate general file or group notes from the next declaration with a blank line to keep those notes in place when it moves.
+
 ## Save and reopen
 
 Ctrl+S saves, Ctrl+Shift+S saves as, and Ctrl+O opens. An `.arcadia` suffix selects text; other suffixes select JSON. Opening detects content rather than relying on the filename. Windows uses native dialogs; Linux uses a path-entry dialog with overwrite confirmation and no portal requirement.
@@ -97,9 +108,9 @@ cargo run --locked -p oa-server --bin arcadia-server
 
 The default is `127.0.0.1:8787`, with a platform-local data directory. `--data-dir PATH`, `--bind IP:PORT` and `--token-file PATH` configure deployment; binding outside loopback requires a bearer token. See [server setup](docs/server.md), the [REST contract](docs/api.rst), [OpenAPI](docs/openapi.json) and [deployment examples](deployment).
 
-The API queries and edits complete models, canonical source, elements, relationships, artifacts and traces. Transactions and transition previews use the same core validation as the desktop. Writes require the returned ETag in `If-Match`. The server retains the current revision only.
+The API queries and edits complete models, canonical source, multi-file source projects, elements, relationships, artifacts and traces. Transactions and transition previews use the same core validation and source writer as the desktop. Writes require the returned ETag in `If-Match`. One revision protects the accepted model and source bundle together, including comment-only edits. The server retains the current revision only.
 
-Desktop files and hosted resources transfer explicitly; the desktop has no direct server connection. Use **Save as** to export `system.json`, import it, then edit using the API. The current import endpoint accepts a complete JSON model or standalone canonical source; it does not resolve a desktop project's included files.
+Desktop files and hosted resources transfer explicitly; the desktop has no direct server connection. Use **Save as** to export `system.json`, import it, then edit using the API. The model interchange endpoint accepts a complete JSON model or standalone canonical source:
 
 ```sh
 curl --fail-with-body -X POST http://127.0.0.1:8787/api/v1/projects/import \
@@ -108,6 +119,8 @@ curl --fail-with-body -X POST http://127.0.0.1:8787/api/v1/projects/import \
 
 The response supplies the service `resource_id` and ETag. After API changes, export `/api/v1/projects/<resource-id>/source` to a new `.arcadia` file and open it in the desktop. This preserves model UUIDs, aliases, diagrams, traces and artifact metadata. Importing creates a separate hosted resource. Artifact URIs and revisions are opaque references for code, CAD, schematics, documents and other evidence; the application does not fetch or execute them.
 
+To preserve authored files and comments, use `POST /api/v1/projects/import-source-project` with a JSON bundle containing `entry` and a `files` map of relative paths to source strings. `GET` and conditional `PUT /api/v1/projects/<resource-id>/source-project` exchange that complete accepted bundle. Include resolution uses only the submitted files; the server never opens the client's disk paths. See the [REST contract](docs/api.rst) for payloads, located diagnostics and admission limits.
+
 ## Development
 
 ```sh