@typeship-ax/mcp 0.8.0 → 0.10.0

package/src/types.ts

@@ -34,6 +34,8 @@ export type DeliveryId = string;
 
 export type TargetReleaseId = string;
 
+export type PublicationId = string;
+
 /**
  * Generator implementation selected by a Target. This is configuration, not identity; several
  * Targets may use the same generator.
@@ -592,6 +594,15 @@ export interface Diagnostic {
   impact: string;
   /** Public surfaces affected by the root cause. */
   surfaces: Array<"api" | "sdk" | "cli" | "mcp">;
+  /**
+   * Whether the finding is provable from the Definition, a conservative review suggestion, or a
+   * documented Typeship implementation limitation.
+   */
+  evidence_basis: "contract" | "heuristic" | "implementation";
+  /** Whether remediation requires intent that the Definition cannot prove. */
+  owner_decision_required: boolean;
+  /** Concrete generated SDK, CLI, or MCP naming effect when Typeship can state it. */
+  surface_impact?: string;
   /** All affected coordinates, kept under one grouped diagnostic. */
   locations: DiagnosticLocation[];
   fix?: DiagnosticFix;
@@ -618,6 +629,15 @@ export interface DiagnosticRead {
   impact: string;
   /** Public surfaces affected by the root cause. */
   surfaces: Array<("api" | "sdk" | "cli" | "mcp") | (string & {})>;
+  /**
+   * Whether the finding is provable from the Definition, a conservative review suggestion, or a
+   * documented Typeship implementation limitation.
+   */
+  evidence_basis: ("contract" | "heuristic" | "implementation") | (string & {});
+  /** Whether remediation requires intent that the Definition cannot prove. */
+  owner_decision_required: boolean;
+  /** Concrete generated SDK, CLI, or MCP naming effect when Typeship can state it. */
+  surface_impact?: string;
   /** All affected coordinates, kept under one grouped diagnostic. */
   locations: DiagnosticLocation[];
   fix?: DiagnosticFixRead;
@@ -702,6 +722,24 @@ export interface DiagnosticEvaluationRead {
   suppressed_occurrences: number;
 }
 
+/** Current-revision suppression usage for one stable Diagnostic rule. */
+export interface DiagnosticSuppressionSignal {
+  rule_id: string;
+  /** Current occurrences of this rule that are not suppressed. */
+  active_occurrences: number;
+  suppressed_occurrences: number;
+}
+
+/**
+ * Current-revision signals for tuning Diagnostics policy. These counts do not claim that a
+ * suppression is a false positive or that runtime behavior has been verified.
+ */
+export interface DiagnosticQualitySignals {
+  suppressed_by_rule: DiagnosticSuppressionSignal[];
+  /** Reviewed exceptions whose rule or exact path no longer matches this revision. */
+  stale_suppressions: DiagnosticSuppression[];
+}
+
 /** Compact rule and location reference; full guidance appears once in diagnostics. */
 export interface DiagnosticReference {
   rule_id: string;
@@ -752,6 +790,7 @@ export interface DiagnosticReport {
   diagnostics: Diagnostic[];
   policy: DiagnosticPolicy;
   evaluation: DiagnosticEvaluation;
+  quality_signals: DiagnosticQualitySignals;
   delta: DiagnosticDelta;
   request_id: RequestId;
 }
@@ -774,6 +813,7 @@ export interface DiagnosticReportRead {
   diagnostics: DiagnosticRead[];
   policy: DiagnosticPolicyRead;
   evaluation: DiagnosticEvaluationRead;
+  quality_signals: DiagnosticQualitySignals;
   delta: DiagnosticDeltaRead;
   request_id: RequestId;
 }
@@ -816,6 +856,11 @@ export interface RepositoryDeliveryInput {
   package_name?: string | null;
   /** Explicit Go module path where applicable. */
   module_path?: string | null;
+  /**
+   * Commit repository-owned registry automation and report publication after the Draft merges.
+   * Default: false
+   */
+  publish_on_merge?: boolean;
 }
 
 /** Response shape for RepositoryDeliveryInput. */
@@ -827,6 +872,11 @@ export interface RepositoryDeliveryInputRead {
   package_name?: string | null;
   /** Explicit Go module path where applicable. */
   module_path?: string | null;
+  /**
+   * Commit repository-owned registry automation and report publication after the Draft merges.
+   * Default: false
+   */
+  publish_on_merge?: boolean;
 }
 
 export interface HostedMcpDeliveryInput {
@@ -855,6 +905,7 @@ export interface RepositoryDelivery {
   directory: string | null;
   package_name: string | null;
   module_path: string | null;
+  publish_on_merge: boolean;
   /** Format: date-time */
   created_at: string;
   /** Format: date-time */
@@ -872,6 +923,7 @@ export interface RepositoryDeliveryRead {
   directory: string | null;
   package_name: string | null;
   module_path: string | null;
+  publish_on_merge: boolean;
   /** Format: date-time */
   created_at: string;
   /** Format: date-time */
@@ -930,7 +982,7 @@ export interface TargetFields {
    * Target-specific overrides merged over Project.config. GraphQL settings are rejected here and
    * belong to the Definition.
    */
-  config?: ProjectConfig | null;
+  config?: TargetConfig | null;
   deliveries?: DeliveryInput[];
 }
 
@@ -951,7 +1003,7 @@ export interface TargetFieldsRead {
    * Target-specific overrides merged over Project.config. GraphQL settings are rejected here and
    * belong to the Definition.
    */
-  config?: ProjectConfigRead | null;
+  config?: TargetConfigRead | null;
   deliveries?: DeliveryInputRead[];
 }
 
@@ -969,7 +1021,7 @@ export interface InitialTargetFields {
    * Target-specific overrides merged over Project.config. GraphQL settings are rejected here and
    * belong to the Definition.
    */
-  config?: ProjectConfig | null;
+  config?: TargetConfig | null;
   deliveries?: DeliveryInput[];
 }
 
@@ -988,7 +1040,7 @@ export interface InitialTargetFieldsRead {
    * Target-specific overrides merged over Project.config. GraphQL settings are rejected here and
    * belong to the Definition.
    */
-  config?: ProjectConfigRead | null;
+  config?: TargetConfigRead | null;
   deliveries?: DeliveryInputRead[];
 }
 
@@ -1002,7 +1054,7 @@ export interface TargetUpdateRequest {
    * Target-specific overrides merged over Project.config. GraphQL settings are rejected here and
    * belong to the Definition.
    */
-  config?: ProjectConfig | null;
+  config?: TargetConfig | null;
   deliveries?: DeliveryInput[];
 }
 
@@ -1017,7 +1069,7 @@ export interface TargetUpdateRequestRead {
    * Target-specific overrides merged over Project.config. GraphQL settings are rejected here and
    * belong to the Definition.
    */
-  config?: ProjectConfigRead | null;
+  config?: TargetConfigRead | null;
   deliveries?: DeliveryInputRead[];
 }
 
@@ -1035,13 +1087,23 @@ export interface Target {
     mode: "reviewed_semver";
     pre1_breaking: "minor";
   };
-  current_version: string;
+  /**
+   * Deprecated projection of the newest immutable Target Release; null until a release becomes
+   * Current.
+   * @deprecated
+   */
+  current_version: string | null;
   proposed_version: string | null;
+  proposed_version_source: "console" | "api" | "github" | null;
+  proposed_version_actor: string | null;
+  /** Optimistic concurrency revision for Draft selections. */
+  release_revision: number;
   /**
    * Target-specific overrides merged over Project.config. GraphQL settings are Definition-owned and
    * never appear here.
    */
-  config: ProjectConfig | null;
+  config: TargetConfig | null;
+  /** At most one repository and one hosted MCP Delivery. */
   deliveries: Delivery[];
   /** Format: date-time */
   created_at: string;
@@ -1065,13 +1127,23 @@ export interface TargetRead {
     mode: "reviewed_semver" | (string & {});
     pre1_breaking: "minor" | (string & {});
   };
-  current_version: string;
+  /**
+   * Deprecated projection of the newest immutable Target Release; null until a release becomes
+   * Current.
+   * @deprecated
+   */
+  current_version: string | null;
   proposed_version: string | null;
+  proposed_version_source: ("console" | "api" | "github" | null) | (string & {}) | null;
+  proposed_version_actor: string | null;
+  /** Optimistic concurrency revision for Draft selections. */
+  release_revision: number;
   /**
    * Target-specific overrides merged over Project.config. GraphQL settings are Definition-owned and
    * never appear here.
    */
-  config: ProjectConfigRead | null;
+  config: TargetConfigRead | null;
+  /** At most one repository and one hosted MCP Delivery. */
   deliveries: DeliveryRead[];
   /** Format: date-time */
   created_at: string;
@@ -1106,7 +1178,9 @@ export interface TargetRelease {
   id: TargetReleaseId;
   object: "target_release";
   target_id: TargetId;
-  generation_id: GenerationId;
+  /** Null only for a verified release imported during package adoption. */
+  generation_id: GenerationId | null;
+  origin: "typeship" | "imported";
   /** Immutable package version released from this Target. */
   version: string;
   channel: "stable" | "prerelease";
@@ -1116,6 +1190,16 @@ export interface TargetRelease {
   definition_revision_id: DefinitionRevisionId | null;
   /** Immutable provider-native revision that was merged or published. */
   delivery_revision: string;
+  import_provenance: {
+    tag: string | null;
+    /** Format: uri */
+    registry_url: string | null;
+    artifact_digest: string | null;
+    /** Format: date-time */
+    imported_at: string | null;
+  }
+    | null;
+  publications: Publication[];
   /** Format: date-time */
   created_at: string;
   request_id?: RequestId;
@@ -1126,7 +1210,9 @@ export interface TargetReleaseRead {
   id: TargetReleaseId;
   object: "target_release" | (string & {});
   target_id: TargetId;
-  generation_id: GenerationId;
+  /** Null only for a verified release imported during package adoption. */
+  generation_id: GenerationId | null;
+  origin: ("typeship" | "imported") | (string & {});
   /** Immutable package version released from this Target. */
   version: string;
   channel: ("stable" | "prerelease") | (string & {});
@@ -1136,6 +1222,16 @@ export interface TargetReleaseRead {
   definition_revision_id: DefinitionRevisionId | null;
   /** Immutable provider-native revision that was merged or published. */
   delivery_revision: string;
+  import_provenance: {
+    tag: string | null;
+    /** Format: uri */
+    registry_url: string | null;
+    artifact_digest: string | null;
+    /** Format: date-time */
+    imported_at: string | null;
+  }
+    | null;
+  publications: PublicationRead[];
   /** Format: date-time */
   created_at: string;
   request_id?: RequestId;
@@ -1163,6 +1259,131 @@ export interface TargetReleaseListRead {
   request_id: RequestId;
 }
 
+export interface Publication {
+  id: PublicationId;
+  object: "publication";
+  target_release_id: TargetReleaseId;
+  destination: "github" | "npm" | "pypi" | "go" | "mcp";
+  state: "pending" | "publishing" | "published" | "failed";
+  attempt: number;
+  /** Format: uri */
+  run_url: string | null;
+  /** Format: uri */
+  registry_url: string | null;
+  artifact_digest: string | null;
+  error: string | null;
+  /** Format: date-time */
+  started_at: string | null;
+  /** Format: date-time */
+  finished_at: string | null;
+  /** Format: date-time */
+  updated_at: string;
+}
+
+/** Response shape for Publication. */
+export interface PublicationRead {
+  id: PublicationId;
+  object: "publication" | (string & {});
+  target_release_id: TargetReleaseId;
+  destination: ("github" | "npm" | "pypi" | "go" | "mcp") | (string & {});
+  state: ("pending" | "publishing" | "published" | "failed") | (string & {});
+  attempt: number;
+  /** Format: uri */
+  run_url: string | null;
+  /** Format: uri */
+  registry_url: string | null;
+  artifact_digest: string | null;
+  error: string | null;
+  /** Format: date-time */
+  started_at: string | null;
+  /** Format: date-time */
+  finished_at: string | null;
+  /** Format: date-time */
+  updated_at: string;
+}
+
+export type TargetDraftSelection = {
+  mode: "automatic";
+}
+  | {
+      mode: "exact";
+      version: string;
+      source: "console" | "api" | "github" | null;
+      actor: string | null;
+    };
+
+/** Response shape for TargetDraftSelection. */
+export type TargetDraftSelectionRead = {
+  mode: "automatic" | (string & {});
+}
+  | {
+      mode: "exact" | (string & {});
+      version: string;
+      source: ("console" | "api" | "github" | null) | (string & {}) | null;
+      actor: string | null;
+    };
+
+export interface TargetDraft {
+  object: "target_draft";
+  target_id: TargetId;
+  revision: number;
+  current_version: string | null;
+  version: string | null;
+  selection: TargetDraftSelection;
+  readiness: Record<string, unknown> | null;
+  changes: {
+    /** Cumulative changelog against Current. */
+    changelog?: string | null;
+    breaking_count?: number | null;
+    previous_version?: string | null;
+  }
+    | null;
+  head_revision: string | null;
+  /** Format: uri */
+  pull_request_url: string | null;
+  request_id?: RequestId;
+}
+
+/** Response shape for TargetDraft. */
+export interface TargetDraftRead {
+  object: "target_draft" | (string & {});
+  target_id: TargetId;
+  revision: number;
+  current_version: string | null;
+  version: string | null;
+  selection: TargetDraftSelectionRead;
+  readiness: Record<string, unknown> | null;
+  changes: {
+    /** Cumulative changelog against Current. */
+    changelog?: string | null;
+    breaking_count?: number | null;
+    previous_version?: string | null;
+  }
+    | null;
+  head_revision: string | null;
+  /** Format: uri */
+  pull_request_url: string | null;
+  request_id?: RequestId;
+}
+
+export type TargetDraftResponse = TargetDraft & ResponseMetadata;
+
+/** Response shape for TargetDraftResponse. */
+export type TargetDraftResponseRead = TargetDraftRead & ResponseMetadata;
+
+export interface TargetDraftUpdate {
+  /** Exact SemVer, or null to return to automatic selection. */
+  version: string | null;
+  expected_revision?: number;
+}
+
+export interface TargetAdoption {
+  /** Exact already-published package version to make Current. */
+  version: string;
+  /** Immutable repository tag containing the matching package source. */
+  tag: string;
+}
+
 export interface RepositoryHealthIssue {
   code: "connection_missing"
     | "definition_unreadable"
@@ -1350,18 +1571,15 @@ export interface DefinitionUpdateRequestRead {
   diagnostic_policy?: DiagnosticPolicyRead;
 }
 
+/**
+ * Project-owned identity, Definition reference, generation controls, and shared configuration.
+ * Targets and Deliveries are available only through their canonical Target endpoints.
+ */
 export interface Project {
   id: ProjectId;
   object: "project";
   name: string;
   definition_id: DefinitionId;
-  /** All configured Targets, including disabled Targets and their saved Deliveries. */
-  targets: Target[];
-  /**
-   * Flattened convenience view derived from the same Target bundles. Every Delivery retains
-   * target_id so ownership is explicit.
-   */
-  deliveries: Delivery[];
   /**
    * Regenerate when the Definition changes: on every push to the default branch for a repository
    * source, every 30 minutes for a URL source. Off by default: the first generation is always one
@@ -1393,13 +1611,6 @@ export interface Project {
 export interface ProjectWrite {
   name: string;
   definition_id: DefinitionId;
-  /** All configured Targets, including disabled Targets and their saved Deliveries. */
-  targets: Target[];
-  /**
-   * Flattened convenience view derived from the same Target bundles. Every Delivery retains
-   * target_id so ownership is explicit.
-   */
-  deliveries: Delivery[];
   /**
    * Regenerate when the Definition changes: on every push to the default branch for a repository
    * source, every 30 minutes for a URL source. Off by default: the first generation is always one
@@ -1426,13 +1637,6 @@ export interface ProjectRead {
   object: "project" | (string & {});
   name: string;
   definition_id: DefinitionId;
-  /** All configured Targets, including disabled Targets and their saved Deliveries. */
-  targets: TargetRead[];
-  /**
-   * Flattened convenience view derived from the same Target bundles. Every Delivery retains
-   * target_id so ownership is explicit.
-   */
-  deliveries: DeliveryRead[];
   /**
    * Regenerate when the Definition changes: on every push to the default branch for a repository
    * source, every 30 minutes for a URL source. Off by default: the first generation is always one
@@ -1461,8 +1665,8 @@ export interface ProjectRead {
 }
 
 /**
- * Lean Project identity returned by collection endpoints. Retrieve the Project or list its Targets
- * for the complete aggregate.
+ * Lean Project identity returned by collection endpoints. Retrieve the Project for shared
+ * configuration and list its Targets for the complete canonical child collection.
  */
 export interface ProjectSummary {
   id: ProjectId;
@@ -1580,30 +1784,151 @@ export interface AccountRead {
   request_id: RequestId;
 }
 
-/** How the generated CLI behaves. Part of Config. */
-export interface CliBehavior {
-  /** Command users run, independent of how the CLI is distributed. */
-  command_name?: string | null;
+/**
+ * Authorization-server metadata used by generated OAuth flows. Secrets and runtime credentials are
+ * never accepted here.
+ */
+export interface OAuthServer {
+  /**
+   * Exact authorization-server issuer, including any tenant path.
+   * Format: uri
+   */
+  issuer?: string | null;
+  /**
+   * Exact metadata URL when it cannot be derived from the issuer.
+   * Format: uri
+   */
+  discovery_url?: string | null;
+  /**
+   * Authorization endpoint override.
+   * Format: uri
+   */
+  authorization_url?: string | null;
   /**
-   * resource.method of a zero-argument GET that the generated CLI's whoami command calls. Overrides
-   * auto-detection; a value that matches nothing is reported as a generation warning.
+   * Token endpoint override.
+   * Format: uri
    */
-  whoami_operation?: string | null;
+  token_url?: string | null;
   /**
-   * OAuth client id baked into the generated CLI for device-flow login. Without it, login prompts
-   * for a pasted credential.
+   * Device-authorization endpoint override.
+   * Format: uri
    */
-  oauth_client_id?: string | null;
+  device_authorization_url?: string | null;
+  /** Default scopes requested during login. */
+  scopes?: string[] | null;
+  /** Default audience included in authorization and token requests. */
+  audience?: string | null;
   /**
-   * Scopes requested during device-flow login. Include offline_access if the authorization server
-   * gates refresh tokens behind it.
+   * Protected API resource included in authorization and token requests.
+   * Format: uri
+   */
+  resource?: string | null;
+}
+
+/**
+ * OAuth application available to generated products. Public clients support interactive login;
+ * confidential clients support runtime-supplied machine credentials. Client secrets are never
+ * stored.
+ */
+export interface OAuthApplication {
+  /** OAuth client identifier. */
+  client_id: string;
+  /** Interactive login method. Browser login uses Authorization Code with PKCE. */
+  login_method?: "browser" | "device" | null;
+  /** How a runtime-supplied client secret is sent for machine grants. */
+  client_auth_method?: "post" | "basic" | null;
+  /**
+   * Loopback callback URL for browser login.
+   * Format: uri
    */
-  oauth_scopes?: string[];
+  redirect_uri?: string | null;
+  /** Provider parameter used to request an organization during browser login. */
+  organization_parameter?: "organization" | "organization_id" | null;
+}
+
+/** Response shape for OAuthApplication. */
+export interface OAuthApplicationRead {
+  /** OAuth client identifier. */
+  client_id: string;
+  /** Interactive login method. Browser login uses Authorization Code with PKCE. */
+  login_method?: ("browser" | "device" | null) | (string & {}) | null;
+  /** How a runtime-supplied client secret is sent for machine grants. */
+  client_auth_method?: ("post" | "basic" | null) | (string & {}) | null;
   /**
-   * Audience sent with the device-authorization request, for authorization servers that require one
-   * to issue API-valid access tokens.
+   * Loopback callback URL for browser login.
+   * Format: uri
+   */
+  redirect_uri?: string | null;
+  /** Provider parameter used to request an organization during browser login. */
+  organization_parameter?: ("organization" | "organization_id" | null) | (string & {}) | null;
+}
+
+/**
+ * Authenticated identity read used to verify a login before it is saved. Operation is auto-detected
+ * when omitted. Requests must include at least one of subject_field, account_field, or
+ * organization_field.
+ */
+export interface IdentityVerification {
+  /** resource.method of a safe identity read with no required arguments. */
+  operation?: string;
+  /** JSON Pointer to the stable caller ID in the identity response. */
+  subject_field?: string;
+  /** JSON Pointer to the customer account ID. */
+  account_field?: string;
+  /** JSON Pointer to the customer organization ID. */
+  organization_field?: string;
+}
+
+/** OAuth application and request-value overrides for one named API environment. */
+export interface AuthenticationEnvironment {
+  oauth_application?: string | null;
+  scopes?: string[] | null;
+  audience?: string | null;
+  /** Format: uri */
+  resource?: string | null;
+}
+
+/**
+ * Public authentication defaults for generated clients and tools. Stored Projects own the OAuth
+ * server, application catalog, and identity policy; stateless generation accepts the same shape for
+ * one run. Runtime credentials and client secrets are never accepted.
+ */
+export interface AuthenticationConfig {
+  oauth_server?: OAuthServer | null;
+  /** OAuth applications keyed by a stable name. */
+  oauth_applications?: Record<string, OAuthApplication> | null;
+  /** Default OAuth application used by generated products. */
+  oauth_application?: string | null;
+  identity_verification?: IdentityVerification | null;
+  /**
+   * Base URL of a custom browser-approval backend implementing the start, status, and revoke
+   * contract. Used only when OAuth is not configured.
+   * Format: uri
    */
-  oauth_audience?: string | null;
+  approval_url?: string | null;
+  /** Authentication selections keyed by generated API environment name. */
+  environments?: Record<string, AuthenticationEnvironment> | null;
+}
+
+export interface TargetAuthenticationEnvironment {
+  oauth_application?: string | null;
+}
+
+/**
+ * Selects a Project OAuth application for one Target. OAuth server metadata, applications, and
+ * identity policy remain Project-owned.
+ */
+export interface TargetAuthenticationConfig {
+  /** Project OAuth application to use. Omit to inherit the Project default. */
+  oauth_application?: string | null;
+  /** Project OAuth application selections keyed by API environment. */
+  environments?: Record<string, TargetAuthenticationEnvironment> | null;
+}
+
+/** How the generated CLI behaves. Part of Config. */
+export interface CliBehavior {
+  /** Command users run, independent of how the CLI is distributed. */
+  command_name?: string | null;
   /**
    * Opt in to a once-a-day registry check that prints an upgrade hint. Off by default; generated
    * code phones nobody unless this is enabled.
@@ -1614,11 +1939,6 @@ export interface CliBehavior {
    * title and environment details.
    */
   support_url?: string | null;
-  /**
-   * Base URL of the browser-approval endpoint pair used by CLI login. The CLI keeps the verifier
-   * and receives the credential directly; no key is pasted through a conversation.
-   */
-  auth_url?: string | null;
   /**
    * Hosted MCP endpoint installed by the generated CLI instead of launching the package's local
    * stdio server.
@@ -1628,10 +1948,34 @@ export interface CliBehavior {
   skills_repo?: string | null;
 }
 
-/** How the generated MCP server and the hosted endpoint behave. Part of Config. */
+/** How generated MCP servers and the Typeship-hosted endpoint behave. Part of Config. */
 export interface McpBehavior {
   /** Stable official MCP registry name, independent of the server runtime. */
   registry_name?: string | null;
+  /**
+   * Authorization for callers connecting to a generated MCP server deployed over HTTP. The hosting
+   * application resolves upstream API credentials separately at runtime. This setting does not
+   * apply to the Typeship-hosted endpoint.
+   */
+  access?: {
+    /**
+     * Exact issuer allowed to sign MCP connection tokens.
+     * Format: uri
+     */
+    issuer: string;
+    /**
+     * Canonical public URL of the self-hosted MCP endpoint that connection tokens must target.
+     * Format: uri
+     */
+    resource: string;
+    /**
+     * Public signing-key endpoint. Omit to discover it from the issuer.
+     * Format: uri
+     */
+    jwks_url?: string;
+    /** Minimum scopes required to connect to the self-hosted MCP server. */
+    scopes?: string[];
+  };
   /**
    * MCP tool shape. meta collapses per-operation tools into search_docs, read_docs, and execute so
    * large APIs don't flood an agent's context window. Auto considers the serialized tool schemas,
@@ -1651,12 +1995,50 @@ export interface McpBehavior {
    * match no operation are reported as generation warnings.
    */
   tool_descriptions?: Record<string, string>;
+  /**
+   * Exact name-or-ID resolver overrides keyed first by the target operationId or "METHOD /path",
+   * then by its wire argument name. A resolver names one read collection operation plus 1-4 item
+   * fields to match case-insensitively; false opts that argument out of strict inference.
+   */
+  reference_resolvers?: Record<string, Record<string, false
+    | {
+        /** OperationId, "METHOD /path", MCP tool name, or dotted resource.method of the list operation. */
+        via: string;
+        /** Item fields compared exactly and case-insensitively, such as name, slug, key, or email. */
+        match: string[];
+        /** Item field substituted into the requested argument. Defaults to id. */
+        id?: string;
+      }>>;
 }
 
 /** Response shape for McpBehavior. */
 export interface McpBehaviorRead {
   /** Stable official MCP registry name, independent of the server runtime. */
   registry_name?: string | null;
+  /**
+   * Authorization for callers connecting to a generated MCP server deployed over HTTP. The hosting
+   * application resolves upstream API credentials separately at runtime. This setting does not
+   * apply to the Typeship-hosted endpoint.
+   */
+  access?: {
+    /**
+     * Exact issuer allowed to sign MCP connection tokens.
+     * Format: uri
+     */
+    issuer: string;
+    /**
+     * Canonical public URL of the self-hosted MCP endpoint that connection tokens must target.
+     * Format: uri
+     */
+    resource: string;
+    /**
+     * Public signing-key endpoint. Omit to discover it from the issuer.
+     * Format: uri
+     */
+    jwks_url?: string;
+    /** Minimum scopes required to connect to the self-hosted MCP server. */
+    scopes?: string[];
+  };
   /**
    * MCP tool shape. meta collapses per-operation tools into search_docs, read_docs, and execute so
    * large APIs don't flood an agent's context window. Auto considers the serialized tool schemas,
@@ -1676,6 +2058,30 @@ export interface McpBehaviorRead {
    * match no operation are reported as generation warnings.
    */
   tool_descriptions?: Record<string, string>;
+  /**
+   * Exact name-or-ID resolver overrides keyed first by the target operationId or "METHOD /path",
+   * then by its wire argument name. A resolver names one read collection operation plus 1-4 item
+   * fields to match case-insensitively; false opts that argument out of strict inference.
+   */
+  reference_resolvers?: Record<string, Record<string, false | (string & {})
+    | {
+        /** OperationId, "METHOD /path", MCP tool name, or dotted resource.method of the list operation. */
+        via: string;
+        /** Item fields compared exactly and case-insensitively, such as name, slug, key, or email. */
+        match: string[];
+        /** Item field substituted into the requested argument. Defaults to id. */
+        id?: string;
+      }>>;
+}
+
+/** Generated README behavior. Part of Config. */
+export interface ReadmeBehavior {
+  /**
+   * operationId or "METHOD /path" to feature as the README's first API call. It must be present in
+   * the generated package and callable with no required input beyond path placeholders. Missing or
+   * unsuitable choices produce a warning and use the automatic example.
+   */
+  quickstart_operation?: string | null;
 }
 
 /**
@@ -1700,7 +2106,7 @@ export interface PackageBehavior {
 
 /**
  * Everything Typeship needs beyond the Definition, in one object: generation customization
- * (globals, retries, pagination) and how the generated tooling behaves (cli, mcp, package,
+ * (globals, retries, pagination, readme) and how the generated tooling behaves (cli, mcp, package,
  * docs_url). Plain configuration. Typeship never requires vendor extensions inside the Definition
  * itself. Stateless generation also accepts GraphQL settings here; stored projects keep those
  * settings on their Definition.
@@ -1719,8 +2125,10 @@ export interface Config {
    */
   pagination?: Record<string, PaginationRule | boolean>;
   graphql?: GraphqlSettings;
+  auth?: AuthenticationConfig;
   cli?: CliBehavior;
   mcp?: McpBehavior;
+  readme?: ReadmeBehavior;
   package?: PackageBehavior;
   /**
    * The API's documentation site. Read through its llms.txt by the generated CLI's docs command,
@@ -1750,8 +2158,10 @@ export interface ConfigRead {
    */
   pagination?: Record<string, PaginationRuleRead | boolean>;
   graphql?: GraphqlSettingsRead;
+  auth?: AuthenticationConfig;
   cli?: CliBehavior;
   mcp?: McpBehaviorRead;
+  readme?: ReadmeBehavior;
   package?: PackageBehavior;
   /**
    * The API's documentation site. Read through its llms.txt by the generated CLI's docs command,
@@ -1769,8 +2179,8 @@ export interface ConfigRead {
 /**
  * Shared generated-client and tooling behavior for a stored Project. Every Target inherits these
  * defaults. Target.config is merged over them for one Target; top-level values replace defaults
- * while cli, mcp, and package merge by field. GraphQL-only source settings live on the Project's
- * Definition and are rejected in both stored config scopes.
+ * while cli, mcp, auth, readme, and package merge by field. GraphQL-only source settings live on
+ * the Project's Definition and are rejected in both stored config scopes.
  */
 export interface ProjectConfig {
   /**
@@ -1785,8 +2195,10 @@ export interface ProjectConfig {
    * reported as generation warnings.
    */
   pagination?: Record<string, PaginationRule | boolean>;
+  auth?: AuthenticationConfig;
   cli?: CliBehavior;
   mcp?: McpBehavior;
+  readme?: ReadmeBehavior;
   package?: PackageBehavior;
   /**
    * The API's documentation site. Read through its llms.txt by the generated CLI's docs command,
@@ -1815,8 +2227,10 @@ export interface ProjectConfigRead {
    * reported as generation warnings.
    */
   pagination?: Record<string, PaginationRuleRead | boolean>;
+  auth?: AuthenticationConfig;
   cli?: CliBehavior;
   mcp?: McpBehaviorRead;
+  readme?: ReadmeBehavior;
   package?: PackageBehavior;
   /**
    * The API's documentation site. Read through its llms.txt by the generated CLI's docs command,
@@ -1831,6 +2245,42 @@ export interface ProjectConfigRead {
   docs_index_url?: string | null;
 }
 
+/**
+ * Target-specific generation and delivery overrides. Authentication may only select a Project-owned
+ * OAuth application. OAuth server metadata, applications, and identity policy remain Project-owned.
+ * Self-hosted MCP access may be overridden for a Target-specific deployment.
+ */
+export interface TargetConfig {
+  globals?: string[];
+  retries?: RetryTuning;
+  pagination?: Record<string, PaginationRule | boolean>;
+  auth?: TargetAuthenticationConfig;
+  cli?: CliBehavior;
+  mcp?: McpBehavior;
+  readme?: ReadmeBehavior;
+  package?: PackageBehavior;
+  /** Format: uri */
+  docs_url?: string | null;
+  /** Format: uri */
+  docs_index_url?: string | null;
+}
+
+/** Response shape for TargetConfig. */
+export interface TargetConfigRead {
+  globals?: string[];
+  retries?: RetryTuning;
+  pagination?: Record<string, PaginationRuleRead | boolean>;
+  auth?: TargetAuthenticationConfig;
+  cli?: CliBehavior;
+  mcp?: McpBehaviorRead;
+  readme?: ReadmeBehavior;
+  package?: PackageBehavior;
+  /** Format: uri */
+  docs_url?: string | null;
+  /** Format: uri */
+  docs_index_url?: string | null;
+}
+
 /** What a GraphQL schema cannot say about itself. Ignored for OpenAPI specs. */
 export interface GraphqlSettings {
   /**
@@ -1964,6 +2414,38 @@ export interface FileStub {
   bytes: number;
 }
 
+export const GenerationStatus = {
+  SUCCEEDED: "succeeded",
+  FAILED: "failed",
+} as const;
+export type GenerationStatus = (typeof GenerationStatus)[keyof typeof GenerationStatus];
+
+export const GenerationTrigger = {
+  MANUAL: "manual",
+  WEBHOOK: "webhook",
+  POLL: "poll",
+  PREVIEW: "preview",
+} as const;
+export type GenerationTrigger = (typeof GenerationTrigger)[keyof typeof GenerationTrigger];
+
+export interface GenerationProvenance {
+  /** Pinned generator contract edition. */
+  generator_edition: string;
+  /** Exact engine build identifier used for replay and support. */
+  engine_build: string;
+  /**
+   * Immutable effective Target configuration used by this run; source credentials are never
+   * included.
+   */
+  resolved_config: Record<string, unknown> | null;
+  config_hash: string | null;
+  /** Resolved generator and entitlement plan used to select the emitted public surface. */
+  surface_plan: Record<string, unknown> | null;
+  surface_plan_hash: string | null;
+  entitlement_cap: number | null;
+  package_version: string | null;
+}
+
 export interface Generation {
   id: GenerationId;
   object: "generation";
@@ -1975,29 +2457,13 @@ export interface Generation {
   files_index?: FileStub[];
   project_id: ProjectId;
   definition_revision_id: DefinitionRevisionId | null;
-  status: "succeeded" | "failed";
-  trigger: "manual" | "webhook" | "poll" | "preview";
+  status: GenerationStatus;
+  trigger: GenerationTrigger;
   /** Persisted Target identity. Null only for stateless generation. */
   target_id: TargetId | null;
   /** Resolved generator implementation; provenance rather than resource identity. */
   generator: GeneratorKind;
-  provenance: {
-    /** Pinned generator contract edition. */
-    generator_edition: string;
-    /** Exact engine build identifier used for replay and support. */
-    engine_build: string;
-    /**
-     * Immutable effective Target configuration used by this run; source credentials are never
-     * included.
-     */
-    resolved_config: Record<string, unknown> | null;
-    config_hash: string | null;
-    /** Resolved generator and entitlement plan used to select the emitted public surface. */
-    surface_plan: Record<string, unknown> | null;
-    surface_plan_hash: string | null;
-    entitlement_cap: number | null;
-    package_version: string | null;
-  };
+  provenance: GenerationProvenance;
   /** Null only for a failed or legacy generation that produced no metadata. */
   meta: GenerationMeta | null;
   warnings: string[];
@@ -2020,29 +2486,13 @@ export interface GenerationWrite {
   files_index?: FileStub[];
   project_id: ProjectId;
   definition_revision_id: DefinitionRevisionId | null;
-  status: "succeeded" | "failed";
-  trigger: "manual" | "webhook" | "poll" | "preview";
+  status: GenerationStatus;
+  trigger: GenerationTrigger;
   /** Persisted Target identity. Null only for stateless generation. */
   target_id: TargetId | null;
   /** Resolved generator implementation; provenance rather than resource identity. */
   generator: GeneratorKind;
-  provenance: {
-    /** Pinned generator contract edition. */
-    generator_edition: string;
-    /** Exact engine build identifier used for replay and support. */
-    engine_build: string;
-    /**
-     * Immutable effective Target configuration used by this run; source credentials are never
-     * included.
-     */
-    resolved_config: Record<string, unknown> | null;
-    config_hash: string | null;
-    /** Resolved generator and entitlement plan used to select the emitted public surface. */
-    surface_plan: Record<string, unknown> | null;
-    surface_plan_hash: string | null;
-    entitlement_cap: number | null;
-    package_version: string | null;
-  };
+  provenance: GenerationProvenance;
   /** Null only for a failed or legacy generation that produced no metadata. */
   meta: GenerationMeta | null;
   warnings: string[];
@@ -2066,29 +2516,13 @@ export interface GenerationRead {
   files_index?: FileStub[];
   project_id: ProjectId;
   definition_revision_id: DefinitionRevisionId | null;
-  status: ("succeeded" | "failed") | (string & {});
-  trigger: ("manual" | "webhook" | "poll" | "preview") | (string & {});
+  status: GenerationStatus | (string & {});
+  trigger: GenerationTrigger | (string & {});
   /** Persisted Target identity. Null only for stateless generation. */
   target_id: TargetId | null;
   /** Resolved generator implementation; provenance rather than resource identity. */
   generator: GeneratorKind | (string & {});
-  provenance: {
-    /** Pinned generator contract edition. */
-    generator_edition: string;
-    /** Exact engine build identifier used for replay and support. */
-    engine_build: string;
-    /**
-     * Immutable effective Target configuration used by this run; source credentials are never
-     * included.
-     */
-    resolved_config: Record<string, unknown> | null;
-    config_hash: string | null;
-    /** Resolved generator and entitlement plan used to select the emitted public surface. */
-    surface_plan: Record<string, unknown> | null;
-    surface_plan_hash: string | null;
-    entitlement_cap: number | null;
-    package_version: string | null;
-  };
+  provenance: GenerationProvenance;
   /** Null only for a failed or legacy generation that produced no metadata. */
   meta: GenerationMetaRead | null;
   warnings: string[];
@@ -2100,6 +2534,71 @@ export interface GenerationRead {
   request_id?: RequestId;
 }
 
+/**
+ * Generation metadata returned by collection endpoints. Generated file contents and file indexes
+ * are available only from retrieve and create operations.
+ */
+export interface GenerationSummary {
+  id: GenerationId;
+  object: "generation";
+  project_id: ProjectId;
+  definition_revision_id: DefinitionRevisionId | null;
+  status: GenerationStatus;
+  trigger: GenerationTrigger;
+  /** Persisted Target identity. Null only for stateless generation. */
+  target_id: TargetId | null;
+  /** Resolved generator implementation; provenance rather than resource identity. */
+  generator: GeneratorKind;
+  provenance: GenerationProvenance;
+  /** Null only for a failed or legacy generation that produced no metadata. */
+  meta: GenerationMeta | null;
+  warnings: string[];
+  error: string | null;
+  /** Format: date-time */
+  created_at: string;
+}
+
+/** Request shape for GenerationSummary. */
+export interface GenerationSummaryWrite {
+  id: GenerationId;
+  project_id: ProjectId;
+  definition_revision_id: DefinitionRevisionId | null;
+  status: GenerationStatus;
+  trigger: GenerationTrigger;
+  /** Persisted Target identity. Null only for stateless generation. */
+  target_id: TargetId | null;
+  /** Resolved generator implementation; provenance rather than resource identity. */
+  generator: GeneratorKind;
+  provenance: GenerationProvenance;
+  /** Null only for a failed or legacy generation that produced no metadata. */
+  meta: GenerationMeta | null;
+  warnings: string[];
+  error: string | null;
+  /** Format: date-time */
+  created_at: string;
+}
+
+/** Response shape for GenerationSummary. */
+export interface GenerationSummaryRead {
+  id: GenerationId;
+  object: "generation" | (string & {});
+  project_id: ProjectId;
+  definition_revision_id: DefinitionRevisionId | null;
+  status: GenerationStatus | (string & {});
+  trigger: GenerationTrigger | (string & {});
+  /** Persisted Target identity. Null only for stateless generation. */
+  target_id: TargetId | null;
+  /** Resolved generator implementation; provenance rather than resource identity. */
+  generator: GeneratorKind | (string & {});
+  provenance: GenerationProvenance;
+  /** Null only for a failed or legacy generation that produced no metadata. */
+  meta: GenerationMetaRead | null;
+  warnings: string[];
+  error: string | null;
+  /** Format: date-time */
+  created_at: string;
+}
+
 export type GenerationResponse = Generation & ResponseMetadata;
 
 /** Request shape for GenerationResponse. */
@@ -2124,20 +2623,24 @@ export interface GenerationFailureRead {
   error: string;
 }
 
+/**
+ * Metadata for each Target generation attempted by a Project run. Retrieve one Generation
+ * separately for generated files.
+ */
 export interface GenerationBatch {
-  data: Array<Generation | GenerationFailure>;
+  data: Array<GenerationSummary | GenerationFailure>;
   request_id: RequestId;
 }
 
 /** Request shape for GenerationBatch. */
 export interface GenerationBatchWrite {
-  data: Array<GenerationWrite | GenerationFailure>;
+  data: Array<GenerationSummaryWrite | GenerationFailure>;
   request_id: RequestId;
 }
 
 /** Response shape for GenerationBatch. */
 export interface GenerationBatchRead {
-  data: Array<GenerationRead | GenerationFailureRead>;
+  data: Array<GenerationSummaryRead | GenerationFailureRead>;
   request_id: RequestId;
 }
 
@@ -2306,7 +2809,7 @@ export interface ProjectListRead {
 
 export interface GenerationList {
   object: ListObject;
-  data: Generation[];
+  data: GenerationSummary[];
   /** Whether another page is available after this one. */
   has_more: boolean;
   /** Pass this value as cursor to retrieve the next page; null on the last page. */
@@ -2317,7 +2820,7 @@ export interface GenerationList {
 /** Request shape for GenerationList. */
 export interface GenerationListWrite {
   object: ListObject;
-  data: GenerationWrite[];
+  data: GenerationSummaryWrite[];
   /** Whether another page is available after this one. */
   has_more: boolean;
   /** Pass this value as cursor to retrieve the next page; null on the last page. */
@@ -2328,7 +2831,7 @@ export interface GenerationListWrite {
 /** Response shape for GenerationList. */
 export interface GenerationListRead {
   object: ListObject;
-  data: GenerationRead[];
+  data: GenerationSummaryRead[];
   /** Whether another page is available after this one. */
   has_more: boolean;
   /** Pass this value as cursor to retrieve the next page; null on the last page. */
@@ -2433,6 +2936,20 @@ export const ErrorCode = {
   FETCH_ERROR: "fetch_error",
   REPOSITORY_PROVIDER_UNSUPPORTED: "repository_provider_unsupported",
   EDITION_UNAVAILABLE: "edition_unavailable",
+  TARGET_BUSY: "target_busy",
+  INVALID_VERSION: "invalid_version",
+  STALE_RELEASE_REVISION: "stale_release_revision",
+  VERSION_OCCUPIED: "version_occupied",
+  VERSION_TOO_LOW: "version_too_low",
+  RELEASE_ANALYSIS_STALE: "release_analysis_stale",
+  TARGET_ALREADY_RELEASED: "target_already_released",
+  ADOPTION_UNVERIFIED: "adoption_unverified",
+  PUBLICATION_DISABLED: "publication_disabled",
+  PUBLICATION_NOT_RETRYABLE: "publication_not_retryable",
+  PUBLICATION_RECOVERY_UNAVAILABLE: "publication_recovery_unavailable",
+  PUBLICATION_DISPATCH_FAILED: "publication_dispatch_failed",
+  REPOSITORY_DISCONNECTED: "repository_disconnected",
+  REGENERATION_FAILED: "regeneration_failed",
   DELIVERY_CONFLICT: "delivery_conflict",
   RESOURCE_HAS_DEPENDENCIES: "resource_has_dependencies",
   PLAN_LIMIT_REACHED: "plan_limit_reached",