@company-semantics/contracts 0.122.0 → 0.123.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.122.0",
+  "version": "0.123.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -56,6 +56,10 @@
       "types": "./src/org/index.ts",
       "default": "./src/org/index.ts"
     },
+    "./content": {
+      "types": "./src/content/index.ts",
+      "default": "./src/content/index.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",

package/src/api/generated.ts

@@ -356,12 +356,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * Get execution timeline
-         * @description Returns the timeline for an execution.
-         *     Timeline is a read-only projection over audit data.
-         *     Returns 404 for both non-existent and non-visible executions (prevents existence leaks).
-         */
+        /** Get timeline events for an execution */
         get: operations["getExecutionTimeline"];
         put?: never;
         post?: never;
@@ -378,11 +373,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * Get execution summary
-         * @description Returns the ExecutionSummary projection for an execution.
-         *     Summary is a UI-facing projection derived from audit records.
-         */
+        /** Get execution summary projection */
         get: operations["getExecutionSummary"];
         put?: never;
         post?: never;
@@ -399,16 +390,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * List executions
-         * @description Lists execution summaries with optional filtering.
-         */
+        /** List executions with cursor pagination */
         get: operations["listExecutions"];
         put?: never;
-        /**
-         * Start a new execution
-         * @description Start a new execution for an integration action.
-         */
+        /** Start a new execution */
         post: operations["startExecution"];
         delete?: never;
         options?: never;
@@ -423,11 +408,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * Get execution explanation
-         * @description Returns the deterministic explanation for an execution.
-         *     Explanation is generated from audit records, NOT from LLM.
-         */
+        /** Get deterministic explanation for an execution */
         get: operations["getExplanation"];
         put?: never;
         post?: never;
@@ -446,12 +427,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /**
-         * Undo a completed execution
-         * @description Undoes a completed execution within its undo window.
-         *     The caller must be the same user who initiated the execution.
-         *     Idempotent: if undo was already performed, returns the existing result.
-         */
+        /** Undo a completed execution within its undo window */
         post: operations["undoExecution"];
         delete?: never;
         options?: never;
@@ -468,11 +444,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /**
-         * Confirm a pending execution
-         * @description Confirms a pending execution. Serialized via advisory lock.
-         *     The caller must be the same user who initiated the execution.
-         */
+        /** Confirm pending execution */
         post: operations["confirmExecution"];
         delete?: never;
         options?: never;
@@ -489,11 +461,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /**
-         * Reject a pending execution
-         * @description Rejects a pending execution. Serialized via advisory lock.
-         *     The caller must be the same user who initiated the execution.
-         */
+        /** Reject pending execution */
         post: operations["rejectExecution"];
         delete?: never;
         options?: never;
@@ -508,11 +476,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * Get timeline UI events
-         * @description Returns timeline events in UI projection format.
-         *     This is the user-facing timeline with derived labels and icons.
-         */
+        /** Get timeline events in UI projection format */
         get: operations["getTimelineUI"];
         put?: never;
         post?: never;
@@ -2504,11 +2468,9 @@ export interface components {
             status: "executing" | "blocked_pending_approval" | "already_confirmed" | "awaiting_approval";
             code?: string;
             executionId?: string;
-            /** @description ExecutionResultData when execution completes inline */
-            result?: Record<string, never>;
         };
         RejectExecutionResponse: {
-            /** @enum {string} */
+            /** @constant */
             status: "cancelled";
         };
         ExecutionSummary: {
@@ -2529,21 +2491,30 @@ export interface components {
             summary: components["schemas"]["ExecutionSummary"];
         };
         ExecutionListResponse: {
-            executions: components["schemas"]["ExecutionSummary"][];
-            /** @description Cursor for next page, null if no more results */
+            executions: {
+                /** Format: uuid */
+                executionId: string;
+                kind: string;
+                /** @enum {string} */
+                status: "pending" | "succeeded" | "failed";
+                /** Format: date-time */
+                decidedAt: string;
+                /** Format: date-time */
+                completedAt?: string;
+                target: {
+                    type: string;
+                };
+            }[];
             nextCursor?: string | null;
-            /** @description Whether more results are available */
-            hasMore: boolean;
+            hasMore?: boolean;
         };
         ExecutionStartRequest: {
             kind: string;
             target: {
-                /** @enum {string} */
-                type: "slack";
+                type: string;
                 workspaceId?: string;
             };
             connectionId?: string;
-            /** Format: uri */
             returnUrl?: string;
         };
         ExecutionStartResponse: {
@@ -3565,6 +3536,28 @@ export interface components {
         PreviewTransferRequest: {
             token: string;
         };
+        ExecutionTimelineResponse: {
+            events: {
+                eventId: string;
+                /** Format: uuid */
+                executionId: string;
+                timestamp: string;
+                createdAt: string;
+                kind: string;
+                summary: string;
+                details?: {
+                    [key: string]: unknown;
+                };
+                relatedIds?: {
+                    decisionId?: string;
+                    artifactId?: string;
+                    rollbackId?: string;
+                    provenanceIds?: string[];
+                };
+                /** @enum {string} */
+                visibilityLevel: "system" | "oversight" | "org_admin" | "user";
+            }[];
+        };
     };
     responses: never;
     parameters: never;
@@ -4038,39 +4031,18 @@ export interface operations {
         parameters: {
             query?: never;
             header?: never;
-            path: {
-                /** @description Execution ID (UUID v4) */
-                executionId: string;
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
         responses: {
-            /** @description Timeline events for the execution */
+            /** @description Execution timeline events */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["TimelineResponse"];
-                };
-            };
-            /** @description Invalid execution ID format */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Execution not found or not visible */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
+                    "application/json": components["schemas"]["ExecutionTimelineResponse"];
                 };
             };
         };
@@ -4079,10 +4051,7 @@ export interface operations {
         parameters: {
             query?: never;
             header?: never;
-            path: {
-                /** @description Execution ID (UUID v4) */
-                executionId: string;
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
@@ -4092,44 +4061,18 @@ export interface operations {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": components["schemas"]["ExecutionSummaryResponse"];
-                };
-            };
-            /** @description Invalid execution ID format */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Execution not found or not visible */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
+                content?: never;
             };
         };
     };
     listExecutions: {
         parameters: {
             query?: {
-                /** @description Filter by ExecutionKind */
-                kind?: string;
-                /** @description Filter by target type */
-                targetType?: string;
-                /** @description Max results (default 100) */
-                limit?: number;
-                /** @description Cursor for pagination */
                 cursor?: string;
-                /** @description Start of date range filter */
+                limit?: number;
+                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup";
+                targetType?: string;
                 periodStart?: string;
-                /** @description End of date range filter */
                 periodEnd?: string;
             };
             header?: never;
@@ -4138,7 +4081,7 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description List of execution summaries */
+            /** @description Paginated execution list */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -4147,15 +4090,6 @@ export interface operations {
                     "application/json": components["schemas"]["ExecutionListResponse"];
                 };
             };
-            /** @description Invalid kind parameter */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     startExecution: {
@@ -4176,27 +4110,7 @@ export interface operations {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": components["schemas"]["ExecutionStartResponse"];
-                };
-            };
-            /** @description Invalid execution kind or missing required fields */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description User does not have required admin role */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
+                content?: never;
             };
         };
     };
@@ -4204,10 +4118,7 @@ export interface operations {
         parameters: {
             query?: never;
             header?: never;
-            path: {
-                /** @description Execution ID (UUID v4) */
-                executionId: string;
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
@@ -4217,36 +4128,7 @@ export interface operations {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": components["schemas"]["ExplanationResponse"];
-                };
-            };
-            /** @description Invalid execution ID format */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Execution not found or not visible */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Explanation service not available */
-            501: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
+                content?: never;
             };
         };
     };
@@ -4254,10 +4136,7 @@ export interface operations {
         parameters: {
             query?: never;
             header?: never;
-            path: {
-                /** @description Execution ID (UUID v4) */
-                executionId: string;
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
@@ -4267,45 +4146,7 @@ export interface operations {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": components["schemas"]["UndoResultData"];
-                };
-            };
-            /** @description Invalid execution ID format or execution not in undoable state */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Insufficient permissions (not the initiating user) */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ExecutionLifecycleError"];
-                };
-            };
-            /** @description Execution not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Execution in wrong state (e.g. undo window expired) */
-            409: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ExecutionLifecycleError"];
-                };
+                content?: never;
             };
         };
     };
@@ -4313,15 +4154,12 @@ export interface operations {
         parameters: {
             query?: never;
             header?: never;
-            path: {
-                /** @description Execution ID (UUID v4) */
-                executionId: string;
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
         responses: {
-            /** @description Confirmation result */
+            /** @description Execution confirmed */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -4330,66 +4168,18 @@ export interface operations {
                     "application/json": components["schemas"]["ConfirmExecutionResponse"];
                 };
             };
-            /** @description Invalid execution ID format */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Insufficient permissions (not the initiating user) */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ExecutionLifecycleError"];
-                };
-            };
-            /** @description Execution not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Execution not in pending_confirmation state */
-            409: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ExecutionLifecycleError"];
-                };
-            };
-            /** @description Confirmation has expired */
-            410: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ExecutionLifecycleError"];
-                };
-            };
         };
     };
     rejectExecution: {
         parameters: {
             query?: never;
             header?: never;
-            path: {
-                /** @description Execution ID (UUID v4) */
-                executionId: string;
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
         responses: {
-            /** @description Rejection result */
+            /** @description Execution rejected */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -4398,55 +4188,15 @@ export interface operations {
                     "application/json": components["schemas"]["RejectExecutionResponse"];
                 };
             };
-            /** @description Invalid execution ID format */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Insufficient permissions (not the initiating user) */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ExecutionLifecycleError"];
-                };
-            };
-            /** @description Execution not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Execution not in pending_confirmation state */
-            409: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ExecutionLifecycleError"];
-                };
-            };
         };
     };
     getTimelineUI: {
         parameters: {
             query?: {
-                /** @description Filter by ExecutionKind */
-                kind?: string;
-                /** @description Filter by kind prefix */
-                kindPrefix?: string;
-                /** @description Max results (default 100) */
                 limit?: number;
-                /** @description Pagination offset (default 0) */
                 offset?: number;
+                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup";
+                kindPrefix?: string;
             };
             header?: never;
             path?: never;
@@ -4454,23 +4204,12 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Timeline UI events */
+            /** @description UI timeline events */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": components["schemas"]["TimelineUIResponse"];
-                };
-            };
-            /** @description Invalid kind parameter */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
+                content?: never;
             };
         };
     };

package/src/content/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Content Domain Barrel
+ *
+ * Re-exports content response schemas for company-md, teams, departments, and drive.
+ * Import from '@company-semantics/contracts/content'.
+ */
+
+// Company.md response schemas (PRD-00448)
+export {
+  CompanyMdListResponseSchema,
+  CompanyMdDocResponseSchema,
+  CompanyMdShareResponseSchema,
+  CompanyMdContextBankResponseSchema,
+  CompanyMdSettingsResponseSchema,
+} from './schemas';
+export type {
+  CompanyMdListResponse,
+  CompanyMdDocResponse,
+  CompanyMdShareResponse,
+  CompanyMdContextBankResponse,
+  CompanyMdSettingsResponse,
+} from './schemas';
+
+// Team response schemas (PRD-00448)
+export { TeamListResponseSchema, TeamResponseSchema } from './schemas';
+export type { TeamListResponse, TeamResponse } from './schemas';
+
+// Department response schemas (PRD-00448)
+export { DepartmentListResponseSchema, DepartmentResponseSchema } from './schemas';
+export type { DepartmentListResponse, DepartmentResponse } from './schemas';
+
+// Drive response schemas (PRD-00448)
+export { DriveFileListResponseSchema, DriveFileContentResponseSchema } from './schemas';
+export type { DriveFileListResponse, DriveFileContentResponse } from './schemas';

package/src/content/schemas.ts

@@ -0,0 +1,286 @@
+/**
+ * Content Domain Response Schemas
+ *
+ * Zod response schemas for content and org structure endpoints.
+ * Canonical location for runtime validation of company-md, team,
+ * department, and drive API responses.
+ *
+ * Covers:
+ *  - company-md.ts        (GET /api/company-md/tree, GET /api/company-md/docs/:slug, etc.)
+ *  - company-md-sharing.ts (GET /api/company-md/docs/:slug/sharing)
+ *  - teams.ts             (GET /api/teams, GET /api/teams/:teamId, etc.)
+ *  - departments.ts       (GET /api/departments, GET /api/departments/:id, etc.)
+ *  - drive.ts             (GET /api/drive/files, GET /api/drive/files/recent, etc.)
+ */
+import { z } from 'zod';
+import { CursorPageSchema } from '../api/primitives';
+
+// ---------------------------------------------------------------------------
+// Company.md Sub-schemas
+// ---------------------------------------------------------------------------
+
+const CompanyMdOwningTeamSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+const CompanyMdPersonSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+const CompanyMdSourceSchema = z.object({
+  label: z.string(),
+  sourceType: z.enum(['meeting', 'document', 'conversation', 'manual']),
+  referencedAt: z.string(),
+});
+
+const CompanyMdDependencySchema = z.object({
+  targetSlug: z.string(),
+  description: z.string(),
+});
+
+const CompanyMdTreeNodeSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  level: z.enum(['root', 'department', 'team', 'context']),
+  parentId: z.string().nullable(),
+  department: z.string().nullable(),
+  departmentId: z.string().nullable(),
+  visibility: z.enum(['public', 'private']),
+  owningTeam: CompanyMdOwningTeamSchema.nullable(),
+  type: z.enum(['company', 'department', 'team', 'cross_team', 'doc', 'goal', 'source', 'map', 'context_bank']),
+  canEdit: z.boolean(),
+  memberCount: z.number().int(),
+  description: z.string().optional(),
+  departmentIds: z.array(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Company.md HTTP Response Schemas
+// ---------------------------------------------------------------------------
+
+/** Response for GET /api/company-md/tree */
+export const CompanyMdListResponseSchema = CursorPageSchema(CompanyMdTreeNodeSchema);
+
+/** Response for GET /api/company-md/docs/:slug */
+export const CompanyMdDocResponseSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  level: z.enum(['root', 'department', 'team', 'context']),
+  department: z.string().nullable(),
+  departmentId: z.string().nullable(),
+  content: z.string(),
+  visibility: z.enum(['public', 'private']),
+  parentId: z.string().nullable(),
+  owningTeam: CompanyMdOwningTeamSchema.nullable(),
+  owner: CompanyMdPersonSchema.nullable(),
+  coOwners: z.array(CompanyMdPersonSchema),
+  canEdit: z.boolean(),
+  inheritsFrom: z.string().nullable(),
+  sources: z.array(CompanyMdSourceSchema),
+  dependencies: z.array(CompanyMdDependencySchema),
+  members: z.array(CompanyMdPersonSchema),
+  extractionStatus: z.enum(['pending', 'extracting', 'complete', 'failed']),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+// ---------------------------------------------------------------------------
+// Company.md Sharing Sub-schemas
+// ---------------------------------------------------------------------------
+
+const AclEntrySchema = z.object({
+  principalType: z.enum(['user', 'team']),
+  principalId: z.string(),
+  principalName: z.string(),
+  accessLevel: z.enum(['viewer', 'commenter', 'editor']),
+  grantedBy: z.object({ id: z.string(), name: z.string() }).nullable(),
+  grantedAt: z.string(),
+});
+
+const AccessReasonSchema = z.object({
+  source: z.enum(['org_rbac', 'sharing_policy', 'team_baseline', 'acl_grant', 'doc_ownership']),
+  detail: z.string(),
+});
+
+const EffectiveAccessSchema = z.object({
+  level: z.enum(['none', 'viewer', 'commenter', 'editor']),
+  reasons: z.array(AccessReasonSchema),
+  canShare: z.boolean(),
+});
+
+/** Response for GET /api/company-md/docs/:slug/sharing */
+export const CompanyMdShareResponseSchema = z.object({
+  sharingPolicy: z.enum(['restricted', 'org_read', 'org_comment', 'org_edit']),
+  acl: z.array(AclEntrySchema),
+  effectiveAccess: EffectiveAccessSchema,
+});
+
+// ---------------------------------------------------------------------------
+// Company.md Context Bank + Settings Response Schemas
+// ---------------------------------------------------------------------------
+
+const CompanyMdContextBankItemSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  visibility: z.enum(['public', 'private']),
+  updatedAt: z.string(),
+});
+
+/** Response for GET /api/company-md/docs/:slug/context-bank */
+export const CompanyMdContextBankResponseSchema = z.object({
+  items: z.array(CompanyMdContextBankItemSchema),
+});
+
+const CompanyMdLevelLabelsSchema = z.object({
+  root: z.string(),
+  department: z.string(),
+  team: z.string(),
+});
+
+/** Response for GET /api/company-md/settings */
+export const CompanyMdSettingsResponseSchema = z.object({
+  levelLabels: CompanyMdLevelLabelsSchema,
+});
+
+// ---------------------------------------------------------------------------
+// Team Sub-schemas
+// ---------------------------------------------------------------------------
+
+const TeamMemberSchema = z.object({
+  userId: z.string(),
+  name: z.string(),
+  email: z.string(),
+  role: z.enum(['member', 'manager', 'owner']),
+  joinedAt: z.string(),
+});
+
+const TeamSummarySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().nullable(),
+  memberCount: z.number().int(),
+  scope: z.enum(['department', 'cross_department', 'org']),
+  department: z.object({ id: z.string(), name: z.string(), slug: z.string() }).nullable(),
+  homeDepartment: z.object({ id: z.string(), name: z.string(), slug: z.string() }).nullable(),
+});
+
+// ---------------------------------------------------------------------------
+// Team HTTP Response Schemas
+// ---------------------------------------------------------------------------
+
+/** Response for GET /api/teams */
+export const TeamListResponseSchema = z.object({
+  teams: z.array(TeamSummarySchema),
+});
+
+/** Response for GET /api/teams/:teamId */
+export const TeamResponseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().nullable(),
+  syncMode: z.enum(['manual_only', 'synced_readonly', 'synced_with_overrides']),
+  members: z.array(TeamMemberSchema),
+});
+
+// ---------------------------------------------------------------------------
+// Department Sub-schemas
+// ---------------------------------------------------------------------------
+
+const DepartmentMemberSchema = z.object({
+  userId: z.string(),
+  name: z.string(),
+  email: z.string(),
+  role: z.enum(['member', 'manager', 'owner']),
+  joinedAt: z.string(),
+});
+
+const DepartmentSummarySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().nullable(),
+  memberCount: z.number().int(),
+  position: z.number().int(),
+});
+
+// ---------------------------------------------------------------------------
+// Department HTTP Response Schemas
+// ---------------------------------------------------------------------------
+
+/** Response for GET /api/departments */
+export const DepartmentListResponseSchema = z.object({
+  departments: z.array(DepartmentSummarySchema),
+});
+
+/** Response for GET /api/departments/:id */
+export const DepartmentResponseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().nullable(),
+  position: z.number().int(),
+  syncMode: z.enum(['manual_only', 'scim', 'hris']),
+  memberCount: z.number().int(),
+  members: z.array(DepartmentMemberSchema),
+});
+
+// ---------------------------------------------------------------------------
+// Drive Sub-schemas
+// ---------------------------------------------------------------------------
+
+const DriveFileOwnerSchema = z.object({
+  displayName: z.string().optional(),
+  emailAddress: z.string().optional(),
+});
+
+const DriveFileSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  mimeType: z.string(),
+  createdTime: z.string().optional(),
+  modifiedTime: z.string().optional(),
+  owners: z.array(DriveFileOwnerSchema).optional(),
+  webViewLink: z.string().optional(),
+  iconLink: z.string().optional(),
+  size: z.string().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Drive HTTP Response Schemas
+// ---------------------------------------------------------------------------
+
+/** Response for GET /api/drive/files and GET /api/drive/files/recent */
+export const DriveFileListResponseSchema = z.object({
+  files: z.array(DriveFileSchema),
+  nextPageToken: z.string().optional(),
+});
+
+/** Response for GET /api/drive/files/:fileId/content */
+export const DriveFileContentResponseSchema = z.object({
+  content: z.string(),
+  exportedAs: z.string(),
+  truncated: z.boolean(),
+});
+
+// ---------------------------------------------------------------------------
+// Inferred Types
+// ---------------------------------------------------------------------------
+
+export type CompanyMdListResponse = z.infer<typeof CompanyMdListResponseSchema>;
+export type CompanyMdDocResponse = z.infer<typeof CompanyMdDocResponseSchema>;
+export type CompanyMdShareResponse = z.infer<typeof CompanyMdShareResponseSchema>;
+export type CompanyMdContextBankResponse = z.infer<typeof CompanyMdContextBankResponseSchema>;
+export type CompanyMdSettingsResponse = z.infer<typeof CompanyMdSettingsResponseSchema>;
+export type TeamListResponse = z.infer<typeof TeamListResponseSchema>;
+export type TeamResponse = z.infer<typeof TeamResponseSchema>;
+export type DepartmentListResponse = z.infer<typeof DepartmentListResponseSchema>;
+export type DepartmentResponse = z.infer<typeof DepartmentResponseSchema>;
+export type DriveFileListResponse = z.infer<typeof DriveFileListResponseSchema>;
+export type DriveFileContentResponse = z.infer<typeof DriveFileContentResponseSchema>;