@greatwait/contracts 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/operations.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { PrincipalKind, Scope } from "./authority.js";
+import type { EnvironmentKind, PrincipalKind, Scope } from "./authority.js";
 import type { ProblemCode } from "./problems.js";
 /**
  * The operation registry: one declaration per public operation, and the single
@@ -100,6 +100,29 @@ export interface OperationDefinition {
      * teaches a shape the service will reject.
      */
     readonly example: unknown;
+    /**
+     * The environment kinds this operation is available in. Absent means both.
+     *
+     * **Declared because the tool listing has to know, and could not.**
+     * `tools/list` is filtered by `toolsVisibleTo`, which asks `authorizeOperation`
+     * — a decision about *scopes*. The environment restriction lived only in the
+     * routes and in prose, so a `live` credential holding `endpoints:read` was
+     * offered `testsinks_list`, `testsinks_read` and `sinkdeliveries_list`: three
+     * tools whose refusal tells it to "act in that environment instead", which a
+     * credential cannot do, because its authority is fixed when it is issued.
+     *
+     * Absent rather than required on all forty-one, because a restriction is the
+     * exception and a field repeated identically on thirty-four entries is one
+     * nobody reads. What stops the next restricted operation being forgotten is
+     * not this declaration but the case that drives every operation with both
+     * principals and compares the refusal against it — see
+     * `v1-environment-restriction.worker.test.ts`.
+     *
+     * **The filter is still a courtesy and the route is still the enforcement.**
+     * Nothing here is a permission check: a tool omitted from a listing is
+     * dispatched and refused exactly as before if a client calls it anyway.
+     */
+    readonly environments?: readonly EnvironmentKind[];
     /** Stable machine name, also the MCP tool name and the SDK method name. */
     readonly id: string;
     /**
@@ -1061,6 +1084,7 @@ export declare const OPERATIONS: readonly [{
         readonly updatedAt: "2026-08-07T15:00:00.000Z";
         readonly url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8";
     };
+    readonly environments: readonly ["test"];
     readonly id: "testsinks.create";
     readonly idempotent: false;
     readonly mcp: {
@@ -1189,6 +1213,7 @@ export declare const OPERATIONS: readonly [{
             readonly kind: "authoritative";
         };
     };
+    readonly environments: readonly ["test"];
     readonly id: "testsinks.list";
     readonly idempotent: true;
     readonly mcp: {
@@ -1281,6 +1306,7 @@ export declare const OPERATIONS: readonly [{
         readonly updatedAt: "2026-08-07T15:02:00.000Z";
         readonly url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8";
     };
+    readonly environments: readonly ["test"];
     readonly id: "testsinks.read";
     readonly idempotent: true;
     readonly mcp: {
@@ -1358,6 +1384,7 @@ export declare const OPERATIONS: readonly [{
         readonly updatedAt: "2026-08-07T15:03:00.000Z";
         readonly url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8";
     };
+    readonly environments: readonly ["test"];
     readonly id: "testsinks.configure";
     readonly idempotent: true;
     readonly mcp: {
@@ -1477,6 +1504,7 @@ export declare const OPERATIONS: readonly [{
             readonly kind: "authoritative";
         };
     };
+    readonly environments: readonly ["test"];
     readonly id: "sinkdeliveries.list";
     readonly idempotent: true;
     readonly mcp: {
@@ -1563,6 +1591,7 @@ export declare const OPERATIONS: readonly [{
         readonly signature: "v1=11135fdfc0bc5d49ebcc9d3a0d8df1116179097cefe961c6eca281339e5cfab3";
         readonly sink: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8";
     };
+    readonly environments: readonly ["test"];
     readonly id: "sinkdeliveries.read";
     readonly idempotent: true;
     readonly mcp: {
@@ -1635,6 +1664,7 @@ export declare const OPERATIONS: readonly [{
         readonly updatedAt: "2026-08-07T15:04:00.000Z";
         readonly url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8";
     };
+    readonly environments: readonly ["test"];
     readonly id: "testsinks.delete";
     readonly idempotent: true;
     readonly mcp: {
@@ -1746,6 +1776,57 @@ export declare const OPERATIONS: readonly [{
     readonly scopes: readonly [];
     readonly summary: "Set the mock scenario";
     readonly surfaces: readonly ["mock"];
+}, {
+    readonly creates: false;
+    readonly description: "Reports the authority the presented credential carries: the project it acts in, which of that project's two environments, and the scopes the service will enforce for it. The answer comes entirely from the verified principal, so there is no parameter that could name another project and no way for the reply to describe anything but the caller itself. It requires a principal and no scope, because every value in it is a property of the credential being presented rather than of anything the credential may reach: a caller that could not read this could still act, and would simply be acting without being able to say where. A signed-in member is not accepted — a session's authority is an organization and it names its project per request, so there is no single answer to give one.";
+    readonly example: {
+        readonly environmentKind: "test";
+        readonly principal: "api-credential";
+        readonly project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8";
+        readonly scopes: readonly ["schedules:read", "schedules:write"];
+    };
+    readonly id: "context.read";
+    readonly idempotent: true;
+    readonly mcp: {
+        readonly kind: "resource";
+        readonly uri: "greatwait://context";
+    };
+    readonly method: "GET";
+    readonly mutates: false;
+    readonly path: "/v1/context";
+    readonly principals: readonly ["api-credential", "oauth"];
+    readonly problems: readonly [];
+    readonly response: z.ZodObject<{
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        principal: z.ZodEnum<{
+            "api-credential": "api-credential";
+            oauth: "oauth";
+        }>;
+        project: z.ZodString;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "credentials:administer": "credentials:administer";
+            "credentials:read": "credentials:read";
+            "credentials:write": "credentials:write";
+            "endpoints:read": "endpoints:read";
+            "endpoints:write": "endpoints:write";
+            "forecast:read": "forecast:read";
+            "grants:read": "grants:read";
+            "grants:write": "grants:write";
+            "occurrences:read": "occurrences:read";
+            "occurrences:redeliver": "occurrences:redeliver";
+            "projects:read": "projects:read";
+            "projects:write": "projects:write";
+            "schedules:read": "schedules:read";
+            "schedules:write": "schedules:write";
+            "usage:read": "usage:read";
+        }>>;
+    }, z.core.$strip>;
+    readonly scopes: readonly [];
+    readonly summary: "Read this credential's authority";
+    readonly surfaces: readonly ["api", "mock"];
 }, {
     readonly creates: true;
     readonly description: "Issues an API credential bound to one project and environment, with scopes capped by the issuing member's current role. The full secret is in this response and in no other, is not recoverable afterwards, and there is deliberately no reveal endpoint. The value is the sixteen-character display prefix followed immediately by thirty-two more characters; the example below is a visible placeholder rather than that shape, because a realistic credential in a committed file is one the repository's own secret scanner refuses.";
@@ -1917,6 +1998,62 @@ export declare const OPERATIONS: readonly [{
     readonly sessionAuthority: "headers";
     readonly summary: "List API credentials";
     readonly surfaces: readonly ["api", "mock"];
+}, {
+    readonly creates: false;
+    readonly description: "Reads what a key this project issued should be able to do over MCP: the endpoint to point a client at, the discovery document beside it, the scopes fixed into the key when it was made, and the MCP tool names those scopes authorize. It returns no secret and cannot: the transient value is shown once at creation and is never sent here. The credential is addressed by identifier and re-resolved against the signed-in member's own project and environment, so a key belonging to another project answers exactly as one that does not exist. `state` distinguishes a key that still verifies from one that was revoked and one whose rotation overlap has run out, because a client configured with either fails identically and the remedies differ.";
+    readonly example: {
+        readonly discovery: "https://api.greatwait.dev/.well-known/oauth-protected-resource/mcp";
+        readonly displayPrefix: "pt_test_a1b2c3d4";
+        readonly endpoint: "https://api.greatwait.dev/mcp";
+        readonly id: "ak_01h8xyz9k2m4n6p8r0t2v4w6y8";
+        readonly scopes: readonly ["occurrences:read", "schedules:read", "schedules:write"];
+        readonly state: "usable";
+        readonly tools: readonly ["occurrences_list", "occurrences_read", "schedules_cancel", "schedules_create", "schedules_list", "schedules_read"];
+    };
+    readonly id: "credentials.connection";
+    readonly idempotent: true;
+    readonly mcp: {
+        readonly kind: "unavailable";
+        readonly reason: "A signed-in member checking a key whose secret is still on screen. MCP carries API credentials and OAuth tokens, neither of which holds a transient secret or a session to bind one to.";
+    };
+    readonly method: "GET";
+    readonly mutates: false;
+    readonly path: "/v1/credentials/{credentialId}/connection";
+    readonly principals: readonly ["session"];
+    readonly problems: readonly ["not_found"];
+    readonly response: z.ZodObject<{
+        discovery: z.ZodString;
+        displayPrefix: z.ZodString;
+        endpoint: z.ZodString;
+        id: z.ZodString;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "credentials:administer": "credentials:administer";
+            "credentials:read": "credentials:read";
+            "credentials:write": "credentials:write";
+            "endpoints:read": "endpoints:read";
+            "endpoints:write": "endpoints:write";
+            "forecast:read": "forecast:read";
+            "grants:read": "grants:read";
+            "grants:write": "grants:write";
+            "occurrences:read": "occurrences:read";
+            "occurrences:redeliver": "occurrences:redeliver";
+            "projects:read": "projects:read";
+            "projects:write": "projects:write";
+            "schedules:read": "schedules:read";
+            "schedules:write": "schedules:write";
+            "usage:read": "usage:read";
+        }>>;
+        state: z.ZodEnum<{
+            revoked: "revoked";
+            usable: "usable";
+            expired: "expired";
+        }>;
+        tools: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    readonly scopes: readonly ["credentials:read"];
+    readonly sessionAuthority: "headers";
+    readonly summary: "Read a credential's MCP connection";
+    readonly surfaces: readonly ["api", "mock"];
 }, {
     readonly creates: false;
     readonly description: "Lists the projects in the signed-in member's organization that they may act in, with the environment kinds each one has. This is what a browser asks before it can address anything else: an API credential and an OAuth token each carry one project intrinsically, but a member belongs to an organization and chooses. Archived and deleted projects are omitted, because a member cannot act in one. The result is a display aid rather than an authorization control — naming a project on a later request re-resolves it against the member's own organization, and a project that is not theirs answers exactly as one that does not exist.";
@@ -3982,4 +4119,21 @@ export declare const UNIVERSAL_PROBLEMS: readonly ProblemCode[];
  * whose rotation window has closed.
  */
 export declare const AUTHENTICATED_PROBLEMS: readonly ProblemCode[];
+/**
+ * The problem an operation returns when the principal is verified and its scope
+ * list falls short.
+ *
+ * **Separated from the list above at W10-01, because the two were keyed on the
+ * wrong field.** `problemsFor` read `scopes.length > 0` and published all four
+ * problems from it, which was exact only while "requires a scope" and "requires
+ * a credential" were the same sentence. `context.read` is the operation that
+ * needs a credential and no scope, and under the old rule it would have been
+ * published with no authentication problems and — through
+ * `securityRequirements` — no security requirement either: a route that refuses
+ * an anonymous caller, documented as open to one. Keying authentication on
+ * `principals` and this one on `scopes` says what each actually depends on, and
+ * it also stops publishing a `scope_missing` that no request to such an
+ * operation could ever produce.
+ */
+export declare const SCOPED_PROBLEMS: readonly ProblemCode[];
 export declare function problemsFor(operation: OperationDefinition): readonly ProblemCode[];

package/dist/operations.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { credentialContextSchema } from "./authority.js";
 import { callbackEndpointCreatedSchema, callbackEndpointPageSchema, callbackEndpointRequestSchema, callbackEndpointRotatedSchema, callbackEndpointSchema, callbackSigningKeyRotationRequestSchema, } from "./endpoints.js";
 import { FORECAST_WINDOW_VERSION, forecastRequestSchema, forecastSchema, forecastWindowsSchema, } from "./forecast.js";
 import { usageRequestSchema, usageSchema } from "./usage.js";
@@ -8,6 +9,7 @@ import { credentialCreatedSchema, credentialPageSchema, credentialRequestSchema,
 import { attemptPageSchema, attemptViewSchema, occurrencePageSchema, occurrenceViewSchema, schedulePageSchema, scheduleRequestSchema, scheduleViewSchema, } from "./scheduling.js";
 import { testSinkCreateRequestSchema, testSinkDeliveryBodySchema, testSinkDeliveryPageSchema, testSinkPageSchema, testSinkProgramSchema, testSinkSchema, } from "./test-sink.js";
 import { projectCreateRequestSchema, projectListSchema, projectSummarySchema, } from "./tenancy.js";
+import { mcpConnectionSchema } from "./mcp.js";
 import { scaffoldVersionSchema, workspaceScaffoldSchema } from "./workspace.js";
 import { timestampSchema } from "./time.js";
 /**
@@ -424,6 +426,7 @@ export const OPERATIONS = [
             updatedAt: "2026-08-07T15:00:00.000Z",
             url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
         },
+        environments: ["test"],
         id: "testsinks.create",
         idempotent: false,
         mcp: { destructive: false, kind: "tool", openWorld: false },
@@ -475,6 +478,7 @@ export const OPERATIONS = [
             ],
             freshness: { kind: "authoritative" },
         },
+        environments: ["test"],
         id: "testsinks.list",
         idempotent: true,
         mcp: { destructive: false, kind: "tool", openWorld: false },
@@ -504,6 +508,7 @@ export const OPERATIONS = [
             updatedAt: "2026-08-07T15:02:00.000Z",
             url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
         },
+        environments: ["test"],
         id: "testsinks.read",
         idempotent: true,
         mcp: { destructive: false, kind: "tool", openWorld: false },
@@ -532,6 +537,7 @@ export const OPERATIONS = [
             updatedAt: "2026-08-07T15:03:00.000Z",
             url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
         },
+        environments: ["test"],
         id: "testsinks.configure",
         idempotent: true,
         mcp: { destructive: false, kind: "tool", openWorld: false },
@@ -568,6 +574,7 @@ export const OPERATIONS = [
             ],
             freshness: { kind: "authoritative" },
         },
+        environments: ["test"],
         id: "sinkdeliveries.list",
         idempotent: true,
         mcp: { destructive: false, kind: "tool", openWorld: false },
@@ -602,6 +609,7 @@ export const OPERATIONS = [
             signature: "v1=11135fdfc0bc5d49ebcc9d3a0d8df1116179097cefe961c6eca281339e5cfab3",
             sink: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
         },
+        environments: ["test"],
         id: "sinkdeliveries.read",
         idempotent: true,
         mcp: {
@@ -633,6 +641,7 @@ export const OPERATIONS = [
             updatedAt: "2026-08-07T15:04:00.000Z",
             url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
         },
+        environments: ["test"],
         id: "testsinks.delete",
         idempotent: true,
         mcp: { destructive: true, kind: "tool", openWorld: false },
@@ -673,6 +682,40 @@ export const OPERATIONS = [
         summary: "Set the mock scenario",
         surfaces: ["mock"],
     },
+    {
+        creates: false,
+        description: "Reports the authority the presented credential carries: the project it acts in, which of that project's two environments, and the scopes the service will enforce for it. The answer comes entirely from the verified principal, so there is no parameter that could name another project and no way for the reply to describe anything but the caller itself. It requires a principal and no scope, because every value in it is a property of the credential being presented rather than of anything the credential may reach: a caller that could not read this could still act, and would simply be acting without being able to say where. A signed-in member is not accepted — a session's authority is an organization and it names its project per request, so there is no single answer to give one.",
+        example: {
+            environmentKind: "test",
+            principal: "api-credential",
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            scopes: ["schedules:read", "schedules:write"],
+        },
+        id: "context.read",
+        idempotent: true,
+        // A resource rather than a tool: it takes no arguments, it reports a fact
+        // about the caller, and an agent choosing between tools should not have to
+        // step past "what am I" to find the operations that schedule anything.
+        // Being scopeless is what makes a resource legal here — `check:mcp-parity`
+        // refuses a resource that requires one, because a resource carries no
+        // scope declaration for a host to gate on.
+        mcp: { kind: "resource", uri: "greatwait://context" },
+        method: "GET",
+        mutates: false,
+        path: "/v1/context",
+        principals: ["api-credential", "oauth"],
+        // No `not_found`: the authority tuple exists by the time a principal is
+        // verified, so there is nothing here that can be absent.
+        problems: [],
+        response: credentialContextSchema,
+        // **Empty, and that is the point of the operation.** Every other
+        // authenticated operation names the scope it consumes; this one consumes
+        // none, so `scope_missing` is a refusal it can never produce and
+        // `problemsFor` does not publish one for it.
+        scopes: [],
+        summary: "Read this credential's authority",
+        surfaces: ["api", "mock"],
+    },
     {
         creates: true,
         description: "Issues an API credential bound to one project and environment, with scopes capped by the issuing member's current role. The full secret is in this response and in no other, is not recoverable afterwards, and there is deliberately no reveal endpoint. The value is the sixteen-character display prefix followed immediately by thirty-two more characters; the example below is a visible placeholder rather than that shape, because a realistic credential in a committed file is one the repository's own secret scanner refuses.",
@@ -776,6 +819,48 @@ export const OPERATIONS = [
         summary: "List API credentials",
         surfaces: ["api", "mock"],
     },
+    {
+        creates: false,
+        description: "Reads what a key this project issued should be able to do over MCP: the endpoint to point a client at, the discovery document beside it, the scopes fixed into the key when it was made, and the MCP tool names those scopes authorize. It returns no secret and cannot: the transient value is shown once at creation and is never sent here. The credential is addressed by identifier and re-resolved against the signed-in member's own project and environment, so a key belonging to another project answers exactly as one that does not exist. `state` distinguishes a key that still verifies from one that was revoked and one whose rotation overlap has run out, because a client configured with either fails identically and the remedies differ.",
+        example: {
+            discovery: "https://api.greatwait.dev/.well-known/oauth-protected-resource/mcp",
+            displayPrefix: "pt_test_a1b2c3d4",
+            endpoint: "https://api.greatwait.dev/mcp",
+            id: "ak_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            scopes: ["occurrences:read", "schedules:read", "schedules:write"],
+            state: "usable",
+            tools: [
+                "occurrences_list",
+                "occurrences_read",
+                "schedules_cancel",
+                "schedules_create",
+                "schedules_list",
+                "schedules_read",
+            ],
+        },
+        id: "credentials.connection",
+        idempotent: true,
+        // **Withheld, and the reason is the same one that withholds issuance.** A
+        // member asks this about a key they are holding in a browser, in the window
+        // where its secret is still on screen. An agent is already connected: it has
+        // no transient secret to check and no session to bind one to, so a tool here
+        // would answer `authentication_required` to every caller that could reach
+        // it. Publishing the exclusion is the honest version of that.
+        mcp: {
+            kind: "unavailable",
+            reason: "A signed-in member checking a key whose secret is still on screen. MCP carries API credentials and OAuth tokens, neither of which holds a transient secret or a session to bind one to.",
+        },
+        method: "GET",
+        mutates: false,
+        path: "/v1/credentials/{credentialId}/connection",
+        principals: ["session"],
+        problems: ["not_found"],
+        response: mcpConnectionSchema,
+        scopes: ["credentials:read"],
+        sessionAuthority: "headers",
+        summary: "Read a credential's MCP connection",
+        surfaces: ["api", "mock"],
+    },
     {
         creates: false,
         description: "Lists the projects in the signed-in member's organization that they may act in, with the environment kinds each one has. This is what a browser asks before it can address anything else: an API credential and an OAuth token each carry one project intrinsically, but a member belongs to an organization and chooses. Archived and deleted projects are omitted, because a member cannot act in one. The result is a display aid rather than an authorization control — naming a project on a later request re-resolves it against the member's own organization, and a project that is not theirs answers exactly as one that does not exist.",
@@ -1824,14 +1909,31 @@ export const AUTHENTICATED_PROBLEMS = [
     "authentication_required",
     "credential_expired",
     "credential_revoked",
-    "scope_missing",
 ];
+/**
+ * The problem an operation returns when the principal is verified and its scope
+ * list falls short.
+ *
+ * **Separated from the list above at W10-01, because the two were keyed on the
+ * wrong field.** `problemsFor` read `scopes.length > 0` and published all four
+ * problems from it, which was exact only while "requires a scope" and "requires
+ * a credential" were the same sentence. `context.read` is the operation that
+ * needs a credential and no scope, and under the old rule it would have been
+ * published with no authentication problems and — through
+ * `securityRequirements` — no security requirement either: a route that refuses
+ * an anonymous caller, documented as open to one. Keying authentication on
+ * `principals` and this one on `scopes` says what each actually depends on, and
+ * it also stops publishing a `scope_missing` that no request to such an
+ * operation could ever produce.
+ */
+export const SCOPED_PROBLEMS = ["scope_missing"];
 export function problemsFor(operation) {
     return [
         ...new Set([
             ...operation.problems,
             ...UNIVERSAL_PROBLEMS,
-            ...(operation.scopes.length > 0 ? AUTHENTICATED_PROBLEMS : []),
+            ...(operation.principals.length > 0 ? AUTHENTICATED_PROBLEMS : []),
+            ...(operation.scopes.length > 0 ? SCOPED_PROBLEMS : []),
         ]),
     ].sort();
 }

package/generated/v1/examples/context.read.response.json

@@ -0,0 +1,6 @@
+{
+  "environmentKind": "test",
+  "principal": "api-credential",
+  "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+  "scopes": ["schedules:read", "schedules:write"]
+}

package/generated/v1/examples/credentials.connection.response.json

@@ -0,0 +1,16 @@
+{
+  "discovery": "https://api.greatwait.dev/.well-known/oauth-protected-resource/mcp",
+  "displayPrefix": "pt_test_a1b2c3d4",
+  "endpoint": "https://api.greatwait.dev/mcp",
+  "id": "ak_01h8xyz9k2m4n6p8r0t2v4w6y8",
+  "scopes": ["occurrences:read", "schedules:read", "schedules:write"],
+  "state": "usable",
+  "tools": [
+    "occurrences_list",
+    "occurrences_read",
+    "schedules_cancel",
+    "schedules_create",
+    "schedules_list",
+    "schedules_read"
+  ]
+}

package/generated/v1/manifest.json

@@ -2,10 +2,13 @@
   "contractVersion": "2026-08-22",
   "externalFiles": [
     "docs/quickstarts/README.md",
+    "docs/quickstarts/cli.md",
     "docs/quickstarts/curl.md",
     "docs/quickstarts/first-value.mjs",
     "docs/quickstarts/first-value.sh",
     "docs/quickstarts/javascript.md",
+    "docs/quickstarts/mcp-reference.md",
+    "docs/quickstarts/mcp.md",
     "packages/api-client/src/operations.generated.ts",
     "packages/mcp-tools/src/schemas.generated.ts"
   ],
@@ -15,6 +18,8 @@
     "callback-receiver.json",
     "examples/attempts.list.response.json",
     "examples/attempts.read.response.json",
+    "examples/context.read.response.json",
+    "examples/credentials.connection.response.json",
     "examples/credentials.create.request.json",
     "examples/credentials.create.response.json",
     "examples/credentials.list.response.json",
@@ -75,6 +80,8 @@
     "schemas/attempts.list.query.json",
     "schemas/attempts.list.response.json",
     "schemas/attempts.read.response.json",
+    "schemas/context.read.response.json",
+    "schemas/credentials.connection.response.json",
     "schemas/credentials.create.request.json",
     "schemas/credentials.create.response.json",
     "schemas/credentials.list.query.json",
@@ -161,6 +168,8 @@
     "schemas/usage.read.response.json",
     "snippets/attempts.list.json",
     "snippets/attempts.read.json",
+    "snippets/context.read.json",
+    "snippets/credentials.connection.json",
     "snippets/credentials.create.json",
     "snippets/credentials.list.json",
     "snippets/credentials.revoke.json",
@@ -176,6 +185,15 @@
     "snippets/forecast.windows.json",
     "snippets/grants.list.json",
     "snippets/grants.revoke.json",
+    "snippets/journey/await-occurrence.json",
+    "snippets/journey/check-credential.json",
+    "snippets/journey/check-service.json",
+    "snippets/journey/clean-up.json",
+    "snippets/journey/create-destination.json",
+    "snippets/journey/create-one-shot.json",
+    "snippets/journey/read-attempt.json",
+    "snippets/journey/read-schedule.json",
+    "snippets/journey/replay-one-shot.json",
     "snippets/meta.scaffold.json",
     "snippets/meta.version.json",
     "snippets/mock/mock.getFixture.json",
@@ -546,6 +564,22 @@
       "scopes": [],
       "surfaces": ["mock"]
     },
+    {
+      "id": "context.read",
+      "method": "GET",
+      "mutates": false,
+      "path": "/v1/context",
+      "principals": ["api-credential", "oauth"],
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "rate_limited",
+        "service_unavailable"
+      ],
+      "scopes": [],
+      "surfaces": ["api", "mock"]
+    },
     {
       "id": "credentials.create",
       "method": "POST",
@@ -585,6 +619,25 @@
       "sessionAuthority": "headers",
       "surfaces": ["api", "mock"]
     },
+    {
+      "id": "credentials.connection",
+      "method": "GET",
+      "mutates": false,
+      "path": "/v1/credentials/{credentialId}/connection",
+      "principals": ["session"],
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "not_found",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["credentials:read"],
+      "sessionAuthority": "headers",
+      "surfaces": ["api", "mock"]
+    },
     {
       "id": "projects.list",
       "method": "GET",