@k9o/core 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -28,14 +28,14 @@ export { orgPath, platformPath, projectPath, resolveBaseUrl, validateBaseUrl, va
  *   - `from('posts').update({ title: '...' }).eq(...)`  → PATCH  /@<projectSlug>/data/posts/:id
  *   - `from('posts').delete().eq('id','rec_X')`         → DELETE /@<projectSlug>/data/posts/:id
  *
- * Filters compose as AND per ch04 §3.2; multiple chained `.eq()` /
+ * Filters compose as AND; multiple chained `.eq()` /
  * `.gt()` / etc. calls all attach to the query string.
  *
- * Pagination + counting per ch01 §6.4: `.limit(n)`, `.cursor(opaque)`,
+ * Pagination + counting: `.limit(n)`, `.cursor(opaque)`,
  * `.count('none' | 'exact' | 'estimated')`. The returned envelope's
  * `meta.cursor.next` is the cursor for the next page.
  *
- * Per ch13 §4.1 KError delivery: every terminal verb throws KError on
+ * Per KError delivery: every terminal verb throws KError on
  * non-2xx. Caller catches via `instanceof KError` + narrows on `.code`.
  */
 
@@ -86,7 +86,7 @@ declare class QueryBuilder {
      */
     cursor(opaque: string): this;
     /**
-     * Total-count behaviour per ch01 §6.4. `none` (default) skips the
+     * Total-count behaviour. `none` (default) skips the
      * count query (cheapest); `exact` runs `SELECT COUNT(*)` (most
      * expensive at scale); `estimated` reads from pg_stats (fast +
      * approximate).
@@ -114,7 +114,7 @@ declare class FromBuilder {
     select<T = unknown>(): SelectBuilder<T>;
     /**
      * Insert one record. Returns the inserted record (with platform-
-     * generated `id` + `metadata`) per ch04 §6.4.
+     * generated `id` + `metadata`).
      */
     insert<T = unknown>(record: Partial<T>): Promise<Envelope<T>>;
     /**
@@ -169,19 +169,19 @@ declare function makeFromFactory(config: HttpClientConfig): (collection: string)
  *
  * The `list` + `create` operations operate org-plane and require
  * `orgSlug` to be bound on the client (or the bearer token to carry
- * an org context per ch01 §8.3). The `get` + `update` operations
+ * an org context). The `get` + `update` operations
  * operate member-plane and use the project slug.
  *
- * Per ch13 §4.1: all methods throw KError on non-2xx.
+ * Per: all methods throw KError on non-2xx.
  */
 
 /**
- * Project shape per ch02. Fields are typed per the canonical shape;
+ * Project shape. Fields are typed per the canonical shape;
  * the gateway may return additional fields that this type doesn't
  * narrow — those are accessible via `as unknown as` widening.
  */
 type Project = {
-    /** `proj_<base62>` per ch01 §3.2. */
+    /** `proj_<base62>`. */
     id: string;
     slug: string;
     name: string;
@@ -211,7 +211,7 @@ type UpdateProjectInput = {
 declare function makeProjectsNamespace(config: HttpClientConfig): {
     /**
      * List projects accessible to the caller. Requires authenticated
-     * session; results are scoped by RBAC per ch06.
+     * session; results are scoped by RBAC.
      */
     list(): Promise<Envelope<ReadonlyArray<Project>>>;
     /**
@@ -229,7 +229,7 @@ declare function makeProjectsNamespace(config: HttpClientConfig): {
 };
 
 /**
- * `client.storage` buckets and objects (ch04 §9): per-project logical buckets and the objects in them, against
+ * `client.storage` buckets and objects: per-project logical buckets and the objects in them, against
  * `/@<projectSlug>/storage/buckets…`. `client.storage.locations.*` (the customer's own object stores) lives in
  * `storage-locations.ts` and is unchanged.
  *
@@ -430,31 +430,24 @@ declare function makeStorageNamespace(config: HttpClientConfig): {
 };
 
 /**
- * `client.metadata.*` — ch14 cross-surface metadata query (`k9o.metadata.*` per ch14 §3.1).
+ * `client.metadata.*` — cross-surface metadata query (`k9o.metadata.*`).
  *
- * 🔴 Client-side surface only, built against the ch14 §3.2 REST contract and the landed Inc-1
- * parse/validate layer (`w4-ch14-metadata-query @ 3488e5c2`, unmerged as of this writing —
- * `services/gateway/src/routes/metadata-query-parse.ts`). `POST /@:projectSlug/metadata/query`
- * (Inc 2 — the route + telemetry-slice execution) has NOT landed yet; calling `.execute()` today
- * hits a 404, not a working query. This ships ahead of the route deliberately (same pattern as the
- * BYOS SDK surfaces) so the wire shape is locked to the spec, not re-derived once the route exists.
+ * Client-side surface for `POST /@:projectSlug/metadata/query`. The wire shape is fixed here ahead of the
+ * server route: until the gateway ships that route, calling `.execute()` returns a 404 rather than a result.
+ * Once it is available, only `telemetry:*` surfaces return data at first; collection and storage metadata
+ * follow as their server-side schemas land.
  *
- * The telemetry slice is buildable on Inc 2
- * (reuses the existing audit-log query); the collection + storage slices are blocked on greenfield
- * `record.metadata`/object-metadata schema (Inc 3/Inc 4) — so even once Inc 2 lands, only
- * `telemetry:*` surfaces will actually return data until those land.
- *
- * `textSearch`/`vectorSearch` (ch14 §3.4) are explicitly a later increment (Inc 5) — not implemented
+ * `textSearch`/`vectorSearch` are explicitly a later increment (Inc 5) — not implemented
  * here; adding stub methods for an unspecified future mode would be speculative, not spec-grounded.
  */
 
-/** The three cross-surface slices (ch14 §2.1). */
+/** The three cross-surface slices. */
 type MetadataSlice = "collection" | "storage" | "telemetry";
-/** ch14 §3.3 operator vocabulary (= ch06 §3.5 JSON-policy set), mirrored verbatim from the gateway's
+/** operator vocabulary (= JSON-policy set), mirrored verbatim from the gateway's
  *  `metadata-query-parse.ts` so a typo can't silently pass client-side and fail only server-side. */
 declare const METADATA_OPERATORS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "contains", "startsWith", "endsWith", "in", "notIn", "and", "or", "not"];
 type MetadataOperator = (typeof METADATA_OPERATORS)[number];
-/** A surface label `<slice>:<scope>` (ch14 §2.2), e.g. `collection:posts`, `storage:images`,
+/** A surface label `<slice>:<scope>`, e.g. `collection:posts`, `storage:images`,
  *  `telemetry:auth.session.created`. */
 type MetadataSurface = `${MetadataSlice}:${string}`;
 type MetadataWhereClause = {
@@ -463,7 +456,7 @@ type MetadataWhereClause = {
     readonly value: unknown;
 };
 /**
- * One result row (ch14 §3.1): "each record carries its surface + scope + the queried metadata
+ * One result row: "each record carries its surface + scope + the queried metadata
  * fields plus a back-reference id" — `recordId` (collection), `objectPath` (storage), or `eventId`
  * (telemetry), depending on which surface the row came from. Exact field names are provisional
  * pending Inc 2 landing a concrete response schema; kept loose (`metadata: Record<string, unknown>`)
@@ -481,7 +474,7 @@ type MetadataQueryResult = {
     records: readonly MetadataQueryRecord[];
     nextCursor: string | null;
 };
-/** The `k9o.metadata.from(...).where(...).limit(...).execute()` builder (ch14 §3.1). Immutable —
+/** The `k9o.metadata.from(...).where(...).limit(...).execute()` builder. Immutable —
  *  every chained call returns a new builder, so a partially-built query can be safely reused/branched. */
 type MetadataQueryBuilder = {
     where(field: string, op: MetadataOperator, value: unknown): MetadataQueryBuilder;
@@ -490,7 +483,7 @@ type MetadataQueryBuilder = {
     execute(): Promise<Envelope<MetadataQueryResult>>;
 };
 declare function makeMetadataNamespace(config: HttpClientConfig): {
-    /** Start a cross-surface metadata query against one or more surfaces (ch14 §3.1). */
+    /** Start a cross-surface metadata query against one or more surfaces. */
     from(surface: MetadataSurface | readonly MetadataSurface[]): MetadataQueryBuilder;
 };
 
@@ -512,8 +505,8 @@ declare function makeMetadataNamespace(config: HttpClientConfig): {
  *
  * Migration shape — STRUCTURED
  * DECLARATIVE DDL, never raw SQL. Every schema change is a typed, key-tagged
- * operation, so schema drift is impossible at the SDK layer (the §2.1
- * invariant). Raw SQL is the separate runtime `client.query()` surface (§6),
+ * operation, so schema drift is impossible at the SDK layer (the
+ * invariant). Raw SQL is the separate runtime `client.query()` surface,
  * which cannot create/alter schema. The gateway checksums each migration and
  * stores it in `_sys.migrations`; already-applied versions are skipped on
  * re-run and mismatched checksums are rejected, preserving the drift invariant.
@@ -539,9 +532,9 @@ type ColumnReferences = {
     on_update?: "CASCADE" | "RESTRICT" | "SET NULL" | "NO ACTION";
 };
 /**
- * A column definition. `type` is the ch04 §2.2.1 column-type vocabulary
+ * A column definition. `type` is the column-type vocabulary
  * (parser-owned; kept as `string` rather than a fabricated enum). The
- * protection attributes declare at-rest field encryption per §2.2.1 (gateway
+ * protection attributes declare at-rest field encryption (gateway
  * shape verified vs the parser, live since `2.56.0`).
  */
 type ColumnSpec = {
@@ -553,7 +546,7 @@ type ColumnSpec = {
     default?: string;
     references?: ColumnReferences;
     /**
-     * At-rest field encryption (§2.2.1). `true` = inline-stored encrypted column;
+     * At-rest field encryption. `true` = inline-stored encrypted column;
      * the object form opts into a `store` ("inline" | "vault") and the D-mode
      * searchable-encryption index (`searchable`). NOTE: `searchable` is NESTED
      * here — it is NOT a sibling attribute.
@@ -578,7 +571,7 @@ type IndexSpec = {
  * mutation (one op carries optional `add_columns[]` + `drop_columns[]`), live in
  * the gateway runner (`migration-runner.ts:156`).
  * `rename_column` remains a pending future op (its parser field names are not yet
- * finalised); NOTE per ch04 §2.2.1/§2.2.3 a `rename_column` on an ENCRYPTED column
+ * finalised); NOTE / a `rename_column` on an ENCRYPTED column
  * is fail-closed-rejected (`K9O_ENCRYPTED_COLUMN_DECLARATION_INVALID`) pending the
  * re-encryption pass — to document when that op lands.
  */
@@ -617,18 +610,18 @@ type Operation = {
     };
 };
 /** A declarative authorization/relationship rule (compiles to RLS USING + WITH
- *  CHECK per ch06 §4.2). The rule grammar is the policy-expression DSL. */
+ *  CHECK). The rule grammar is the policy-expression DSL. */
 type ActionRule = {
     rule?: unknown;
 };
-/** A declared relationship for embedding/joins (ch04 §2.2 references). */
+/** A declared relationship for embedding/joins (references). */
 type RelationshipSpec = {
     collection: string;
     on: string;
     as: string;
     type?: "inner" | "left";
 };
-/** Per-collection policy block (RLS + relationships), ch06 §4. */
+/** Per-collection policy block (RLS + relationships),. */
 type CollectionPolicy = {
     references?: ReadonlyArray<RelationshipSpec>;
     actions?: {
@@ -638,7 +631,7 @@ type CollectionPolicy = {
         delete?: ActionRule;
     };
 };
-/** Per-bucket storage policy block, ch06 §5. */
+/** Per-bucket storage policy block,. */
 type StorageBucketPolicy = {
     public?: boolean;
     actions?: {
@@ -697,7 +690,7 @@ declare function makeMigrationsNamespace(config: HttpClientConfig): {
     list(): Promise<Envelope<ReadonlyArray<AppliedMigration>>>;
     /** Get a single applied migration by version. */
     get(version: number): Promise<Envelope<AppliedMigration>>;
-    /** Queue migrations for maker-checker approval per ch06 §8. */
+    /** Queue migrations for maker-checker approval. */
     queue(input: {
         migrations: ReadonlyArray<Migration>;
     }): Promise<Envelope<{
@@ -706,7 +699,7 @@ declare function makeMigrationsNamespace(config: HttpClientConfig): {
     /** List pending (queued, not yet approved) migrations. */
     listPending(): Promise<Envelope<ReadonlyArray<PendingMigration>>>;
     /**
-     * Apply a queued migration by id (§2.6 same-actor fast path — floors at
+     * Apply a queued migration by id (same-actor fast path — floors at
      * PROJECT_ADMIN; a `pending_approval` row, i.e. a protected-collection
      * migration awaiting a distinct-admin's review, is refused here and
      * needs its own approval flow, not this call).
@@ -736,8 +729,8 @@ declare function makeMigrationsNamespace(config: HttpClientConfig): {
  *   - `delete(name)`                          → DELETE /@<slug>/functions/<name>
  *   - `invoke(name, payload)`                 → POST   /@<slug>/functions/<name>/invoke
  *
- * Per ch07 §3.3: deploy requires PROJECT_ADMIN; invoke authority is per
- * function manifest. Per ch07 §3.1: deploy returns 202 with status
+ * Per: deploy requires PROJECT_ADMIN; invoke authority is per
+ * function manifest. Per: deploy returns 202 with status
  * `deploying`; the function is ready when status flips to `active`.
  */
 
@@ -745,7 +738,7 @@ declare function makeMigrationsNamespace(config: HttpClientConfig): {
  * Function record returned by gateway endpoints.
  */
 type FunctionRecord = {
-    /** `fn_<base62>` per ch01 §3.2. */
+    /** `fn_<base62>`. */
     id: string;
     name: string;
     runtime: "wasm" | "bun" | "node";
@@ -756,7 +749,7 @@ type FunctionRecord = {
 };
 /**
  * Deploy input. The `code` field is the runtime bundle (base64-encoded
- * WASM or JS source) per ch07 §3.4.
+ * WASM or JS source).
  */
 type DeployFunctionInput = {
     name: string;
@@ -768,7 +761,7 @@ type DeployFunctionInput = {
 declare function makeFunctionsNamespace(config: HttpClientConfig): {
     /** Deploy or redeploy a function. Returns the function record with status. */
     deploy(input: DeployFunctionInput): Promise<Envelope<FunctionRecord>>;
-    /** List deployed functions (cursor pagination per ch01 §6.4). */
+    /** List deployed functions (cursor pagination). */
     list(opts?: {
         limit?: number;
         cursor?: string;
@@ -776,7 +769,7 @@ declare function makeFunctionsNamespace(config: HttpClientConfig): {
     }): Promise<Envelope<ReadonlyArray<FunctionRecord>>>;
     /** Get a function by name. */
     get(name: string): Promise<Envelope<FunctionRecord>>;
-    /** Retire a function. Returns confirmation; the function name enters a 24h cooldown per ch07 §3.1. */
+    /** Retire a function. Returns confirmation; the function name enters a 24h cooldown. */
     delete(name: string): Promise<Envelope<{
         retired: boolean;
         cooldownUntil: string;
@@ -786,8 +779,8 @@ declare function makeFunctionsNamespace(config: HttpClientConfig): {
      * verbatim; the gateway returns whatever the function returns wrapped
      * in the standard envelope.
      *
-     * Per ch07 §3.3: invoke authority is per-function (declared in the
-     * function manifest). Per ch07 §5: streaming responses use the
+     * Per: invoke authority is per-function (declared in the
+     * function manifest). Per: streaming responses use the
      * subscription/async-iterator pattern; this method covers the
      * request-response variant only.
      */
@@ -809,13 +802,13 @@ declare function makeFunctionsNamespace(config: HttpClientConfig): {
  *   - `delete(bundleId)`                  → DELETE /@<slug>/policies/<id>
  *   - `publish(bundleId)`                 → POST   /@<slug>/policies/<id>/publish
  *
- * Per ch06 §9.4: only Pathmaker-class roles author policy; only
+ * Per: only Pathmaker-class roles author policy; only
  * Custodian-class roles publish. `validate` is read-only and any role
  * with policy-read can lint a candidate bundle.
  */
 
 type PolicyBundle = {
-    /** `pol_<base62>` per ch01 §3.2. */
+    /** `pol_<base62>`. */
     id: string;
     name: string;
     version: number;
@@ -882,19 +875,19 @@ declare function makePoliciesNamespace(config: HttpClientConfig): {
  *
  * The endpoint accepts cursor-paginated reverse-chronological queries.
  * `type` is the audit-event namespace (e.g. `data.write.access.insert`,
- * `gate.signin.success`) per the ch05 §4 event-name taxonomy +
+ * `gate.signin.success`) per the event-name taxonomy +
  * `feedback_error_code_namespace_boundary_and_prefix.md` cement.
  *
  * Returns audit events with full context payload — actorId / targetKind /
- * targetId / payload / occurredAt / requestId / traceId per ch05 §4.2.
+ * targetId / payload / occurredAt / requestId / traceId.
  */
 
 /**
- * Audit event record per ch05 §4.2 `_sys.audit_log` shape.
+ * Audit event record `_sys.audit_log` shape.
  */
 type AuditEvent = {
     id: string;
-    /** Dotted namespace per ch05 §4 (e.g. `data.write.access.insert`). */
+    /** Dotted namespace (e.g. `data.write.access.insert`). */
     type: string;
     actorId: string | null;
     targetKind: string | null;
@@ -927,7 +920,7 @@ declare function makeAuditNamespace(config: HttpClientConfig): {
      * Query the audit log. Returns reverse-chronological events matching
      * all supplied filters (AND composition).
      *
-     * Per ch05 §4 RBAC: requires `AUDIT_READER` role minimum; Custodian-
+     * Per RBAC: requires `AUDIT_READER` role minimum; Custodian-
      * class roles inherit. Project-level audit is project-scoped (this
      * endpoint); platform-level audit is admin-only (separate surface).
      */
@@ -935,7 +928,7 @@ declare function makeAuditNamespace(config: HttpClientConfig): {
     /**
      * Convenience: live-tail recent events. Currently single-shot read
      * with `since` defaulted to "1 minute ago"; subscription-mode tail
-     * (SSE) lands when the streaming layer ships per ch04 §8 pattern.
+     * (SSE) lands when the streaming layer ships pattern.
      */
     tail(opts?: {
         sinceMinutes?: number;
@@ -961,14 +954,14 @@ declare function makeAuditNamespace(config: HttpClientConfig): {
  * `restore` is the one exception — it stays keyed by `orgId`, because a
  * soft-deleted org's slug is tombstoned and may have been reassigned.
  *
- * Per ch02 RBAC: org listing is scoped by the caller's accessible orgs
- * (most callers see exactly one — their own). Org creation is currently
- * out of scope at v0.1.0 (signup flow per ch10 §1; future sub-cycle
- * wires `client.orgs.create()` once signup substrate stabilises).
+ *: org listing is scoped by the caller's accessible orgs
+ * (most callers see exactly one — their own). Org creation is not available
+ * through the SDK yet; `client.orgs.create()` will be added once sign-up
+ * is exposed as an API).
  */
 
 type Org = {
-    /** `org_<base62>` per ch01 §3.2. */
+    /** `org_<base62>`. */
     id: string;
     slug: string;
     name: string;
@@ -991,39 +984,39 @@ declare function makeOrgsNamespace(config: HttpClientConfig): {
  * Compute LLMs SDK — `client.compute.llms.*`.
  *
  * Compute LLMs registry. Curated 9-model library
- * (§10.1) + 4-endpoint family (§10.2) + per-model tier-gating.
+ * + 4-endpoint family + per-model tier-gating.
  *
- * Wire mapping (project-plane; ch07 §10.2):
+ * Wire mapping (project-plane;):
  *   - list()                    → GET  /@<slug>/compute/llms
  *   - read(modelId)             → GET  /@<slug>/compute/llms/<model-id>
  *   - invoke(modelId, ...)      → POST /@<slug>/compute/llms/<model-id>/invoke
  *   - invokeStream(modelId,...) → POST /@<slug>/compute/llms/<model-id>/invoke-stream (SSE)
  *
- * Per ch07 §10.5 RBAC: list/read against all cohort roles; invoke +
+ * Per RBAC: list/read against all cohort roles; invoke +
  * invokeStream require PROJECT_AUTHOR or PROJECT_ADMIN (LLM cost gate).
- * Per ch07 §10.6, surfaces K9O_LLM_PROVIDER_UNAVAILABLE (503) +
+ * Per, surfaces K9O_LLM_PROVIDER_UNAVAILABLE (503) +
  * reuses K9O_MODEL_NOT_DECLARED / K9O_TIER_FEATURE_GATED /
  * K9O_AGENT_INFERENCE_TIMEOUT.
  */
 
-/** Curated 9-model closed enum at v2 launch per ch07 §10.1 (extensible v2.x). */
+/** Curated 9-model closed enum at v2 launch (extensible v2.x). */
 type LLMModelId = "mistral-7b" | "mistral-8x7b" | "llama-3-8b" | "llama-3-70b" | "claude-3-5-sonnet" | "gpt-4o" | "gpt-4o-mini" | "text-embedding-3-small" | "text-embedding-3-large";
 type LLMProviderClass = "self-hosted" | "external";
 type LLMModality = "text-completion" | "text-completion+tool-use" | "embeddings";
-/** Model metadata per ch07 §10.1 + §10.4 (cost transparency). */
+/** Model metadata + (cost transparency). */
 type LLMModel = {
     id: LLMModelId;
     providerClass: LLMProviderClass;
     modality: LLMModality;
-    /** Minimum tier gate per ch10 (e.g. "base-camp", "ascent", "ridge"). */
+    /** Minimum tier gate (e.g. "base-camp", "ascent", "ridge"). */
     tierGate: string;
     contextWindow: number;
     capabilities: ReadonlyArray<string>;
-    /** Per-model token cost for cost-transparency per §10.4. */
+    /** Per-model token cost for cost-transparency. */
     costPerMillionInputTokens: number;
     costPerMillionOutputTokens: number;
 };
-/** Inference parameters per ch07 §10.2 (passed through to provider). */
+/** Inference parameters (passed through to provider). */
 type LLMInvokeParams = {
     maxTokens?: number;
     temperature?: number;
@@ -1031,13 +1024,13 @@ type LLMInvokeParams = {
     stop?: ReadonlyArray<string>;
     [key: string]: unknown;
 };
-/** Synchronous inference response per ch07 §10.2 `/invoke`. */
+/** Synchronous inference response `/invoke`. */
 type LLMResponse = {
     completion: string;
     tokensUsed: number;
     latencyMs: number;
 };
-/** Streaming chunk per ch07 §10.2 `/invoke-stream` (SSE per-token). */
+/** Streaming chunk `/invoke-stream` (SSE per-token). */
 type LLMStreamChunk = {
     /** Incremental completion delta. */
     delta: string;
@@ -1050,14 +1043,14 @@ type LLMInvokeInput = {
     prompt: string;
     params?: LLMInvokeParams;
 };
-/** Error code coined in ch07 §10.6 (others reused per §10.6). */
+/** Error code coined in (others reused). */
 declare const LLM_ERROR_CODES: {
     readonly PROVIDER_UNAVAILABLE: "K9O_LLM_PROVIDER_UNAVAILABLE";
 };
 declare function makeComputeNamespace(config: HttpClientConfig): {
-    /** LLM registry + inference — `client.compute.llms.*` (ch07 §10). */
+    /** LLM registry + inference — `client.compute.llms.*`. */
     llms: {
-        /** GET /@<slug>/compute/llms — list models available to the project tier per ch10. */
+        /** GET /@<slug>/compute/llms — list models available to the project tier. */
         list(opts?: {
             modality?: LLMModality;
             providerClass?: LLMProviderClass;
@@ -1066,12 +1059,12 @@ declare function makeComputeNamespace(config: HttpClientConfig): {
         read(modelId: LLMModelId | string): Promise<Envelope<LLMModel>>;
         /**
          * POST /@<slug>/compute/llms/<model-id>/invoke — synchronous inference.
-         * Requires PROJECT_AUTHOR or PROJECT_ADMIN (LLM cost gate per §10.5).
+         * Requires PROJECT_AUTHOR or PROJECT_ADMIN (LLM cost gate).
          */
         invoke(modelId: LLMModelId | string, input: LLMInvokeInput): Promise<Envelope<LLMResponse>>;
         /**
          * POST /@<slug>/compute/llms/<model-id>/invoke-stream — streaming
-         * inference (SSE; per-token delta for low-latency UX per §10.2).
+         * inference (SSE; per-token delta for low-latency UX).
          * Returns an async iterable of `LLMStreamChunk` — caller writes
          * `for await (const chunk of client.compute.llms.invokeStream(...))`.
          * The SDK handles SSE framing internally per
@@ -1090,30 +1083,30 @@ declare function makeComputeNamespace(config: HttpClientConfig): {
  * across accessible orgs) — `client.org` is the singular bound-org
  * namespace with member / group / smtp / audit / gate sub-namespaces.
  *
- * Org-plane URL grammar per v2.5.68 §5.4: requests route against the
+ * Org-plane URL grammar: requests route against the
  * `<orgSlug>.api.k9o.io/` org subdomain WITHOUT the `@<projectSlug>/`
  * prefix used by project-plane requests. The gateway resolves the org
  * context from the subdomain.
  */
 
 type OrgMember = {
-    /** `u_<base62>` per ch01 §3.2. */
+    /** `u_<base62>`. */
     userId: string;
     email: string;
-    /** Org-level role enum per ch05 §2.1. */
+    /** Org-level role enum. */
     role: "ORG_OWNER" | "ORG_ADMIN" | "ORG_BILLING_ADMIN" | "ORG_MEMBER";
     joinedAt: string;
     status: "active" | "invited" | "suspended";
 };
 type OrgGroup = {
-    /** `grp_<base62>` per ch01 §3.2. */
+    /** `grp_<base62>`. */
     id: string;
     name: string;
     memberCount: number;
     createdAt: string;
 };
 type OrgRoleGrant = {
-    /** `grt_<base62>` per ch02 §6.5. */
+    /** `grt_<base62>`. */
     id: string;
     userId: string;
     role: "ORG_ADMIN" | "ORG_BILLING_ADMIN";
@@ -1124,7 +1117,7 @@ type OrgRoleGrant = {
     viaDelegationId: string | null;
 };
 /**
- * Org-level audit event per ch05 §4.2 6-event family.
+ * Org-level audit event 6-event family.
  *
  * Event types (closed set at v2.1.132):
  *   - `data.write.org.member_invited`
@@ -1134,7 +1127,7 @@ type OrgRoleGrant = {
  *   - `data.write.org.idp_config_changed`
  *   - `data.write.org.settings_updated`
  *
- * `targetKind` is `org` for all; `targetId` is the orgId per ch05 §4.1.
+ * `targetKind` is `org` for all; `targetId` is the orgId.
  */
 type OrgAuditEvent = {
     id: string;
@@ -1148,7 +1141,7 @@ type OrgAuditEvent = {
     traceId: string | null;
 };
 /**
- * Org SMTP configuration per ch02 §6.6. Sensitive fields (passwordRef)
+ * Org SMTP configuration. Sensitive fields (passwordRef)
  * are sequestered in Kibo enclave; the SDK stores only the reference.
  */
 type SmtpConfig = {
@@ -1175,7 +1168,7 @@ type SmtpTestEmailResult = {
     attemptedAt: string;
 };
 type OrgIdpProvider = {
-    /** `idp_<base62>` per ch01 §3.2. */
+    /** `idp_<base62>`. */
     id: string;
     name: string;
     /** Protocol/vendor (e.g. "okta-saml", "azure-ad-oidc", "google-workspace"). */
@@ -1233,7 +1226,7 @@ declare function makeOrgNamespace(config: HttpClientConfig): {
          * GET /audit-log (org-plane).
          * Distinct from project-plane `client.audit.query()` which routes to
          * `@<projectSlug>/audit-log`. Org-plane events cover the 6-event family
-         * per ch05 §4.2 (member_invited/removed/role_granted/revoked/
+         * (member_invited/removed/role_granted/revoked/
          * idp_config_changed/settings_updated).
          */
         query(opts?: {
@@ -1255,7 +1248,7 @@ declare function makeOrgNamespace(config: HttpClientConfig): {
     /** Gate (IAK) org-level surfaces — role-grants + IdP-providers. */
     gate: {
         roles: {
-            /** GET /org-role-grants — list active grants per ch02 §6.5 ask 4. */
+            /** GET /org-role-grants — list active grants ask 4. */
             list(opts?: {
                 userId?: string | undefined;
                 role?: OrgRoleGrant["role"] | undefined;
@@ -1272,7 +1265,7 @@ declare function makeOrgNamespace(config: HttpClientConfig): {
             revoke(grantId: string): Promise<Envelope<OrgRoleGrant>>;
         };
         idpProviders: {
-            /** GET /idp-providers — list configured org operator IdP providers per ch02 §6.5 ask 7. */
+            /** GET /idp-providers — list configured org operator IdP providers ask 7. */
             list(): Promise<Envelope<ReadonlyArray<OrgIdpProvider>>>;
             /** POST /idp-providers — create a new IdP integration. */
             create(input: CreateOrgIdpInput): Promise<Envelope<OrgIdpProvider>>;
@@ -1295,7 +1288,7 @@ declare function makeOrgNamespace(config: HttpClientConfig): {
         /**
          * GET /org/smtp — read current SMTP config.
          * Returns null when no org-level SMTP is configured (falls back to
-         * platform SMTP per ch02 §6.6 3-tier cascade).
+         * platform SMTP 3-tier cascade).
          */
         get(): Promise<Envelope<SmtpConfig | null>>;
         /**
@@ -1318,18 +1311,18 @@ declare function makeOrgNamespace(config: HttpClientConfig): {
             cleared: boolean;
         }>>;
     };
-    /** Org-default LLM — get / set per ch07 §10.3 (ORG_ADMIN). */
+    /** Org-default LLM — get / set (ORG_ADMIN). */
     defaultLLM: {
         /**
-         * GET /org/default-llm — read the org-default LLM model id per ch07
-         * §10.3. Returns `null` when no explicit default is set (gateway
-         * falls back to `mistral-7b` per §10.3). ORG_ADMIN read; tier-gated.
+         * GET /org/default-llm — read the org-default LLM model id
+         *. Returns `null` when no explicit default is set (gateway
+         * falls back to `mistral-7b`). ORG_ADMIN read; tier-gated.
          */
         get(): Promise<Envelope<LLMModelId | null>>;
         /**
-         * PATCH /org/default-llm — set the org-default LLM per ch07 §10.3.
+         * PATCH /org/default-llm — set the org-default LLM.
          * ORG_ADMIN only. The model must be available to the org's tier per
-         * §10.1 or the gateway returns K9O_TIER_FEATURE_GATED.
+         * or the gateway returns K9O_TIER_FEATURE_GATED.
          */
         set(input: {
             modelId: LLMModelId;
@@ -1359,17 +1352,17 @@ declare function makeOrgNamespace(config: HttpClientConfig): {
  * Wire mapping (gateway uses platform-plane / cross-org `/me/...` routes):
  *   - `client.me.profile.get/update` → GET/PATCH /me
  *   - `client.me.sessions.list/revoke` → GET/DELETE /me/sessions
- *   - `client.me.apiTokens.list/create/delete` → GET/POST/DELETE /me/api-tokens (forward sub-cycle)
- *   - `client.me.notifications.list/markRead` → GET/PATCH /me/notifications (forward sub-cycle)
- *   - `client.me.auditLog.query` → GET /me/audit-log (forward sub-cycle)
- *   - `client.me.dataExport.request` → POST /me/data-export (forward sub-cycle)
+ *   - `client.me.apiTokens.list/create/delete` → GET/POST/DELETE /me/api-tokens (not available yet)
+ *   - `client.me.notifications.list/markRead` → GET/PATCH /me/notifications (not available yet)
+ *   - `client.me.auditLog.query` → GET /me/audit-log (not available yet)
+ *   - `client.me.dataExport.request` → POST /me/data-export (not available yet)
  *
  * Profile, sessions and MFA setup are served by the existing gateway routes
  * `me.ts` + `mfa.ts`.
  */
 
 type MyProfile = {
-    /** `u_<base62>` per ch01 §3.2. */
+    /** `u_<base62>`. */
     id: string;
     email: string;
     displayName: string | null;
@@ -1431,9 +1424,8 @@ declare function makeMeNamespace(config: HttpClientConfig): {
         }>>;
     };
     /**
-     * API tokens for personal scripting (forward-cycle surface per ch12
-     * §3.1 implicit; substrate not yet shipped per gateway routes audit).
-     * Methods will return K9O_NOT_FOUND until gateway lands the endpoints.
+     * API tokens for personal scripting. The gateway endpoints are not available yet,
+     * so these methods return K9O_NOT_FOUND until they ship.
      */
     apiTokens: {
         list(): Promise<Envelope<ReadonlyArray<MyApiToken>>>;
@@ -1505,9 +1497,9 @@ declare function makeMeNamespace(config: HttpClientConfig): {
  * Studio Dashboards SDK — `client.studio.dashboards.*`.
  *
  * Dashboards persisted authoring substrate.
- * Mirrors `_sys.dashboards` (§3.10.1) row shape.
+ * Mirrors `_sys.dashboards` row shape.
  *
- * Wire mapping (project-plane; ch04 §3.10.4):
+ * Wire mapping (project-plane;):
  *   - list()                  → GET    /@<slug>/dashboards
  *   - create(dashboard)       → POST   /@<slug>/dashboards
  *   - read(id)                → GET    /@<slug>/dashboards/<dsh-id>
@@ -1516,17 +1508,17 @@ declare function makeMeNamespace(config: HttpClientConfig): {
  *   - pin(id)                 → POST   /@<slug>/dashboards/<dsh-id>/pin
  *   - unpin(id)               → POST   /@<slug>/dashboards/<dsh-id>/unpin
  *
- * Per ch04 §3.10.4 RBAC: create/update/delete/pin/unpin require
+ * Per RBAC: create/update/delete/pin/unpin require
  * PROJECT_AUTHOR; list/read read against all cohort roles subject
- * to RLS. Per ch04 §3.10.7, surfaces 2 K9O_DASHBOARD_* codes.
+ * to RLS. Per, surfaces 2 K9O_DASHBOARD_* codes.
  */
 
-/** 9-widget catalogue per ch04 §3.10.2. */
+/** 9-widget catalogue. */
 type WidgetType = "kpi_card" | "bar_chart" | "line_chart" | "pie_chart" | "data_table" | "filter_dropdown" | "filter_date_range" | "text_panel" | "workflow_status";
 /** Widget data source modes. */
 type WidgetDataSourceMode = "view" | "query" | "workflow" | "rollup" | "form";
 type DashboardStatus = "active" | "archived" | "draft";
-/** A widget config entry in the `widgets` array per ch04 §3.10.2. */
+/** A widget config entry in the `widgets` array. */
 type Widget = {
     id: string;
     widgetType: WidgetType;
@@ -1539,20 +1531,20 @@ type Widget = {
     /** Widget-local config (display options, thresholds, etc.). */
     config?: Record<string, unknown>;
 };
-/** Dashboard record per ch04 §3.10.1 `_sys.dashboards` row. */
+/** Dashboard record `_sys.dashboards` row. */
 type Dashboard = {
-    /** `dsh_<base62>` per ch01 §3.2. */
+    /** `dsh_<base62>`. */
     id: string;
     projectId: string;
     name: string;
     description: string;
     status: DashboardStatus;
-    /** Widget positions + sizes per output-03 §3 layout schema. */
+    /** Widget positions + sizes per output-03 layout schema. */
     layoutGrid: Record<string, unknown>;
     widgets: ReadonlyArray<Widget>;
     /** Dashboard-level filter widgets cascade to per-widget data sources. */
     filterConfig: Record<string, unknown>;
-    /** Pathmaker org-pin per output-03 §9; surfaces in Workspace sidebar. */
+    /** Pathmaker org-pin per output-03; surfaces in Workspace sidebar. */
     pinnedToWorkspace: boolean;
     rbacBinding: Record<string, unknown>;
     authoredBy: string;
@@ -1576,7 +1568,7 @@ type DashboardListFilters = {
     status?: DashboardStatus;
     pinnedToWorkspace?: boolean;
 };
-/** 2 K9O_DASHBOARD_* error codes per ch04 §3.10.7. */
+/** 2 K9O_DASHBOARD_* error codes. */
 declare const DASHBOARD_ERROR_CODES: {
     readonly NOT_FOUND: "K9O_DASHBOARD_NOT_FOUND";
     readonly WIDGET_INVALID: "K9O_DASHBOARD_WIDGET_INVALID";
@@ -1586,9 +1578,9 @@ declare const DASHBOARD_ERROR_CODES: {
  * Studio Workflows SDK — `client.studio.workflows.*`.
  *
  * Workflows substrate. Mirrors
- * `_sys.workflows` (§9.1) + `_sys.workflow_runs` (§9.2) row shapes.
+ * `_sys.workflows` + `_sys.workflow_runs` row shapes.
  *
- * Wire mapping (project-plane; ch07 §9.6):
+ * Wire mapping (project-plane;):
  *   - list()                       → GET    /@<slug>/workflows
  *   - create(workflow)             → POST   /@<slug>/workflows
  *   - read(id)                     → GET    /@<slug>/workflows/<wfl-id>
@@ -1599,19 +1591,19 @@ declare const DASHBOARD_ERROR_CODES: {
  *   - runs.read(id, runId)         → GET    /@<slug>/workflows/<wfl-id>/runs/<wfr-id>
  *   - runs.cancel(id, runId)       → POST   /@<slug>/workflows/<wfl-id>/runs/<wfr-id>/cancel
  *
- * Per ch07 §9.6 RBAC: create/update/delete/trigger/cancel require
+ * Per RBAC: create/update/delete/trigger/cancel require
  * PROJECT_AUTHOR; list/read/runs read against all cohort roles subject
- * to RLS. Per ch07 §9.11, surfaces 6 K9O_WORKFLOW_* error codes (see
+ * to RLS. Per, surfaces 6 K9O_WORKFLOW_* error codes (see
  * `WORKFLOW_ERROR_CODES`); callers narrow on `error.code`.
  */
 
-/** 5-trigger catalogue per ch07 §9.3. */
+/** 5-trigger catalogue. */
 type WorkflowTriggerType = "view_row_event" | "form_submission" | "scheduled" | "manual" | "webhook";
-/** 9-action catalogue per ch07 §9.4. */
+/** 9-action catalogue. */
 type WorkflowActionType = "write_collection" | "read_collection" | "invoke_function" | "invoke_extension" | "llm_inference" | "send_notification" | "http_request" | "approval_step" | "branch";
 type WorkflowStatus = "active" | "archived" | "draft";
 type WorkflowRunStatus = "pending" | "running" | "succeeded" | "failed" | "cancelled";
-/** A single step in the `actions` chain per ch07 §9.4. */
+/** A single step in the `actions` chain. */
 type WorkflowAction = {
     index: number;
     action_type: WorkflowActionType;
@@ -1621,30 +1613,30 @@ type WorkflowAction = {
         backoffStrategy?: string;
     };
     condition?: Record<string, unknown>;
-    /** Sibling steps with parallel:true execute concurrently per §9.4. */
+    /** Sibling steps with parallel:true execute concurrently. */
     parallel?: boolean;
 };
-/** Workflow record per ch07 §9.1 `_sys.workflows` row. */
+/** Workflow record `_sys.workflows` row. */
 type Workflow = {
-    /** `wfl_<base62>` per ch01 §3.2. */
+    /** `wfl_<base62>`. */
     id: string;
     projectId: string;
     name: string;
     description: string;
     status: WorkflowStatus;
     triggerType: WorkflowTriggerType;
-    /** Shape varies per triggerType per §9.3. */
+    /** Shape varies per triggerType. */
     triggerConfig: Record<string, unknown>;
-    /** Chain definition per §9.4. */
+    /** Chain definition. */
     actions: ReadonlyArray<WorkflowAction>;
-    /** Approver-step participant resolution per §9.5. */
+    /** Approver-step participant resolution. */
     rbacBinding: Record<string, unknown>;
     authoredBy: string;
     authoredAt: string;
     updatedBy: string;
     updatedAt: string;
 };
-/** Per-step status entry in a run per ch07 §9.2 `per_step_status`. */
+/** Per-step status entry in a run `per_step_status`. */
 type WorkflowRunStep = {
     stepIndex: number;
     actionType: WorkflowActionType;
@@ -1655,9 +1647,9 @@ type WorkflowRunStep = {
     outputSummary?: unknown;
     costSubtotal?: number;
 };
-/** Workflow run record per ch07 §9.2 `_sys.workflow_runs` row. */
+/** Workflow run record `_sys.workflow_runs` row. */
 type WorkflowRun = {
-    /** `wfr_<base62>` per ch01 §3.2. */
+    /** `wfr_<base62>`. */
     id: string;
     workflowId: string;
     projectId: string;
@@ -1670,7 +1662,7 @@ type WorkflowRun = {
     completedAt: string | null;
     firedBy: string;
 };
-/** Create input — omits server-assigned fields per §9.1. */
+/** Create input — omits server-assigned fields. */
 type CreateWorkflowInput = {
     name: string;
     description?: string;
@@ -1693,7 +1685,7 @@ type WorkflowRunListFilters = {
     status?: WorkflowRunStatus;
 };
 /**
- * 6 K9O_WORKFLOW_* error codes per ch07 §9.11. KError code-space is
+ * 6 K9O_WORKFLOW_* error codes. KError code-space is
  * open; these constants document the well-known codes for narrowing
  * (`if (e.code === WORKFLOW_ERROR_CODES.RUN_NOT_CANCELLABLE)`).
  */
@@ -1707,7 +1699,7 @@ declare const WORKFLOW_ERROR_CODES: {
 };
 
 declare function makeStudioNamespace(config: HttpClientConfig): {
-    /** Workflow lifecycle + runs — `client.studio.workflows.*` (ch07 §9). */
+    /** Workflow lifecycle + runs — `client.studio.workflows.*`. */
     workflows: {
         list(filters?: WorkflowListFilters): Promise<Envelope<ReadonlyArray<Workflow>>>;
         create(workflow: CreateWorkflowInput): Promise<Envelope<Workflow>>;
@@ -1723,7 +1715,7 @@ declare function makeStudioNamespace(config: HttpClientConfig): {
             cancel(workflowId: string, runId: string): Promise<Envelope<WorkflowRun>>;
         };
     };
-    /** Dashboard lifecycle + widget data — `client.studio.dashboards.*` (ch04 §3.10). */
+    /** Dashboard lifecycle + widget data — `client.studio.dashboards.*`. */
     dashboards: {
         list(filters?: DashboardListFilters): Promise<Envelope<ReadonlyArray<Dashboard>>>;
         create(dashboard: CreateDashboardInput): Promise<Envelope<Dashboard>>;
@@ -1781,22 +1773,22 @@ declare function makeAiNamespace(config: HttpClientConfig): {
  * `for await (const event of client.realtime.subscribe(topic)) { ... }`.
  *
  * Per `feedback_sdk_abstracted_primitive_default_to_richer_interaction.md`
- * + ch07 §11.3: the SDK chooses the transport (WebSocket primary → SSE
+ * +: the SDK chooses the transport (WebSocket primary → SSE
  * → poll), transparently. SPLIT (polling) is the SDK-internal fallback
  * when WebSocket / SSE are unavailable — NOT a consumer-side design
  * choice. The consumer sees one uniform async iterable regardless.
  *
- * Wire mapping (project-plane; ch07 §11.2):
+ * Wire mapping (project-plane;):
  *   - subscribe → GET  /@<slug>/realtime/subscribe?topic=<t>&filter=<jsonb> (WS/SSE upgrade)
  *   - replay    → POST /@<slug>/realtime/replay  { topic, fromSequence, untilSequence?, limit? }
  *
- * Per ch07 §11.4, `filter` + RLS compose (filter narrows, RLS gates).
- * Per ch07 §11.5, surfaces no new codes — reuses K9O_INVALID_FILTER +
+ * Per, `filter` + RLS compose (filter narrows, RLS gates).
+ * Per, surfaces no new codes — reuses K9O_INVALID_FILTER +
  * K9O_SUBSCRIPTION_LIMIT_EXCEEDED + K9O_TIER_FEATURE_GATED.
  */
 
 /**
- * The 6 closed subscription topic families per ch07 §11.1. Concrete
+ * The 6 closed subscription topic families. Concrete
  * topic strings carry a dynamic segment (collection name, resource id,
  * event family) — use `realtimeTopic.*` builders to construct them.
  */
@@ -1804,7 +1796,7 @@ type RealtimeTopicFamily = "collections" | "studio.workflows.runs" | "studio.que
 /** A concrete topic string, e.g. `studio.dashboards.refresh.dsh_abc`. */
 type RealtimeTopic = string;
 /**
- * Typed builders for the 6 topic families per ch07 §11.1. Prefer these
+ * Typed builders for the 6 topic families. Prefer these
  * over hand-built strings for compile-time family safety.
  */
 declare const realtimeTopic: {
@@ -1821,9 +1813,9 @@ declare const realtimeTopic: {
     /** `audit.org.<event-family>` — org-plane audit events. */
     readonly auditOrg: (eventFamily: string) => RealtimeTopic;
 };
-/** Per-topic filter predicate per ch07 §11.4 (ch04 §3.2 vocabulary). */
+/** Per-topic filter predicate (vocabulary). */
 type RealtimeFilter = Record<string, unknown>;
-/** A single realtime event delivered on a subscription per ch07 §11. */
+/** A single realtime event delivered on a subscription. */
 type RealtimeEvent<T = unknown> = {
     topic: RealtimeTopic;
     /** Event type within the topic family (e.g. `row_inserted`, `workflow.run.completed`). */
@@ -1840,7 +1832,7 @@ type SubscribeOptions = {
     /**
      * Force a transport instead of the WebSocket → SSE → poll cascade.
      * Mainly for tests + constrained runtimes. Omit for production —
-     * the SDK picks the richest available transport per §11.3.
+     * the SDK picks the richest available transport.
      */
     transport?: RealtimeTransportKind;
     /** Poll-transport interval in ms (default 2000). Only used when polling. */
@@ -1868,7 +1860,7 @@ declare function makeRealtimeNamespace(config: HttpClientConfig): {
     /**
      * Subscribe to a topic. Returns a `RealtimeSubscription` — an async
      * iterable of `RealtimeEvent`s. The SDK selects the richest available
-     * transport (WebSocket → SSE → poll) per ch07 §11.3; the caller's
+     * transport (WebSocket → SSE → poll); the caller's
      * `for await` loop is transport-agnostic.
      *
      * ```ts
@@ -1882,7 +1874,7 @@ declare function makeRealtimeNamespace(config: HttpClientConfig): {
      */
     subscribe<T = unknown>(topic: RealtimeTopic, options?: SubscribeOptions): RealtimeSubscription<T>;
     /**
-     * One-shot historical replay per ch07 §11.2 — catch up on missed
+     * One-shot historical replay — catch up on missed
      * events from `fromSequence`. Capped at 10k events server-side;
      * paginate via the returned events' `sequence`. Use the highest
      * `sequence` you've seen as the next `fromSequence`.
@@ -1899,21 +1891,19 @@ declare function makeRealtimeNamespace(config: HttpClientConfig): {
  * factory returning typed bindings for Trailblazer/Anchor/Keystone
  * class extensions (baked in at SDK publish time). Circuit-class
  * (Long Tail) extensions use the install-time `k9o codegen` tool
- * (v2.x) per ch13 §8.1.4 path (a) OR raw HTTP / vendor-SDK fallback
- * per path (b).
- *
- * The bridge re-exports the factory directly — it is config-free at
- * v0.3.0 (extension stubs do not require HTTP routing yet; v2.5.68p-
- * stack-sdk-pass2 wires per-method HTTP dispatch). When pass2 lands,
- * the bridge will need to thread baseUrl + auth into the extension
- * runtime; until then the re-export is a thin pass-through.
+ * path (a) OR raw HTTP / vendor-SDK fallback per path (b).
+ *
+ * The bridge re-exports the factory directly — it is config-free
+ * (extension stubs do not require HTTP routing yet). Once per-method dispatch
+ * ships, the bridge will thread baseUrl + auth into the extension runtime;
+ * until then the re-export is a thin pass-through.
  */
 
 /**
  * Build the composed `client.extensions` namespace. Currently a thin
  * re-export of the `@k9o/extensions` `k9o.extension(slug)` factory.
- * Config-free at v0.3.0 — wires to client HTTP config when pass2 lands
- * runtime dispatch.
+ * Config-free for now; it will use the client HTTP config once runtime
+ * dispatch ships.
  */
 declare function makeExtensionsBridge(): {
     /** Resolve a typed extension instance by slug. See `@k9o/extensions` for the factory contract. */
@@ -2042,22 +2032,12 @@ declare function assertProviderRegion(value: unknown, provider?: ProviderRegionP
  * Customer-facing surface. The `createClient(options)`
  * factory returns a `K9oClient` instance with namespaces:
  *
- *   - `client.from(collection)`  — data-plane DSL (ch04 §3 + §6.4)
- *   - `client.projects`          — project lifecycle (ch02)
- *
- * Forward sub-cycles add:
- *   - `client.gate`              — auth composition (re-export from `@k9o/gate`)
- *   - `client.kibo`              — vault ops (re-export from future `@k9o/kibo`)
- *   - `client.extensions`        — extension consumption (re-export from `@k9o/extensions`)
- *   - `client.migrations`        — migration lifecycle (ch04 §2)
- *   - `client.functions`         — function deploy/invoke (ch07)
- *   - `client.policies`          — policy bundle lifecycle (ch06)
- *   - `client.audit`             — audit log queries (ch05 §4)
- *   - `client.orgs`              — org lifecycle (ch02)
- *
- * Architectural posture: 3-pillar default (`@k9o/gate` + `@k9o/extensions` + future `@k9o/kibo`)
- * with `@k9o/core` as the umbrella factory that composes pillars +
- * provides cross-cutting client construction + data-plane surface.
+ *   - `client.from(collection)`  — data-plane DSL
+ *   - `client.projects`          — project lifecycle
+ *   - `client.gate`, `client.extensions`, `client.migrations`, `client.functions`, `client.policies`,
+ *     `client.audit`, `client.orgs` and the other namespaces on the client type
+ *
+ * `@k9o/core` composes `@k9o/gate` and `@k9o/extensions` and adds client construction and the data-plane surface.
  * The SDK shape stays stable whether pillars are imported directly or
  * through `@k9o/core` — only the package boundary moves.
  *
@@ -2070,8 +2050,8 @@ declare function assertProviderRegion(value: unknown, provider?: ProviderRegionP
  * ```typescript
  * import { createClient, KError } from "@k9o/core";
  *
+ * // `orgSlug` selects your organization's host (https://acme.api.k9o.io); do not also pass `baseUrl`.
  * const client = createClient({
- *   baseUrl: "https://acme.api.k9o.io",
  *   apiKey: process.env.K9O_API_KEY,
  *   orgSlug: "acme",
  *   projectSlug: "member-portal",
@@ -2103,7 +2083,7 @@ type K9oClient = {
      *  `client.kibo.vault.secrets` (credential pre-create): this namespace only registers a caller-supplied
      *  `credentialRef` string, never creates or resolves one. */
     storage: ReturnType<typeof makeStorageNamespace>;
-    /** Cross-surface metadata query (ch14) — `client.metadata.from(...).where(...).execute()`. Client-side
+    /** Cross-surface metadata query — `client.metadata.from(...).where(...).execute()`. Client-side
      *  only until the gateway's Inc-2 route lands; see `metadata.ts` for status. */
     metadata: ReturnType<typeof makeMetadataNamespace>;
     /** Migration lifecycle — `client.migrations.apply()` etc. */
@@ -2120,27 +2100,27 @@ type K9oClient = {
     org: ReturnType<typeof makeOrgNamespace>;
     /** Operator-self namespace — `client.me.profile`, `client.me.sessions`, etc. Cross-org; no tenant context required. */
     me: ReturnType<typeof makeMeNamespace>;
-    /** Studio surfaces — `client.studio.workflows.*` (ch07 §9) + `client.studio.dashboards.*` (ch04 §3.10). */
+    /** Studio surfaces — `client.studio.workflows.*` + `client.studio.dashboards.*`. */
     studio: ReturnType<typeof makeStudioNamespace>;
-    /** Compute surfaces — `client.compute.llms.*` (ch07 §10). */
+    /** Compute surfaces — `client.compute.llms.*`. */
     compute: ReturnType<typeof makeComputeNamespace>;
     /** Platform AI primitives — `client.ai.embed({ model?, input })`. */
     ai: ReturnType<typeof makeAiNamespace>;
-    /** Realtime subscriptions — `client.realtime.subscribe()` / `.replay()` (ch07 §11). */
+    /** Realtime subscriptions — `client.realtime.subscribe()` / `.replay()`. */
     realtime: ReturnType<typeof makeRealtimeNamespace>;
     /** Gate (Identity-Aware Kernel) — composed from `@k9o/gate`. Available when projectSlug is bound on the client. */
     readonly gate: GateClient;
-    /** Kibo (Zero-Knowledge vault) — composed from `@k9o/kibo`. `client.kibo.vault.zkDeks.*` (ch08 §11.3.2 F.5); project-scoped methods self-guard the project context. */
+    /** Kibo (Zero-Knowledge vault) — composed from `@k9o/kibo`. `client.kibo.vault.zkDeks.*` (F.5); project-scoped methods self-guard the project context. */
     readonly kibo: KiboClient;
-    /** Extensions consumption — composed from `@k9o/extensions`. `client.extensions.extension(slug)` returns typed extension bindings per ch13 §8.1. */
+    /** Extensions consumption — composed from `@k9o/extensions`. `client.extensions.extension(slug)` returns typed extension bindings. */
     extensions: ReturnType<typeof makeExtensionsBridge>;
     /** Bound config — exposed for advanced use (custom HTTP per-call). */
     readonly config: Readonly<HttpClientConfig>;
 };
 /**
  * Construct a `K9oClient` bound to the supplied gateway baseUrl + auth
- * + project context. Validates the baseUrl at construct time per ch13
- * §7.2 — path-bearing baseUrls throw `K9O_INVALID_BASE_URL` synchronously.
+ * + project context. Validates the baseUrl at construct time
+ * — path-bearing baseUrls throw `K9O_INVALID_BASE_URL` synchronously.
  */
 declare function createClient(options: CreateClientOptions): K9oClient;