From b729866ea50ec5ebbbb81c5895241b2e07b1eb9f Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 12:00:26 +0100
Subject: [PATCH 01/11] XC-02: name the key-creation 200 exception on
 customer.mdx#keys

Session-0 ruling (2026-08-06): create-POSTs return 201 with exactly two
named action-POST exceptions (key creation, application setup). The
keys section now states the exception so the 200 is read as deliberate,
not drift.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/src/content/docs/api-doc/customer.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/src/content/docs/api-doc/customer.mdx b/src/src/content/docs/api-doc/customer.mdx
index d2678a5..8914d5d 100644
--- a/src/src/content/docs/api-doc/customer.mdx
+++ b/src/src/content/docs/api-doc/customer.mdx
@@ -490,6 +490,8 @@ Api keys allocated to this customer. The accompanying secret is only available a
 | POST | Create a new key | - | vocab:Key (with secret, once) | 200 OK |
 | DELETE | Delete an individual key, at `/customers/{customer}/keys/{key}` | - | - | 204 No Content, 400 Bad request |
 
+The POST here is a deliberate exception to the platform's usual convention that a create returns `201 Created`: it is an _action_ returning a one-time payload — the key and its secret — rather than the creation of a resource you can fetch again, so it returns `200 OK`. The secret is never available at any URL afterwards.
+
 The returned collection has `vocab:key` members like this:
 
 ```

From d7b96518a30b8222b044684179c2d1c9384f1283 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 12:00:43 +0100
Subject: [PATCH 02/11] ACC-12 (remainder): custom-header PUT row gains its 404

UpdateCustomHeader returns WriteResult.NotFound when the header does
not exist; the row listed only 200/400. This was the part of ACC-12
held back pending the ACC-15 ruling - now ruled (session 0,
2026-08-06): PUT-update returns 200 (protagonist hygiene/session-0
fixes the handler that returned 201), so the documented 200 stands.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/src/content/docs/api-doc/custom-headers.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/src/content/docs/api-doc/custom-headers.mdx b/src/src/content/docs/api-doc/custom-headers.mdx
index 1c9de4c..45489c4 100644
--- a/src/src/content/docs/api-doc/custom-headers.mdx
+++ b/src/src/content/docs/api-doc/custom-headers.mdx
@@ -28,7 +28,7 @@ A `CustomHeader` resource is created by POSTing to the [customer.customHeaders](
 | Method | Label | Expects | Returns | Status |
 |:---|:---|:---|:---|:---|
 | GET | Retrieve a custom header | - | vocab:CustomHeader | 200 OK, 404 Not Found |
-| PUT | Update a custom header | vocab:CustomHeader | vocab:CustomHeader | 200 OK, 400 Bad Request |
+| PUT | Update a custom header | vocab:CustomHeader | vocab:CustomHeader | 200 OK, 400 Bad Request, 404 Not Found |
 | DELETE | Delete a custom header | - | - | 204 No Content, 404 Not Found |
 
 <Aside type="note">

From 59135ab303802b3070eb1880bf0f9a8ab351b422 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 12:00:43 +0100
Subject: [PATCH 03/11] SPA-19 (sample half): delete orphan
 update_credentials.py

Session-0 ruling (2026-08-06): the phantom credentials PUT operation is
removed from the Hydra model (protagonist hygiene/session-0); this
sample demoed that never-implemented /credentials sub-resource. The
sub-resource prose and its original status-code table are preserved in
scratch/api-doc/origin-strategy.md. Credentials updates via full-object
PUT are covered by get_put_delete_origin_strategy.py.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../update_credentials.py                     | 57 -------------------
 1 file changed, 57 deletions(-)
 delete mode 100644 dlcs-docs-client/p12_origin_strategies/update_credentials.py

diff --git a/dlcs-docs-client/p12_origin_strategies/update_credentials.py b/dlcs-docs-client/p12_origin_strategies/update_credentials.py
deleted file mode 100644
index 9d6a9d5..0000000
--- a/dlcs-docs-client/p12_origin_strategies/update_credentials.py
+++ /dev/null
@@ -1,57 +0,0 @@
-import settings
-from iiif_cs import get_cloud_services_resource, post_resource, put_resource, delete_resource, pprint
-
-
-def setup_origin_strategy():
-    """Create a CustomerOriginStrategy to use in this example."""
-    path = f"/customers/{settings.IIIF_CS_CUSTOMER_ID}/originStrategies"
-    origin_strategy = {
-        "strategy": "basic-http-authentication",
-        "regex": "https\\:\\/\\/credentials-example\\.com\\/.*",
-        "credentials": '{ \"user\": \"original-user\", \"password\": \"original-password\" }',
-        "optimised": False,
-        "order": 1
-    }
-    r = post_resource(path, origin_strategy)
-    result = r.json()
-    print("Created CustomerOriginStrategy:")
-    pprint(result)
-    print()
-    return result
-
-# TODO: This is not implemented yet
-def update_credentials(origin_strategy_url):
-    """PUT to the credentials sub-resource to update stored credentials.
-    The request body is an escaped JSON string, not a JSON object."""
-    credentials_url = origin_strategy_url + "/credentials"
-    new_credentials = '{ "user": "updated-user", "password": "updated-password" }'
-    r = put_resource(credentials_url, new_credentials)
-    print("PUT credentials returned:")
-    print(f"HTTP Status Code: {r.status_code}")
-    print()
-
-
-def delete_credentials(origin_strategy_url):
-    """DELETE the stored credentials from a CustomerOriginStrategy."""
-    credentials_url = origin_strategy_url + "/credentials"
-    delete_resource(credentials_url)
-
-
-if __name__ == '__main__':
-    origin_strategy = setup_origin_strategy()
-    origin_strategy_url = origin_strategy["@id"]
-
-    # Update credentials - note: no GET is available, credentials always show as "xxx"
-    update_credentials(origin_strategy_url)
-
-    # GET the strategy to confirm it still works (credentials still shown as "xxx")
-    r = get_cloud_services_resource(origin_strategy_url)
-    print("GET after credentials update:")
-    pprint(r.json())
-    print()
-
-    # DELETE the credentials
-    delete_credentials(origin_strategy_url)
-
-    # Clean up
-    delete_resource(origin_strategy_url)

From 9030ccba8aabe99b69beadafcd8f3e8f9d664e26 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 12:15:54 +0100
Subject: [PATCH 04/11] XC-04: document the batch /test success shape + its 404

Session-0 ruling (2026-08-06): the /test endpoint's plain {success}
JSON body is kept and documented as a deliberate exception (the last
non-Hydra shape on the API). Also adds the 404 (unknown batch ->
HydraNotFound, CustomerQueueController).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/src/content/docs/api-doc/batch.mdx | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/src/content/docs/api-doc/batch.mdx b/src/src/content/docs/api-doc/batch.mdx
index ad8c7bb..75eec44 100644
--- a/src/src/content/docs/api-doc/batch.mdx
+++ b/src/src/content/docs/api-doc/batch.mdx
@@ -153,7 +153,15 @@ An HTTP POST to this resource will update the batch's [superseded](#superseded)
 
 | Method | Label | Expects | Returns | Status |
 |:---|:---|:---|:---|:---|
-| POST | Force an update of the batch.superseded property. | - | JSON object with single success property (boolean). | 200 OK |
+| POST | Force an update of the batch.superseded property. | - | JSON object with single success property (boolean). | 200 OK, 404 Not Found |
+
+The response body is a plain JSON object, not a Hydra resource — a deliberate exception for this action endpoint:
+
+```json
+{ "success": true }
+```
+
+`success` is `true` when the test resulted in an update to the batch (marking it superseded and/or finished), and `false` when the batch was tested but no changes were needed. Either way the test itself succeeded — `false` is not an error.
 
 ## Adjunct Batch
 

From 614bc84de74099a34df676d6a0dd9679275725ca Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 12:42:14 +0100
Subject: [PATCH 05/11] XC-08: identifiers.mdx becomes the identifier exception
 register

Session-0 ratification (2026-08-06): resources are addressed by id
unless listed in the register; exactly two exceptions today
(DeliveryChannelPolicy addressed by name; NamedQuery has a name but is
addressed by id). New name-addressed resources must be registered in
the same PR that introduces them. Drive-by: fixes the broken
#assetidentifiers anchor in asset.mdx (#asset-identifiers).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/src/content/docs/api-doc/asset.mdx       |  2 +-
 src/src/content/docs/api-doc/identifiers.mdx | 10 +++++++---
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/src/content/docs/api-doc/asset.mdx b/src/src/content/docs/api-doc/asset.mdx
index 2df3f46..5003b17 100644
--- a/src/src/content/docs/api-doc/asset.mdx
+++ b/src/src/content/docs/api-doc/asset.mdx
@@ -127,7 +127,7 @@ text/plain
 
 ## space
 
-The integer identifier of the customer Space. This is readonly on an asset except when sent in a batch to the queue (see [registering assets](../registering-assets)), where a single batch of assets may be intended for different spaces. That is, you can set it on an asset that has yet to be given an `@id` within the system. After this point the value of `space` will always match the space part of the [asset identifier](../identifiers#assetidentifiers). You do not need to supply it on API operations other than creation of assets to the queue, but if you do, it must match the expected space from the asset ID.
+The integer identifier of the customer Space. This is readonly on an asset except when sent in a batch to the queue (see [registering assets](../registering-assets)), where a single batch of assets may be intended for different spaces. That is, you can set it on an asset that has yet to be given an `@id` within the system. After this point the value of `space` will always match the space part of the [asset identifier](../identifiers#asset-identifiers). You do not need to supply it on API operations other than creation of assets to the queue, but if you do, it must match the expected space from the asset ID.
 
 | domain | range | readonly | writeonly |
 |:---|:---|:---|:---|
diff --git a/src/src/content/docs/api-doc/identifiers.mdx b/src/src/content/docs/api-doc/identifiers.mdx
index fa99eb1..75dca49 100644
--- a/src/src/content/docs/api-doc/identifiers.mdx
+++ b/src/src/content/docs/api-doc/identifiers.mdx
@@ -46,11 +46,15 @@ The model `id` of an asset must be unique within its space. Unlike other resourc
 
 You are free to use any string as an asset `id`, but it will appear in URLs so it should be URL-safe. Common choices are filenames (with or without the extension), or opaque identifiers like shelfmarks or catalogue references.
 
-## Resources that use `name` instead of `id`
+## The identifier exception register
 
-Most resources follow the convention above, where the `id` property holds the model identifier and becomes the last path element of the `@id`. However, some resources use a `name` property for this purpose instead. The notable example is `DeliveryChannelPolicy` (where `name` becomes the last segment of `/customers/{customer}/deliveryChannelPolicies/{channel}/{name}`). (Note: `NamedQuery` also has a `name` property, but unlike `DeliveryChannelPolicy` it is addressed by a minted `id`, not its `name`.)
+Resources are addressed by `id`, following the convention above — unless they are listed here. This section is the authoritative register of exceptions: any new resource addressed by something other than `id` must be added to this register in the same pull request that introduces it.
 
-The behaviour is the same as for `id` elsewhere: the value you supply becomes a permanent part of the resource's URI, you choose it yourself, and it must be unique within its parent collection. When creating a `DeliveryChannelPolicy` via PUT the `name` is taken from the URL path rather than the request body; when creating via POST to the parent collection the `name` must be present in the body.
+There are exactly two registered exceptions:
+
+1. **`DeliveryChannelPolicy` is addressed by `name`.** Its `name` becomes the last segment of `/customers/{customer}/deliveryChannelPolicies/{channel}/{name}`. The behaviour is the same as for `id` elsewhere: the value you supply becomes a permanent part of the resource's URI, you choose it yourself, and it must be unique within its parent collection. When creating a `DeliveryChannelPolicy` via PUT the `name` is taken from the URL path rather than the request body; when creating via POST to the parent collection the `name` must be present in the body.
+
+2. **`NamedQuery` has a human-readable `name` property but is still addressed by `id`.** The `name` is how the query is invoked in public-facing resource URLs; the API resource itself is addressed by a minted GUID `id`.
 
 ## Compact URIs
 

From a0527f9994e81344c7bf446e5af9e083a9cb3817 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 13:45:03 +0100
Subject: [PATCH 06/11] XC-10: label the intentional 405 demos as deliberate
 failures

Session-0 ratification (2026-08-06): sample parity is a rule for main;
the p02_registering/p06_space POST-to-space samples deliberately
demonstrate the 405 and are now labelled so they read as demos, not
drift. The scheduled-sample-runs idea is parked as issue #11.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 dlcs-docs-client/p02_registering/post.py   | 5 ++++-
 dlcs-docs-client/p06_space/space_images.py | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/dlcs-docs-client/p02_registering/post.py b/dlcs-docs-client/p02_registering/post.py
index aaf72b5..8b2e981 100644
--- a/dlcs-docs-client/p02_registering/post.py
+++ b/dlcs-docs-client/p02_registering/post.py
@@ -4,7 +4,10 @@
 from settings import docs_space_id, docs_space_name
 
 
-# Not yet supported. Returns HTTP 405 Method Not Allowed
+# INTENTIONAL error demo - this sample is *supposed* to fail.
+# Direct POST of a single asset to a space is not supported; the platform
+# returns HTTP 405 Method Not Allowed. Register assets with PUT, or POST a
+# collection to the queue instead (see registering-assets).
 def post_asset():
     space = docs_space_id
     ensure_space(space, docs_space_name)
diff --git a/dlcs-docs-client/p06_space/space_images.py b/dlcs-docs-client/p06_space/space_images.py
index 0f0116b..014c817 100644
--- a/dlcs-docs-client/p06_space/space_images.py
+++ b/dlcs-docs-client/p06_space/space_images.py
@@ -28,7 +28,10 @@ def get_images_with_query():
     print()
 
 
-# Not yet supported. Returns HTTP 405 Method Not Allowed
+# INTENTIONAL error demo - this sample is *supposed* to fail.
+# Direct POST of a single asset to a space is not supported; the platform
+# returns HTTP 405 Method Not Allowed. Register assets with PUT, or POST a
+# collection to the queue instead (see registering-assets).
 def post_asset():
     ensure_space(docs_space_id, docs_space_name)
     asset = {

From e16c202c0eca6087ad645c21b34cb2a328a7aa53 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 13:49:23 +0100
Subject: [PATCH 07/11] XC-12: document whole-container status semantics for
 multi-adjunct POST

Session-0 ruling (2026-08-06): option (a) - the status code applies to
the container operation, not its members. A multi-member upsert returns
201 only when every member was created; 200 if any member updated.
Documented on the released surface (adjuncts.mdx bulk POST); the
adjunct-queue twin is release-gated and its wording is parked in
scratch/api-doc/queues.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 scratch/api-doc/queues.md                 | 10 ++++++++++
 src/src/content/docs/api-doc/adjuncts.mdx |  2 ++
 2 files changed, 12 insertions(+)

diff --git a/scratch/api-doc/queues.md b/scratch/api-doc/queues.md
index d2ce031..9ffda4b 100644
--- a/scratch/api-doc/queues.md
+++ b/scratch/api-doc/queues.md
@@ -103,3 +103,13 @@ release-gated; fix them with the same wording when the adjunct queue ships.
 
 **Disposition: probably-drop** (superseded by code reality). Restore only if batch
 activation ever becomes start-of-processing rather than submission.
+
+## XC-12 ruling — batch upsert status semantics (for the adjunct-queue docs when released)
+
+Session 0 (2026-08-06) ruled: the status describes the AGGREGATE outcome of the
+request, not itemised per-member results — 201 only when every member was newly
+created (RFC 9110 permits 201 for "one or more new resources"), 200 when any member
+updated existing state. A 201 therefore always means everything in the request is
+new. When the adjunct-queue sections are promoted (PRO-08 release gate), state this
+on the queue POST rows using the same wording as adjuncts.mdx "Registering multiple
+adjuncts".
diff --git a/src/src/content/docs/api-doc/adjuncts.mdx b/src/src/content/docs/api-doc/adjuncts.mdx
index fa20d96..7447ee3 100644
--- a/src/src/content/docs/api-doc/adjuncts.mdx
+++ b/src/src/content/docs/api-doc/adjuncts.mdx
@@ -265,6 +265,8 @@ POST https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/adj
 ]
 ```
 
+The response status code describes the aggregate outcome of the request — per-member results are not itemised. A multi-adjunct POST returns `201 Created` when every member was newly created, and `200 OK` when any member updated an existing adjunct; a `201` from this endpoint therefore always means everything in the request is new. (This follows [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#section-15.3.2), which defines `201` as a request that resulted in "one or more new resources" being created.)
+
 If an adjunct needs to be access-controlled, it specifies [roles](../asset#roles) in the same way assets do, and the platform will emit IIIF Auth services when referencing the adjunct in a manifest.
 
 <Aside type="caution">

From c2b004be7af4555d0c43549aaf27e2a8a7ca4bd2 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 14:07:52 +0100
Subject: [PATCH 08/11] XC-13 (docs half): remove phantom
 completedImages/errorImages from batch example

Session-0 ruling (2026-08-06): no such routes exist (the #899 examples)
and protagonist PR #1238 removes the links from the model; the example
showed links that 404 today, so removing them is correct against
released behaviour too. Filter batch images with the asset-query syntax
on the images collection instead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/src/content/docs/api-doc/batch.mdx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/src/content/docs/api-doc/batch.mdx b/src/src/content/docs/api-doc/batch.mdx
index 75eec44..b275287 100644
--- a/src/src/content/docs/api-doc/batch.mdx
+++ b/src/src/content/docs/api-doc/batch.mdx
@@ -33,8 +33,6 @@ Old batches are kept on the platform for at least a year but are eventually arch
     "superseded": false,
     "images": "https://api.dlcs.example/customers/2/queue/batches/875629/images",
     "assets": "https://api.dlcs.example/customers/2/queue/batches/875629/assets",
-    "completedImages": "https://api.dlcs.example/customers/2/queue/batches/875629/completedImages",
-    "errorImages": "https://api.dlcs.example/customers/2/queue/batches/875629/errorImages",
     "test": "https://api.dlcs.example/customers/2/queue/batches/875629/test"
 }
 ```

From 0bdede522eb61e90eced841b51a0fe6274d17f97 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 14:08:52 +0100
Subject: [PATCH 09/11] PRO-05: GET priority queue is supported - document it +
 sample

Session-0 ruling (2026-08-06), option (a): GET is intended
(GetCustomerPriorityQueue, CustomerQueueController.cs:149-163). Removes
the "GET is not supported" claim, adds the GET row, and the sample now
GETs the priority queue too (closing that XC-10 coverage gap). LinkCard
description still fits (the sample's primary purpose is the POST).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../p08_queue/post_to_priority_queue.py            | 14 +++++++++++++-
 src/src/content/docs/api-doc/queues.mdx            |  3 ++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/dlcs-docs-client/p08_queue/post_to_priority_queue.py b/dlcs-docs-client/p08_queue/post_to_priority_queue.py
index ff98805..a5eb0e1 100644
--- a/dlcs-docs-client/p08_queue/post_to_priority_queue.py
+++ b/dlcs-docs-client/p08_queue/post_to_priority_queue.py
@@ -1,9 +1,20 @@
 import settings
-from iiif_cs import post_resource, pprint
+from iiif_cs import get_cloud_services_resource, post_resource, pprint
 from p06_space.ensure_space import ensure_space
 from settings import docs_space_id, docs_space_name
 
 
+def get_priority_queue():
+    """GET the priority queue - a CustomerQueue resource with its own counts."""
+    path = f"/customers/{settings.IIIF_CS_CUSTOMER_ID}/queue/priority"
+    r = get_cloud_services_resource(path)
+    print("GET Priority Queue returned:")
+    queue = r.json()
+    pprint(queue)
+    print()
+    return queue
+
+
 def post_to_priority_queue():
     """POST a collection of assets to the priority queue for faster processing."""
     ensure_space(docs_space_id, docs_space_name)
@@ -30,4 +41,5 @@ def post_to_priority_queue():
 
 
 if __name__ == '__main__':
+    get_priority_queue()
     post_to_priority_queue()
diff --git a/src/src/content/docs/api-doc/queues.mdx b/src/src/content/docs/api-doc/queues.mdx
index b98c3ff..43fa1cb 100644
--- a/src/src/content/docs/api-doc/queues.mdx
+++ b/src/src/content/docs/api-doc/queues.mdx
@@ -145,10 +145,11 @@ This endpoint acts in the same way as `/customers/{customer}/queue`, but any bat
 
 `/customers/{customer}/queue/priority`
 
-Note that GET is not supported. Batches sent to the priority queue will be visible in the batch collections available on the main queue: [batches](#batches), [active](#active) and [recent](#recent). The only difference is that they will be picked up and processed sooner when sent to the priority queue - so a batch may appear sooner in [recent](#recent).
+A GET returns the priority queue's own CustomerQueue resource, with its counts. Batches sent to the priority queue will also be visible in the batch collections available on the main queue: [batches](#batches), [active](#active) and [recent](#recent). The only difference is that they will be picked up and processed sooner when sent to the priority queue - so a batch may appear sooner in [recent](#recent).
 
 | Method | Label | Expects | Returns | Status |
 |:---|:---|:---|:---|:---|
+| GET | View the priority queue | - | vocab:CustomerQueue | 200 OK, 404 Not Found |
 | POST | Submit a collection of Assets (vocab:Image) and get a batch back | hydra:Collection | vocab:Batch | 201 Created |
 
 <Aside type="caution">

From 0372faeb627158fb11078dd1e5a02265db2bdf99 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 14:09:41 +0100
Subject: [PATCH 10/11] DIS-01 + DIS-02: ordering and include=adjuncts are real
 - promote

Session-0 rulings (2026-08-06): DIS-01 options (a)+(b) - restore the
### Ordering section (orderBy/orderByDescending; default order is
created, answering the old doc's open question), de-list ordering from
the caution Aside. DIS-02 option (a) - de-list include from the Aside;
the body already documented include=adjuncts, resolving the internal
contradiction. Both share the single Aside sentence, hence one commit
for two cards. Sample docstrings were already fixed in PR #7. Scratch
ordering note marked promoted; the DIS-06 no-whitelist nuance stays
parked there.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 scratch/api-doc/asset-queries.md               |  2 +-
 src/src/content/docs/api-doc/asset-queries.mdx | 13 ++++++++++++-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/scratch/api-doc/asset-queries.md b/scratch/api-doc/asset-queries.md
index 961fee2..01c8274 100644
--- a/scratch/api-doc/asset-queries.md
+++ b/scratch/api-doc/asset-queries.md
@@ -9,7 +9,7 @@ These examples belong in the `### Query object` section once supported:
 ?q={"id":"PHOTO.2.22.36.2.tif"}
 ```
 
-# Ordering — ⟳ IMPLEMENTED, restore (verified 2026-08-03, DIS-01) — **restore-candidate**
+# Ordering — ✅ PROMOTED 2026-08-06 (session 0, DIS-01 ruling): `### Ordering` section restored to asset-queries.mdx with default = `created`. Kept below for the DIS-06 nuance (no field whitelist; unknown field → handled Hydra 500 not 400) which is NOT yet documented — that's DIS-06's call.
 
 You can order by the value of a field of an asset:
 
diff --git a/src/src/content/docs/api-doc/asset-queries.mdx b/src/src/content/docs/api-doc/asset-queries.mdx
index b72d355..a00c953 100644
--- a/src/src/content/docs/api-doc/asset-queries.mdx
+++ b/src/src/content/docs/api-doc/asset-queries.mdx
@@ -8,7 +8,7 @@ sidebar:
 import { Aside, LinkCard } from '@astrojs/starlight/components';
 
 <Aside type="caution">
-  These features are still under development. Queries based on `string1`, `string2`, `string3`, `number1`, `number2` and `number3` are supported. `tags`, `roles`, `id` queries, ordering, `include` and multiple values are not yet supported.
+  These features are still under development. Queries based on `string1`, `string2`, `string3`, `number1`, `number2` and `number3` are supported, as are [ordering](#ordering) and [include](#include-children). `tags`, `roles`, `id` queries and multiple values are not yet supported.
 </Aside>
 
 Any hyperlink to a collection of assets can accept query parameters that filter the returned assets.
@@ -47,6 +47,17 @@ Only the 6 built-in string and number fields are supported.
 ?q={"string1":"my-value","number1":99}&pageSize=10&page=2
 ```
 
+### Ordering
+
+You can order results by the value of a field of an asset:
+
+```
+?orderBy=height
+?orderByDescending=width
+```
+
+The field can be one of the metadata shortcut names above (`string1`, `number2`, ...) or any asset property (e.g., `width`, `height`, `created`). If no ordering is provided, results are ordered by `created`.
+
 ### Include Children
 
 The only accepted value is `adjuncts`.

From 1fa0e9c8958f78ae618f0580afc75b2064952e14 Mon Sep 17 00:00:00 2001
From: tomcrane <tom@nanoplanet.com>
Date: Wed, 5 Aug 2026 14:12:04 +0100
Subject: [PATCH 11/11] DIS-25: correct iiif-av Choice prose + audio example;
 document no-canvas

Session-0 ruling (2026-08-06), verified against
ManifestV3Builder.HandleTimebasedAsset: a single transcode gets a bare
Sound/Video painting body; Choice only wraps multiple outputs; an
iiif-av asset with no transcoded outputs gets no canvas at all (even
with a file channel alongside). Audio example de-Choiced and its
annotation id corrected to .../page/image (builder uses
{canvasId}/page/image for timebased too). Originals preserved in
scratch/api-doc/single-asset-manifest.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 scratch/api-doc/single-asset-manifest.md      | 21 ++++++++++++++++++-
 .../docs/api-doc/single-asset-manifest.mdx    | 21 +++++++------------
 2 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/scratch/api-doc/single-asset-manifest.md b/scratch/api-doc/single-asset-manifest.md
index 2ef251b..8f01759 100644
--- a/scratch/api-doc/single-asset-manifest.md
+++ b/scratch/api-doc/single-asset-manifest.md
@@ -59,4 +59,23 @@ The behaviour for file-only assets (placeholder image, `placeholder` and `origin
 
 removed from copy:
 
-In addition to the above, the single asset manifest has an extension property `dlcs:channelOutputs`: an array of content resources and services, one per delivery channel output, each including the channel it belongs to. This is more consistent in structure than the regular manifest properties and can be used for quick programmatic access to channel outputs.
\ No newline at end of file
+In addition to the above, the single asset manifest has an extension property `dlcs:channelOutputs`: an array of content resources and services, one per delivery channel output, each including the channel it belongs to. This is more consistent in structure than the regular manifest properties and can be used for quick programmatic access to channel outputs.
+## Replaced prose preserved (DIS-25, session 0, 2026-08-06)
+
+Original iiif-av bullet (single-asset-manifest.mdx:27), replaced per the DIS-25 ruling:
+
+> For the `iiif-av` delivery channel, the body of the painting annotation is a `Choice` resource listing all the transcoded outputs.
+
+And the audio-example prose:
+
+> The painting body is a `Choice` wrapping the single transcoded output.
+
+**Why changed:** ManifestV3Builder.HandleTimebasedAsset uses a bare `Sound`/`Video`
+body when `transcodes.Length == 1` and `PaintingChoice` only for several; an asset
+with no transcode metadata gets no canvas at all. The old doc's own "(?)" question
+is answered by the code in the opposite direction. The audio example's `Choice`
+wrapper was removed and its annotation id corrected to `.../page/image` (the
+builder uses `{canvasId}/page/image` for timebased assets too).
+
+**Disposition: probably-drop** (superseded by code reality). Restore only if
+always-Choice is ever made the contract (the room chose not to).
diff --git a/src/src/content/docs/api-doc/single-asset-manifest.mdx b/src/src/content/docs/api-doc/single-asset-manifest.mdx
index fccfc0b..c57dd06 100644
--- a/src/src/content/docs/api-doc/single-asset-manifest.mdx
+++ b/src/src/content/docs/api-doc/single-asset-manifest.mdx
@@ -24,7 +24,7 @@ The single asset manifest is a public IIIF resource served by the platform, not
 ```
 
 - For the `iiif-img` delivery channel, the body of the painting annotation is a full/max parameterisation of the v3 image service, with that image service as a `service` property of the body image.
-- For the `iiif-av` delivery channel, the body of the painting annotation is a `Choice` resource listing all the transcoded outputs. Each output is a Content Resource with width, height and/or duration, mediaType, label, and additional profile information where available (e.g., codec).
+- For the `iiif-av` delivery channel, the body of the painting annotation is the transcoded output itself (a `Sound` or `Video` Content Resource) when there is a single transcode, or a `Choice` resource listing all the transcoded outputs when there are several. Each output is a Content Resource with width, height and/or duration, mediaType, label, and additional profile information where available (e.g., codec). An `iiif-av` asset with **no** transcoded outputs gets no canvas in the manifest at all — even if it also has the `file` delivery channel.
 - If the asset is an image and _does not have_ the `iiif-img` delivery channel but does have the `thumbs` delivery channel, the body of the painting annotation is a full/max parameterisation of the v3 _thumbnail_ image service.
 
 If the asset has the `iiif-img` delivery channel, the body of the painting annotation has two services, one for v2 and one for v3 of the Image API. If the asset has access control, the auth services are included inline on the image services.
@@ -389,7 +389,7 @@ The same image as above with four adjuncts, one for each `iiifLink` value. The `
 
 ### Audio with iiif-av
 
-An audio asset on the `iiif-av` delivery channel. The canvas has only `duration` — no visual dimensions and no thumbnail. The painting body is a `Choice` wrapping the single transcoded output.
+An audio asset on the `iiif-av` delivery channel. The canvas has only `duration` — no visual dimensions and no thumbnail. The painting body is the single transcoded output as a bare `Sound` resource — a `Choice` is only used when there are several outputs (see the video example below).
 
 ```json
 {
@@ -423,20 +423,15 @@ An audio asset on the `iiif-av` delivery channel. The canvas has only `duration`
                     "type": "AnnotationPage",
                     "items": [
                         {
-                            "id": "https://dlcs.example/iiif-av/2/5/my-audio.mp3/canvas/c/1/page/audio",
+                            "id": "https://dlcs.example/iiif-av/2/5/my-audio.mp3/canvas/c/1/page/image",
                             "type": "Annotation",
                             "motivation": "painting",
                             "body": {
-                                "type": "Choice",
-                                "items": [
-                                    {
-                                        "id": "https://dlcs.example/iiif-av/2/5/my-audio.mp3/mp3-320",
-                                        "type": "Sound",
-                                        "format": "audio/mpeg",
-                                        "duration": 300,
-                                        "label": {"en": ["MP3 320kbps"]}
-                                    }
-                                ]
+                                "id": "https://dlcs.example/iiif-av/2/5/my-audio.mp3/mp3-320",
+                                "type": "Sound",
+                                "format": "audio/mpeg",
+                                "duration": 300,
+                                "label": {"en": ["MP3 320kbps"]}
                             },
                             "target": "https://dlcs.example/iiif-av/2/5/my-audio.mp3/canvas/c/1"
                         }