Add named behavior creation and verified textual authoring examples

2026-09-11 01:54:55 -07:00
parent d114a271c5
commit 4bb4aaf3dc
57 changed files with 6920 additions and 379 deletions
@@ -65,12 +65,12 @@ The integration oracle executes this exact semantic review and source update. It
 | `oa/`, `sa/` | Participants, work, data, capabilities and reusable behavior |
 | `views/` | Five saved views; filters and placements are presentation state |
 | `traceability.arcadia` | OA↔SA correspondence and review history |
-| `model.json` | Current schema-6 interchange of the final accepted model |
+| `model.json` | Current schema-7 interchange of the final accepted model |
 | `transition-before.json`, `transition-request.json` | Explicit first-transition replay inputs |
 | `evidence/repair-check.md` | Local teaching evidence linked from the SA conversation |
 | `model.rs` | Deterministic lesson builder shared by generator and tests |

-The REST routes are documented in [the API reference](../../docs/api.rst). Import `model.json` with `POST /api/v1/projects/import`; query the returned resource's `/model` and `/validation`. Expect schema 6 and the one warning above. JSON import provides canonical source; to retain the exact modular source layout, use `/api/v1/projects/import-source-project` with a SourceBundle containing entry `project.arcadia` and only the 30 reachable `.arcadia` file strings, keyed by slash-separated relative paths. Neither route reads the artifact target from your local filesystem.
+The REST routes are documented in [the API reference](../../docs/api.rst). Import `model.json` with `POST /api/v1/projects/import`; query the returned resource's `/model` and `/validation`. Expect schema 7 and the one warning above. JSON import provides canonical source; to retain the exact modular source layout, use `/api/v1/projects/import-source-project` with a SourceBundle containing entry `project.arcadia` and only the 30 reachable `.arcadia` file strings, keyed by slash-separated relative paths. Neither route reads the artifact target from your local filesystem.

 For transition replay, import `transition-before.json` instead. Submit `transition-request.json` to that baseline resource's `/transitions/preview` with its current ETag in `If-Match`. Review the returned plan, then follow the documented `/transitions/apply` protocol. Use the baseline resource for this exercise: the final model already contains the mapped records and subsequent refinements. This tutorial's automated evidence is core/source validation; it does not claim a separate native or HTTP acceptance run of this particular example.

@@ -0,0 +1,24 @@
+# Start a model in text
+
+Open `project.arcadia`, then choose **Textual model**. The model describes who
+reports distress, who assesses it, and the information passing between those
+activities. It needs no diagram or handwritten UUIDs.
+
+1. Read each declaration as **kind, alias, display name**. References such as
+   `@assess` use the alias. The two allocations state responsibility; the
+   interaction states the direction of the exchange.
+2. Change `"Assess incident"` to a name suited to your project. Use **Apply all**,
+   then **Save all**. Keep the identity clauses added to the accepted source:
+   they preserve the same model objects in later edits.
+3. Add work and exchanges as your understanding grows. Behavior coverage checks
+   identify activities and exchanges that still need process or scenario context;
+   these advisory checks allow you to save the intermediate model.
+
+Changing a display name keeps references intact. Changing an alias requires
+updating every `@alias` use. Nesting expresses decomposition; an allocation
+expresses who performs work. Neither implies the other.
+
+For a larger example with behavior, ports, views and OA/SA correspondence, use
+[the water-pressure walkthrough](../release1/README.md). The
+[language reference](../../docs/language.rst) defines all declarations and the
+rules for splitting a project into included files.
@@ -0,0 +1,10 @@
+arcadia 7;
+project distress "Distress response" {
+    oa_actor vessel "Vessel in distress" {}
+    oa_entity rescue "Rescue coordination" {}
+    oa_activity report "Report distress" {}
+    oa_activity assess "Assess incident" {}
+    allocation vessel_reports "Crew reports" { source @vessel; target @report; }
+    allocation rescue_assesses "Team assesses" { source @rescue; target @assess; }
+    interaction distress_report "Distress report" { source @report; target @assess; }
+}