docs(spec): cite the /ai/models picker decision as cloud ADR-0028

.changeset/24486-spec-cloud-adr-0028-citation.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+Clause-②: no
+
+docs(spec): the `GET /api/v1/ai/models` response JSDoc cites `cloud ADR-0028`, not a bare `ADR-0028`
+
+- **What changed.** The JSDoc on `AiModelsResponseSchema` and on its `models` field now cites `cloud ADR-0028` (the plan-filtered AI model picker decision) where it cited a bare `ADR-0028`. This repository's own ADR-0028 is about metadata naming and namespace isolation; the AI service that serves this list is a cloud package. The client SDK TSDoc and the docs already cite it this way.
+- **Unchanged.** Every schema shape, `.describe()` string, generated JSON Schema and behaviour.

packages/spec/src/api/protocol.test.ts

@@ -372,7 +372,7 @@ describe('ObjectStack Protocol', () => {
     expect(AiCompleteRequestSchema.safeParse({ prompt: 'Summarise:', options: { maxTokens: 64 } }).success).toBe(true);
     expect(AiCompleteRequestSchema.safeParse({}).success).toBe(false);
 
-    // models — both live shapes: the ADR-0028 allowlist and the bare-id fallback
+    // models — both live shapes: the cloud ADR-0028 allowlist and the bare-id fallback
     expect(AiModelsResponseSchema.safeParse({
       models: [{ id: 'gpt-4o-mini', label: 'GPT-4o mini', default: true }], defaultModel: 'gpt-4o-mini',
     }).success).toBe(true);

packages/spec/src/api/protocol.zod.ts

@@ -3396,10 +3396,10 @@ export const AiCompleteRequestSchema = lazySchema(() => z.object({
   options: z.record(z.string(), z.unknown()).optional().describe('Request options (model, temperature, maxTokens, …)'),
 }));
 
-/** `GET /api/v1/ai/models` — the environment's plan-filtered picker list (ADR-0028). */
+/** `GET /api/v1/ai/models` — the environment's plan-filtered picker list (cloud ADR-0028). */
 export const AiModelsResponseSchema = lazySchema(() => z.object({
   /**
-   * Objects when the service exposes the ADR-0028 allowlist; bare ids when it
+   * Objects when the service exposes the cloud ADR-0028 allowlist; bare ids when it
    * falls back to the adapter's `listModels()`. Both shapes are live, so both
    * are declared rather than one being asserted and the other 404-by-parse.
    */