Add scope diagrams section with C4 Level 1 and Level 2 diagrams

lws10-core/diagrams/fig-1-system-context.md

@@ -0,0 +1,18 @@
+# LWS Protocol — System Context (C4 Level 1)
+
+```mermaid
+C4Context
+  title LWS Protocol — system context
+
+  Person(user, "User", "Person accessing resources")
+  System(client, "Client application", "Requests and manages resources")
+  System(lws, "LWS server", "Manages resource hierarchy and access")
+  System_Ext(idp, "Identity provider", "Issues signed credentials")
+  System_Ext(ext, "External resources", "Web resources under management")
+
+  Rel(user, client, "uses")
+  Rel(client, lws, "HTTP requests")
+  Rel(lws, idp, "validates credential")
+  Rel(lws, ext, "mediates access to")
+```
+

lws10-core/diagrams/fig-2-container-diagram.md

@@ -0,0 +1,27 @@
+# LWS Protocol — Container Diagram (C4 Level 2)
+
+```mermaid
+C4Container
+  title LWS Protocol — container diagram
+
+  Person(user, "User", "Person accessing resources")
+  System(client, "Client application", "Requests and manages resources")
+  System_Ext(idp, "Identity provider", "Issues signed credentials")
+  System_Ext(ext, "External resources", "Web resources under management")
+
+  Boundary(lws, "LWS server") {
+    Container(authn, "Authentication", "Validates credential against identity provider")
+    Container(authz, "Authorization", "Enforces resource manager access decisions")
+    Container(rm, "Resource Management", "Manages containers, containment and linksets")
+    Container(era, "External Resource Access", "Mediates access to external web resources")
+  }
+
+  Rel(user, client, "uses")
+  Rel(client, authn, "presents credential")
+  Rel(authn, idp, "validates credential")
+  Rel(authn, authz, "confirmed identity")
+  Rel(authz, rm, "permitted operation")
+  Rel(rm, era, "resolves resource")
+  Rel(era, ext, "accesses")
+```
+Issue: The internal organisation of container, containment and linkset management within the LWS server is not yet defined in the protocol. This diagram reflects current terminology and is subject to revision.

lws10-core/index.html

@@ -171,8 +171,36 @@ <h2>Security and Privacy</h2>
           A <dfn>LWS Client</dfn> is an HTTP client [[!rfc9112]] that complies with all of the relevant "MUST" statements in this specification. Specifically, the relevant normative "MUST" statements in <a href="#operations"></a> of this document MUST be respected.
         </p>
       </section>
-    </section>
 
+      <section id="scope-diagrams">    <!-- becomes 2.4 Scope Diagrams -->
+        <h2>Scope Diagrams</h2>
+        <p>
+          The following diagrams are platform-independent models 
+          to guide implementation.
+        </p>
+        <p>
+          Figure 1 shows the System Context, identifying the user, the systems 
+          that interact with a compliant LWS server, and the external systems on 
+          which the protocol depends.
+        </p>
+        <figure id="fig-1-system-context">
+          <img src="diagrams/fig-1-system-context.svg" 
+              alt="LWS Protocol system context diagram showing the user, client application, LWS server, identity provider, and external resources"/>
+          <figcaption>LWS Protocol &mdash; system context (C4 Level 1)</figcaption>
+        </figure>
+        <p>
+          Figure 2 shows the Container Diagram, describing the protocol-level 
+          responsibilities within a compliant LWS server and the relationships 
+          between them.
+        </p>
+        <figure id="fig-2-container-diagram">
+          <img src="diagrams/fig-2-container-diagram.svg"
+              alt="LWS Protocol container diagram showing authentication, authorization, resource management, and external resource access within the LWS server boundary"/>
+          <figcaption>LWS Protocol &mdash; container diagram (C4 Level 2)</figcaption>
+        </figure>
+     </section>
+
+    </section>
     <section id="terminology">
       <h2>Terminology</h2>
       <p>