@k9o/core 1.0.0 → 1.1.0

package/src/index.ts

@@ -4,22 +4,12 @@
  * 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)
+ *   - `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
  *
- * 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.
+ * `@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.
  *
@@ -32,8 +22,8 @@
  * ```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",
@@ -160,7 +150,7 @@ export type {
   UpdateSecretInput, UpdateSecretResult, RotateSecretResult, MoveSecretResult,
 } from "@k9o/kibo";
 
-// Studio surfaces (ch07 §9 workflows + ch04 §3.10 dashboards)
+// Studio surfaces (workflows + dashboards)
 export {
   WORKFLOW_ERROR_CODES,
   type Workflow,
@@ -188,7 +178,7 @@ export {
   type DashboardListFilters,
 } from "./studio/dashboards.ts";
 
-// Compute LLMs (ch07 §10)
+// Compute LLMs
 export {
   LLM_ERROR_CODES,
   type LLMModelId,
@@ -205,7 +195,7 @@ export type { EmbedInput, EmbedResult, EmbeddingModelId } from "./ai.ts";
 
 export { assertProviderRegion, isProviderRegion, type ProviderRegionProvider } from "./provider-region.ts";
 
-// Realtime subscriptions (ch07 §11)
+// Realtime subscriptions
 export {
   realtimeTopic,
   type RealtimeTopic,
@@ -232,7 +222,7 @@ export 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. */
@@ -249,19 +239,19 @@ export 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>;
@@ -269,8 +259,8 @@ export type K9oClient = {
 
 /**
  * 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.
  */
 export function createClient(options: CreateClientOptions): K9oClient {
   const baseUrl = resolveBaseUrl(options.baseUrl, options.orgSlug);

package/src/internal/sse.ts

@@ -2,8 +2,8 @@
  * Minimal SSE (Server-Sent Events) stream parser — internal.
  *
  * Used by:
- *   - `client.compute.llms.invokeStream()` (ch07 §10.2 `/invoke-stream`)
- *   - `client.realtime.subscribe()` SSE transport fallback (ch07 §11.3)
+ *   - `client.compute.llms.invokeStream()` (`/invoke-stream`)
+ *   - `client.realtime.subscribe()` SSE transport fallback
  *
  * Parses an SSE byte stream (a `ReadableStream<Uint8Array>` from a fetch
  * `Response.body`) into an async iterable of parsed `data:` payloads.

package/src/kerror.ts

@@ -17,7 +17,7 @@
  *                  gateway didn't return one).
  *   - `status`   — HTTP status the gateway returned (or null for
  *                  SDK-side construct-time errors like
- *                  `K9O_INVALID_BASE_URL` per ch13 §7.2).
+ *                  `K9O_INVALID_BASE_URL`).
  *   - `requestId` — gateway-emitted trace ID for downstream correlation.
  *
  * Standalone `@k9o/gate` ships its own `GateError` for the Auth0-parity
@@ -75,7 +75,7 @@ export class KError extends Error {
  * Rehydrate a wire `KError` payload into a typed `KError` instance.
  * Unlike `@k9o/gate.gateErrorFromWire`, `@k9o/core` does not maintain
  * a hand-curated allow-list of known codes — the gateway's KError
- * code-space is open-ended and curated centrally per ch11; the SDK
+ * code-space is open-ended and curated centrally; the SDK
  * preserves whatever code the gateway sends. Code-narrowing in caller
  * code uses string-literal comparison against the well-known codes
  * (e.g. `if (e.code === 'K9O_TIER_CAP_HIT')`).

package/src/me.ts

@@ -8,10 +8,10 @@
  * 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`.
@@ -22,7 +22,7 @@ import { orgPath } from "./url-grammar.ts";
 import type { Envelope } from "./envelope.ts";
 
 export type MyProfile = {
-  /** `u_<base62>` per ch01 §3.2. */
+  /** `u_<base62>`. */
   id: string;
   email: string;
   displayName: string | null;
@@ -98,9 +98,8 @@ export 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: {
       async list(): Promise<Envelope<ReadonlyArray<MyApiToken>>> {

package/src/metadata.ts

@@ -1,19 +1,12 @@
 /**
- * `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.
  */
 
@@ -22,10 +15,10 @@ import { projectPath } from "./url-grammar.ts";
 import { KError } from "./kerror.ts";
 import type { Envelope } from "./envelope.ts";
 
-/** The three cross-surface slices (ch14 §2.1). */
+/** The three cross-surface slices. */
 export 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. */
 export const METADATA_OPERATORS = [
   "eq", "neq", "gt", "gte", "lt", "lte",
@@ -34,7 +27,7 @@ export const METADATA_OPERATORS = [
 ] as const;
 export 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`. */
 export type MetadataSurface = `${MetadataSlice}:${string}`;
 
@@ -45,7 +38,7 @@ export type MetadataWhereClause = {
 };
 
 /**
- * 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>`)
@@ -65,7 +58,7 @@ export type MetadataQueryResult = {
   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. */
 export type MetadataQueryBuilder = {
   where(field: string, op: MetadataOperator, value: unknown): MetadataQueryBuilder;
@@ -78,7 +71,7 @@ function requireProjectSlug(config: HttpClientConfig): string {
   if (config.projectSlug === undefined || config.projectSlug.length === 0) {
     throw new KError({
       code: "K9O_MISSING_PROJECT_CONTEXT",
-      message: "client.metadata requires a bound projectSlug (project data-plane resource, ch14 §4)",
+      message: "client.metadata requires a bound projectSlug (project data-plane resource,)",
       context: {},
       recommendation: "Pass projectSlug when constructing the client.",
     });
@@ -120,7 +113,7 @@ function makeBuilder(
 
 export function makeMetadataNamespace(config: HttpClientConfig) {
   return {
-    /** 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 {
       const surfaces = Array.isArray(surface) ? surface : [surface as MetadataSurface];
       if (surfaces.length === 0) {

package/src/migrations.ts

@@ -16,8 +16,8 @@
  *
  * 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.
@@ -48,9 +48,9 @@ export type ColumnReferences = {
 };
 
 /**
- * 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`).
  */
 export type ColumnSpec = {
@@ -62,7 +62,7 @@ export 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.
@@ -86,7 +86,7 @@ export 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.
  */
@@ -100,10 +100,10 @@ export type Operation =
   | { drop_index: { name: string } };
 
 /** 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. */
 export type ActionRule = { rule?: unknown };
 
-/** A declared relationship for embedding/joins (ch04 §2.2 references). */
+/** A declared relationship for embedding/joins (references). */
 export type RelationshipSpec = {
   collection: string;
   on: string;
@@ -111,7 +111,7 @@ export type RelationshipSpec = {
   type?: "inner" | "left";
 };
 
-/** Per-collection policy block (RLS + relationships), ch06 §4. */
+/** Per-collection policy block (RLS + relationships),. */
 export type CollectionPolicy = {
   references?: ReadonlyArray<RelationshipSpec>;
   actions?: {
@@ -122,7 +122,7 @@ export type CollectionPolicy = {
   };
 };
 
-/** Per-bucket storage policy block, ch06 §5. */
+/** Per-bucket storage policy block,. */
 export type StorageBucketPolicy = {
   public?: boolean;
   actions?: {
@@ -210,7 +210,7 @@ export function makeMigrationsNamespace(config: HttpClientConfig) {
       });
     },
 
-    /** Queue migrations for maker-checker approval per ch06 §8. */
+    /** Queue migrations for maker-checker approval. */
     async queue(input: { migrations: ReadonlyArray<Migration> }): Promise<Envelope<{ pending: ReadonlyArray<PendingMigration> }>> {
       const slug = requireProjectSlug(config);
       return request(config, {
@@ -230,7 +230,7 @@ export function makeMigrationsNamespace(config: HttpClientConfig) {
     },
 
     /**
-     * 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).

package/src/org.ts

@@ -7,7 +7,7 @@
  * 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.
@@ -23,17 +23,17 @@ import type { LLMModelId } from "./compute/llms.ts";
 // ----------------------------------------------------------------------
 
 export 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";
 };
 
 export type OrgGroup = {
-  /** `grp_<base62>` per ch01 §3.2. */
+  /** `grp_<base62>`. */
   id: string;
   name: string;
   memberCount: number;
@@ -41,7 +41,7 @@ export type OrgGroup = {
 };
 
 export type OrgRoleGrant = {
-  /** `grt_<base62>` per ch02 §6.5. */
+  /** `grt_<base62>`. */
   id: string;
   userId: string;
   role: "ORG_ADMIN" | "ORG_BILLING_ADMIN";
@@ -53,7 +53,7 @@ export type OrgRoleGrant = {
 };
 
 /**
- * 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`
@@ -63,7 +63,7 @@ export 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.
  */
 export type OrgAuditEvent = {
   id: string;
@@ -78,7 +78,7 @@ export type OrgAuditEvent = {
 };
 
 /**
- * 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.
  */
 export type SmtpConfig = {
@@ -108,7 +108,7 @@ export type SmtpTestEmailResult = {
 };
 
 export 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"). */
@@ -181,7 +181,7 @@ function makeOrgAuditLogNamespace(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).
      */
     async query(opts?: {
@@ -207,7 +207,7 @@ function makeOrgAuditLogNamespace(config: HttpClientConfig) {
 function makeOrgGateNamespace(config: HttpClientConfig) {
   return {
     roles: {
-      /** GET /org-role-grants — list active grants per ch02 §6.5 ask 4. */
+      /** GET /org-role-grants — list active grants ask 4. */
       async list(opts?: { userId?: string | undefined; role?: OrgRoleGrant["role"] | undefined; includeRevoked?: boolean | undefined }): Promise<Envelope<ReadonlyArray<OrgRoleGrant>>> {
         return request(config, { method: "GET", path: orgPath("org-role-grants"), query: opts });
       },
@@ -229,7 +229,7 @@ function makeOrgGateNamespace(config: HttpClientConfig) {
     },
 
     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. */
       async list(): Promise<Envelope<ReadonlyArray<OrgIdpProvider>>> {
         return request(config, { method: "GET", path: orgPath("idp-providers") });
       },
@@ -262,7 +262,7 @@ function makeSmtpNamespace(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).
      */
     async get(): Promise<Envelope<SmtpConfig | null>> {
       return request(config, { method: "GET", path: orgPath("org/smtp") });
@@ -297,18 +297,18 @@ function makeSmtpNamespace(config: HttpClientConfig) {
 function makeDefaultLlmNamespace(config: HttpClientConfig) {
   return {
     /**
-     * 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.
      */
     async get(): Promise<Envelope<LLMModelId | null>> {
       return request(config, { method: "GET", path: orgPath("org/default-llm") });
     },
 
     /**
-     * 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.
      */
     async set(input: { modelId: LLMModelId }): Promise<Envelope<LLMModelId>> {
       return request(config, { method: "PATCH", path: orgPath("org/default-llm"), body: input });
@@ -332,7 +332,7 @@ export function makeOrgNamespace(config: HttpClientConfig) {
     gate: makeOrgGateNamespace(config),
     /** Org-level SMTP config — get / set / test / unset. */
     smtp: makeSmtpNamespace(config),
-    /** Org-default LLM — get / set per ch07 §10.3 (ORG_ADMIN). */
+    /** Org-default LLM — get / set (ORG_ADMIN). */
     defaultLLM: makeDefaultLlmNamespace(config),
 
     /**

package/src/orgs.ts

@@ -16,10 +16,10 @@
  * `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).
  */
 
 import { request, type HttpClientConfig } from "./http.ts";
@@ -27,7 +27,7 @@ import { orgPath, validateSlug } from "./url-grammar.ts";
 import type { Envelope } from "./envelope.ts";
 
 export type Org = {
-  /** `org_<base62>` per ch01 §3.2. */
+  /** `org_<base62>`. */
   id: string;
   slug: string;
   name: string;

package/src/policies.ts

@@ -13,7 +13,7 @@
  *   - `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.
  */
@@ -23,7 +23,7 @@ import { projectPath } from "./url-grammar.ts";
 import type { Envelope } from "./envelope.ts";
 
 export type PolicyBundle = {
-  /** `pol_<base62>` per ch01 §3.2. */
+  /** `pol_<base62>`. */
   id: string;
   name: string;
   version: number;

package/src/projects.ts

@@ -10,10 +10,10 @@
  *
  * 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.
  */
 
 import { request, type HttpClientConfig } from "./http.ts";
@@ -21,12 +21,12 @@ import { orgPath, projectPath, validateSlug } from "./url-grammar.ts";
 import type { Envelope } from "./envelope.ts";
 
 /**
- * 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.
  */
 export type Project = {
-  /** `proj_<base62>` per ch01 §3.2. */
+  /** `proj_<base62>`. */
   id: string;
   slug: string;
   name: string;
@@ -60,7 +60,7 @@ export function makeProjectsNamespace(config: HttpClientConfig) {
   return {
     /**
      * List projects accessible to the caller. Requires authenticated
-     * session; results are scoped by RBAC per ch06.
+     * session; results are scoped by RBAC.
      */
     async list(): Promise<Envelope<ReadonlyArray<Project>>> {
       return request<ReadonlyArray<Project>>(config, {