diff --git a/lws10-core/diagrams/fig1-system-context.png b/lws10-core/diagrams/fig1-system-context.png
new file mode 100644
index 0000000..0a934b3
Binary files /dev/null and b/lws10-core/diagrams/fig1-system-context.png differ
diff --git a/lws10-core/diagrams/fig2-container-diagram.png b/lws10-core/diagrams/fig2-container-diagram.png
new file mode 100644
index 0000000..710275d
Binary files /dev/null and b/lws10-core/diagrams/fig2-container-diagram.png differ
diff --git a/lws10-core/diagrams/fig3-lws-server-components.png b/lws10-core/diagrams/fig3-lws-server-components.png
new file mode 100644
index 0000000..67edbf8
Binary files /dev/null and b/lws10-core/diagrams/fig3-lws-server-components.png differ
diff --git a/lws10-core/diagrams/fig4-resource-hierarchy.png b/lws10-core/diagrams/fig4-resource-hierarchy.png
new file mode 100644
index 0000000..aaba986
Binary files /dev/null and b/lws10-core/diagrams/fig4-resource-hierarchy.png differ
diff --git a/lws10-core/diagrams/figures.md b/lws10-core/diagrams/figures.md
new file mode 100644
index 0000000..743588b
--- /dev/null
+++ b/lws10-core/diagrams/figures.md
@@ -0,0 +1,64 @@
+# Figures
+
+A set of composition diagrams that models the [Linked Web Storage Protocol](https://w3c.github.io/lws-protocol/lws10-core/) specification.
+
+## Figure 1 - System Context Diagram
+
+Shows the LWS System as a single unit and the person who uses it. Establishes scope only — no internal structure is shown.
+
+
+
+| Box | Description |
+|---|---|
+| Agent | An agent of the LWS system |
+| LWS System | A system that implements the LWS Protocol |
+
+## Figure 2 - Container Diagram
+
+Breaks the LWS System into its primary elements.
+
+
+
+| Box | Description |
+|---|---|
+| Agent | An agent of the LWS system |
+| LWS System | A system that implements the LWS Protocol |
+| LWS Client | An HTTP client that complies with the LWS Protocol |
+| LWS Server | An HTTP server that complies with the LWS Protocol |
+
+## Figure 3 - LWS Server Component Diagram
+
+Decomposition of the LWS Server into components and their responsibilities from client request to storage access.
+
+
+
+| Box | Description |
+|---|---|
+| LWS Client | An HTTP client that complies with the LWS Protocol |
+| LWS Server | An HTTP server that complies with the LWS Protocol |
+| Resource Manager | Manages data resources, containers, containment and linksets |
+| Authentication | Validates credentials against the identity provider |
+| Authorization | Enforces resource manager access decisions |
+| Storage Controller | Controls all resources in the storage directed by its client resource-manager |
+| Identity Provider | Confirms user identity and issues signed credentials. MAY be an external system |
+| Storage | A set of hierarchically organized HTTP resources managed per LWS conventions |
+
+## Figure 4 - LWS Resource Type Hierarchy
+
+The resource type taxonomy and relationship defined in the specification's Terminology section.
+
+
+
+| Box | Description |
+|---|---|
+| Resource Manager | Manages data resources, containers, containment and linksets |
+| Storage | A set of hierarchically organized HTTP resources managed per LWS conventions |
+| LWS Resource | An HTTP resource that supports the read operations defined by LWS |
+| Container | An LWS resource able to enumerate a collection of LWS resources; may recursively contain other containers |
+| Data Resource | A data-bearing LWS resource such as a document, image, or structured information |
+| Auxiliary Resource | An LWS resource whose lifetime is bound to a primary resource |
+| Linkset Resource | An auxiliary resource conforming to RFC9264 |
+| Metadata Resource | An auxiliary resource, managed by a storage, that describes an LWS resource |
+| Storage Root | The container at the root of a containment hierarchy of a storage |
+| Storage Description | Enumerates the storage root and the services/capabilities of a storage |
+
diff --git a/lws10-core/diagrams/index.png b/lws10-core/diagrams/index.png
new file mode 100644
index 0000000..0a934b3
Binary files /dev/null and b/lws10-core/diagrams/index.png differ
diff --git a/lws10-core/diagrams/lws10-core.c4 b/lws10-core/diagrams/lws10-core.c4
new file mode 100644
index 0000000..bd8fdcb
--- /dev/null
+++ b/lws10-core/diagrams/lws10-core.c4
@@ -0,0 +1,161 @@
+specification {
+ element actor {
+ style {
+ shape person
+ color amber
+ }
+ }
+ element system {
+ style {
+ color blue
+ opacity 30%
+ }
+ }
+ element externalSystem {
+ style {
+ color secondary
+ opacity 30%
+ }
+ }
+ element component
+
+ element resource {
+ style {
+ shape document
+ color indigo
+ }
+ }
+
+ relationship isA {
+ color gray
+ line dashed
+ head none
+ }
+ relationship contains {
+ color gray
+ head diamond
+ }
+ relationship boundTo {
+ color gray
+ line dotted
+ head none
+ }
+ relationship describes {
+ color gray
+ line dotted
+ }
+ relationship manages
+
+ tag optional
+}
+
+model {
+ agent = actor 'Agent' {
+ description 'An agent of the LWS system'
+ }
+
+ lws = system 'LWS System' {
+ description 'A system that implements the LWS Protocol'
+ component lws-client 'LWS Client' {
+ description 'An HTTP client that complies with the LWS Protocol'
+ }
+ component lws-server 'LWS Server' {
+ description 'An HTTP server that complies with the LWS Protocol'
+
+ component identity-provider 'Identity Provider' {
+ #optional
+ description 'Confirms user identity and issues signed credentials. MAY be an external system'
+ }
+ component resource-manager 'Resource Manager' {
+ description 'Manages data resources, containers, containment and linksets'
+ }
+ component authentication 'Authentication' {
+ description 'Validates credentials against the identity provider'
+ }
+ component authorization 'Authorization' {
+ description 'Enforces resource manager access decisions'
+ }
+ component storage 'Storage' {
+ description 'A set of hierarchically organized HTTP resources managed per LWS conventions'
+
+ lws-resource = resource 'LWS Resource' {
+ description 'An HTTP resource that supports the read operations defined by LWS'
+ }
+ container = resource 'Container' {
+ description 'An LWS resource able to enumerate a collection of LWS resources; may recursively contain other containers'
+ }
+ data-resource = resource 'Data Resource' {
+ description 'A data-bearing LWS resource such as a document, image, or structured information'
+ }
+ auxiliary-resource = resource 'Auxiliary Resource' {
+ description 'An LWS resource whose lifetime is bound to a primary resource'
+ }
+ linkset-resource = resource 'Linkset Resource' {
+ description 'An auxiliary resource conforming to RFC9264'
+ }
+ metadata-resource = resource 'Metadata Resource' {
+ description 'An auxiliary resource, managed by a storage, that describes an LWS resource'
+ }
+ storage-root = resource 'Storage Root' {
+ description 'The container at the root of a containment hierarchy of a storage'
+ }
+ storage-description = resource 'Storage Description' {
+ description 'Enumerates the storage root and the services/capabilities of a storage'
+ }
+
+ container -[isA]-> lws-resource
+ data-resource -[isA]-> lws-resource
+ auxiliary-resource -[isA]-> lws-resource
+ linkset-resource -[isA]-> auxiliary-resource
+ metadata-resource -[isA]-> auxiliary-resource
+ storage-root -[isA]-> container
+ storage-description -[isA]-> lws-resource
+
+ container -[contains]-> data-resource 'contains'
+
+ auxiliary-resource -[boundTo]-> lws-resource 'bound to primary resource'
+ metadata-resource -[describes]-> lws-resource 'describes'
+ storage-description -[describes]-> storage-root 'enumerates & describes'
+ }
+
+ component storage-controller 'Storage Controller' {
+ description 'Controls all resources in the storage directed by its client resource-manager'
+ }
+ }
+
+ agent -> lws-client 'agent requests'
+ lws-client -> lws-server 'HTTP requests'
+ lws-client -> identity-provider 'authenticates'
+ lws-client -> resource-manager 'sends request'
+ resource-manager -> authentication 'authenticates request'
+ authentication -> identity-provider 'validates credentials'
+ resource-manager -> authorization 'checks permission'
+ resource-manager -> storage-controller 'acts as client to'
+ storage-controller -> storage 'controls'
+ resource-manager -[manages]-> storage-root 'manages'
+ }
+}
+
+views {
+ view fig1-system-context {
+ title 'System Context Diagram'
+ include agent, lws
+ }
+
+ view fig2-container-diagram of lws {
+ title 'Container Diagram'
+ include *
+ }
+
+ view fig3-lws-server-components of lws-server {
+ title 'LWS Server Component Diagram'
+ autoLayout TopBottom
+ include *
+ }
+
+ view fig4-resource-hierarchy of storage {
+ title 'LWS Resource Type Hierarchy'
+ autoLayout LeftRight
+ include *
+ }
+}
diff --git a/lws10-core/index.html b/lws10-core/index.html
index 01c7427..50de9c8 100644
--- a/lws10-core/index.html
+++ b/lws10-core/index.html
@@ -115,7 +115,29 @@
Document Conventions
Introduction
+ This specification defines the Linked Web Storage (LWS) Protocol, which enables client applications to access and manage web resources stored externally, based on the identity and permissions of the user.
+
+ By standardising how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other.
+
+
+ The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server as a set of JSON-LD documents (and other representations). Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses.
+
+
+ A user's identity is confirmed through an identity provider that can be external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs).
+
+
+ Authorization determines whether a requesting user has permission to access a resource or perform an operation on it. A compliant LWS server designates a resource manager for each resource that determines whether a resource is private (i.e., available only to its owner), restricted (i.e., available to a defined set of users), or public (i.e., available to any user). The server enforces the access decisions of the resource manager when handling each client request.
+
+
This specification is intended to be used by:
+
+
Developers building client applications that access a user's LWS resources
+
Server implementers building compliant LWS servers that mediate access to a user's web resources
+
+
+ Different compliant servers each maintain their own hierarchy of linked resources. A user can navigate across servers using the same identity, with access to each server's resources determined by the permissions granted by that servers resource managers.
+
+
Resource Access
@@ -155,11 +177,115 @@
Security and Privacy
- A LWS Client is an HTTP client [[!rfc9112]] that complies with all of the relevant "MUST" statements in this specification. Specifically, the relevant normative "MUST" statements in of this document MUST be respected.
+ An LWS Client is an HTTP client [[!rfc9112]] that complies with all of the relevant "MUST" statements in this specification. Specifically, the relevant normative "MUST" statements in of this document MUST be respected.
-
+
+
Scope Diagrams
+
+ The following diagrams are platform-independent models
+ to guide implementation.
+
+
+ Figure 1 System Context shows the LWS System as a single unit and the person who uses it.
+
+
+
+ System Context (C4 Level 1)
+
+
+
+
+
Box
Description
+
+
+
LWS User
A user of the LWS system
+
LWS System
A system that implements the LWS Protocol
+
+
+
+
+
+ Figure 2 Container Diagram breaks the LWS System into its primary elements.
+
+
+
+ Container diagram (C4 Level 2)
+
+
+
+
+
Box
Description
+
+
+
LWS User
A user of the LWS system
+
LWS System
A system that implements the LWS Protocol
+
LWS Client
An HTTP client that complies with the LWS Protocol
+
LWS Server
An HTTP server that complies with the LWS Protocol
+
+
+
+
+
+ Figure 3 Component Diagram decomposition of the LWS Server into components and their responsibilities from client request to storage access.
+
+
+
+ Component diagram (C4 Level 3)
+
+
+
+
+
Box
Description
+
+
+
LWS Client
An HTTP client that complies with the LWS Protocol
+
LWS Server
An HTTP server that complies with the LWS Protocol
+
Resource Manager
Manages data resources, containers, containment and linksets
+
Authentication
Validates credentials against the identity provider
+
Authorization
Enforces resource manager access decisions
+
Storage Controller
Controls all resources in the storage, directed by its client resource-manager
+
Identity Provider
Confirms user identity and issues signed credentials. MAY be an external system
+
Storage
A set of hierarchically organized HTTP resources managed per LWS conventions
+
+
+
+
+
+ Figure 4 Resource Types show taxonomy and relationship defined in the specification's Terminology section.
+
+
+
+ Resource hierarchy
+
+
+
+
+
Box
Description
+
+
+
Resource Manager
Manages data resources, containers, containment and linksets
+
Storage
A set of hierarchically organized HTTP resources managed per LWS conventions
+
LWS Resource
An HTTP resource that supports the read operations defined by LWS
+
Container
An LWS resource able to enumerate a collection of LWS resources; may recursively contain other containers
+
Data Resource
A data-bearing LWS resource such as a document, image, or structured information
+
Auxiliary Resource
An LWS resource whose lifetime is bound to a primary resource
+
Linkset Resource
An auxiliary resource conforming to RFC9264
+
Metadata Resource
An auxiliary resource, managed by a storage, that describes an LWS resource
+
Storage Root
The container at the root of a containment hierarchy of a storage
+
Storage Description
Enumerates the storage root and the services/capabilities of a storage
- The folowing section will describe the semantics and responses of these operations but the following core responses apply to any operation:
+ The following section will describe the semantics and responses of these operations but the following core responses apply to any operation:
success - the operation is believed to have completed. This may be accompanied by a resource representation conveying the contents of a served resource. A success response is not defined for the create resource operation. See instead created.
+ 
+ 
+ 
+