Merge remote-tracking branch 'origin/main' into feat/add-org-booking-tools

# Conflicts:
#	apps/mcp-server/README.md
#	apps/mcp-server/src/server-instructions.ts

Author: Udit-takkar

.agents/README.md

@@ -0,0 +1,17 @@
+# Companion Agent Documentation Index
+
+- **[../AGENTS.md](../AGENTS.md)** — main agent guide (repo areas, tooling, scope).
+- **[rules/](rules/)** — modular engineering rules.
+- **[skills/](skills/)** — agent skills (e.g. `chat-sdk`, synced via `skills-lock.json`).
+
+## Rules Index
+
+### API
+
+- [api-mcp-openapi-contract](rules/api-mcp-openapi-contract.md) — align `apps/mcp-server` tools with the Cal.com API v2 OpenAPI contract.
+
+### Reference
+
+- [reference-local-cal-api](rules/reference-local-cal-api.md) — how to locate the local `/cal` API v2 OpenAPI spec.
+
+See [rules/_sections.md](rules/_sections.md) for section definitions and [rules/README.md](rules/README.md) for the rule format.

.agents/rules/README.md

@@ -0,0 +1,55 @@
+# Companion Engineering Rules
+
+This directory contains modular, machine-readable engineering rules for the
+Companion monorepo. The scaffold mirrors the format used in
+[`calcom/cal`](https://github.com/calcom/cal), kept intentionally lean — rules are
+added as needs arise rather than copied wholesale.
+
+## Structure
+
+Rules are grouped by a section prefix, defined in `_sections.md`:
+
+| Prefix | Section | Impact |
+|--------|---------|--------|
+| `api-` | API / Contract | HIGH |
+| `testing-` | Testing | MEDIUM-HIGH |
+| `quality-` | Code Quality | MEDIUM |
+| `reference-` | Reference | LOW |
+
+## Files
+
+- `_sections.md` — defines sections, ordering, and impact levels.
+- `_template.md` — template for creating new rules.
+- `{section}-{rule-name}.md` — individual rule files.
+
+## Rule Format
+
+Each rule file uses YAML frontmatter followed by a clear explanation:
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: Optional description
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: LEVEL (optional description)**
+
+Brief explanation of the rule and why it matters, with concrete examples.
+```
+
+## Adding New Rules
+
+1. Copy `_template.md` to `{section}-{rule-name}.md`.
+2. Fill in the frontmatter (title, impact, tags).
+3. Write a clear explanation with incorrect/correct examples where useful.
+4. Add the rule to [`../README.md`](../README.md) under the right section.
+
+## Scope
+
+Keep rules narrowly scoped. The MCP/OpenAPI rules apply only to `apps/mcp-server`
+and other code that wraps Cal.com API v2 — they do not apply to `apps/chat`,
+`apps/mobile`, `apps/extension`, or `packages/cli`.

.agents/rules/_sections.md

@@ -0,0 +1,28 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. API / Contract (api)
+
+**Impact:** HIGH
+**Description:** Rules that keep MCP server tools and other API-v2-wrapping code
+aligned with the Cal.com Platform API v2 contract (OpenAPI).
+
+## 2. Testing (testing)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Test coverage and validation strategies, especially for request
+shapes and schema boundaries.
+
+## 3. Code Quality (quality)
+
+**Impact:** MEDIUM
+**Description:** Standards for maintainable, consistent code.
+
+## 4. Reference (reference)
+
+**Impact:** LOW
+**Description:** Reference guides for locating shared resources and local setup.

.agents/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "prevents API drift")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example();
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example();
+```
+
+Reference: [Link to documentation or resource](https://example.com)

.agents/rules/api-mcp-openapi-contract.md

@@ -0,0 +1,101 @@
+---
+title: Align MCP Server Tools with the Cal.com API v2 OpenAPI Contract
+impact: HIGH
+impactDescription: Prevents MCP tool schemas from drifting away from the API they wrap
+tags: api, openapi, mcp, mcp-server, zod, api-v2
+---
+
+# Align MCP Server Tools with the Cal.com API v2 OpenAPI Contract
+
+**Impact: HIGH (prevents MCP tool schemas from drifting away from the API they wrap)**
+
+`apps/mcp-server` is a Model Context Protocol server that wraps the
+[Cal.com Platform API v2](https://cal.com/docs/api-reference/v2). Every tool's
+Zod input schema is effectively a re-declaration of part of the API v2 contract.
+If the schema drifts from the real endpoint, the LLM sends requests the API
+rejects (or, worse, silently malformed ones). Keep the two in sync.
+
+**This rule applies only to `apps/mcp-server`** (and any other code that wraps
+API v2). It does not apply to `apps/chat`, `apps/mobile`, `apps/extension`, or
+`packages/cli`.
+
+## Before adding or changing a tool
+
+1. **Locate the OpenAPI spec.** Find `docs/api-reference/v2/openapi.json` from a
+   local `calcom/cal` checkout — see
+   [reference-local-cal-api](reference-local-cal-api.md) for the lookup order.
+2. **Read the exact contract** for the endpoint you wrap:
+   - HTTP path and method.
+   - Path params and query params.
+   - Request body schema (follow `$ref`s).
+   - Response schema (follow `$ref`s).
+   - Enums, `minimum`/`maximum`, `default`, and `required` fields.
+3. **Mirror those constraints in the Zod schema**, unless you intentionally
+   choose a stricter bound for safety (document why in a comment if non-obvious).
+
+## Mirror constraints in Zod
+
+Schemas live next to each tool in `apps/mcp-server/src/tools/**` and are exported
+as `<tool>Schema` objects. Encode the documented bounds directly:
+
+**Incorrect (loose schema that ignores the documented bounds):**
+
+```typescript
+export const getOrgMembershipsSchema = {
+  orgId: z.number().describe("Organization ID"),
+  take: z.number().optional(),
+  skip: z.number().optional(),
+};
+```
+
+**Correct (mirrors path/param types and the OpenAPI min/max + integer bounds):**
+
+```typescript
+export const getOrgMembershipsSchema = {
+  orgId: z.number().int().describe("Organization ID. Use get_me — never guess."),
+  take: z.number().int().min(1).max(250).optional().describe("Max results (1-250)"),
+  skip: z.number().int().min(0).optional().describe("Results to skip (offset, min 0)"),
+};
+```
+
+Match documented enums exactly (e.g. `z.enum(["MEMBER", "OWNER", "ADMIN"])`) and
+keep `.describe()` text accurate — the descriptions become the tool's parameter
+docs that the LLM reads.
+
+## Update discovery + metadata when behavior changes
+
+When a change affects what a tool can do or how it is discovered, update all of:
+
+- Tool annotations (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`,
+  `openWorldHint`) so they still reflect the operation.
+- The tool tables in `apps/mcp-server/README.md`.
+- Server instructions in `apps/mcp-server/src/server-instructions.ts`.
+
+## Add tests for request shape and validation boundaries
+
+Co-located `*.test.ts` files already assert OpenAPI bounds — extend them. Cover
+the schema edges so future edits can't silently loosen them:
+
+```typescript
+it("enforces OpenAPI pagination bounds", () => {
+  expect(getOrgMembershipsSchema.take.safeParse(0).success).toBe(false);
+  expect(getOrgMembershipsSchema.take.safeParse(250).success).toBe(true);
+  expect(getOrgMembershipsSchema.take.safeParse(251).success).toBe(false);
+  expect(getOrgMembershipsSchema.skip.safeParse(-1).success).toBe(false);
+});
+```
+
+Run them with `bun --filter @calcom/mcp-server test` (or `vitest run` inside
+`apps/mcp-server`).
+
+## Optional: local stdio smoke
+
+For high-confidence MCP PRs, run a local stdio smoke against API v2 when a local
+API key/DB is available (see `apps/mcp-server/README.md` for stdio + `CAL_API_KEY`
+setup) to confirm the tool actually round-trips against the live contract.
+
+## Do not hand-edit the spec
+
+`docs/api-reference/v2/openapi.json` is generated in `calcom/cal`. If the spec is
+wrong, fix/regenerate it in `/cal` separately — never hand-edit that JSON from
+Companion.

.agents/rules/reference-local-cal-api.md

@@ -0,0 +1,44 @@
+---
+title: Locating the Cal.com API v2 OpenAPI Spec
+impact: LOW
+impactDescription: Reference guide for finding the source-of-truth API v2 contract
+tags: reference, api, openapi, mcp
+---
+
+# Locating the Cal.com API v2 OpenAPI Spec
+
+`apps/mcp-server` wraps the Cal.com Platform API v2. The source of truth for the
+API contract is the OpenAPI document that lives in the **`calcom/cal`** repo at:
+
+```
+docs/api-reference/v2/openapi.json
+```
+
+It is auto-generated from the API v2 NestJS decorators and is large (~1MB+).
+Companion does **not** vendor a copy of it, so agents resolve it from a local
+checkout of `calcom/cal`.
+
+## How to find it
+
+Look for the file in this order and use the first that exists:
+
+1. `$CALCOM_CAL_REPO/docs/api-reference/v2/openapi.json`
+   — set the `CALCOM_CAL_REPO` env var to your local `calcom/cal` checkout.
+2. `../cal/docs/api-reference/v2/openapi.json`
+   — the common layout where `companion` and `cal` are sibling directories.
+
+```bash
+# Resolve the spec path (first match wins)
+SPEC="${CALCOM_CAL_REPO:+$CALCOM_CAL_REPO/docs/api-reference/v2/openapi.json}"
+[ -f "$SPEC" ] || SPEC="../cal/docs/api-reference/v2/openapi.json"
+[ -f "$SPEC" ] && echo "Using $SPEC" || echo "openapi.json not found — clone calcom/cal"
+```
+
+If neither path exists, ask for a `calcom/cal` checkout (or its location) rather
+than guessing the contract.
+
+## Do not hand-edit the spec
+
+`openapi.json` is generated. If the spec itself is wrong, fix or regenerate it in
+the `calcom/cal` repo (by changing the API v2 decorators and rebooting the API),
+**not** by editing the JSON. Never hand-edit `cal`'s `openapi.json` from Companion.

AGENTS.md

@@ -0,0 +1,49 @@
+# Companion Development Guide for AI Agents
+
+Companion is a Bun-based monorepo for Cal.com's mobile app, browser extension, and
+AI-driven interfaces (chat gateway, MCP server, CLI). This file is the main entry
+point for AI agents working in this repo.
+
+## Repo Areas
+
+| Path | What it is |
+|------|------------|
+| `apps/mobile` | Expo (React Native) mobile app for iOS/Android. |
+| `apps/extension` | WXT-based browser extension. |
+| `apps/chat` | Multi-protocol bot gateway (Slack/Telegram) with an AI agent. |
+| `apps/mcp-server` | Model Context Protocol server that wraps the Cal.com Platform API v2. |
+| `packages/cli` | Command-line interface for Cal.com API interactions. |
+
+## Tooling
+
+- **Runtime / package manager**: Bun (workspaces in `apps/*`, `packages/*`).
+- **Lint & format**: Biome (`bun run lint`, `bun run format`, `bun run check`).
+- **Type check**: `bun run typecheck`.
+- **Git hooks**: Husky + lint-staged run `biome format --write` on staged files.
+
+Note: Biome's `files.includes` in `biome.json` only covers `js/jsx/ts/tsx/json`,
+so `bun run format` / `format:check` do **not** touch Markdown. Validate docs with
+`git diff --check` (whitespace) and a manual read.
+
+## When Touching MCP Tools
+
+Before adding or changing tools in `apps/mcp-server` that wrap Cal.com API v2,
+follow [.agents/rules/api-mcp-openapi-contract.md](.agents/rules/api-mcp-openapi-contract.md):
+mirror the API v2 OpenAPI contract (path/method, params, request/response shapes,
+enums, bounds, defaults, required fields) in the MCP Zod schemas, and update tool
+metadata, README tables, server instructions, and tests when behavior changes.
+
+To locate the OpenAPI spec, see
+[.agents/rules/reference-local-cal-api.md](.agents/rules/reference-local-cal-api.md).
+
+## Scope of These Rules
+
+The `.agents/rules` here are intentionally narrow. The MCP/OpenAPI rules apply
+**only** to `apps/mcp-server` (and other API-v2-wrapping code). They do **not**
+apply to unrelated `apps/chat`, `apps/mobile`, `apps/extension`, or `packages/cli`
+work — don't burden those areas with MCP-specific constraints.
+
+## Extended Documentation
+
+- **[.agents/README.md](.agents/README.md)** — agent docs index and rules list.
+- **[.agents/rules/](.agents/rules/)** — modular engineering rules.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

apps/mcp-server/README.md

@@ -4,7 +4,7 @@ A **Model Context Protocol (MCP)** server that wraps the [Cal.com Platform API v
 
 ## Features
 
-- **44 tools** covering Bookings, Event Types, Schedules, Availability, Calendars, Conferencing, Routing Forms, Organizations, and User Profile (each with MCP tool annotations: `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
+- **52 tools** covering Bookings, Event Types, Schedules, Availability, Calendars, Conferencing, Routing Forms, Organizations, Teams, and User Profile (each with MCP tool annotations: `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
 - **Dual transport** — stdio for local dev tooling, StreamableHTTP for remote/production
 - **Dual auth** — API key for stdio (local dev), OAuth 2.1 Authorization Code + PKCE for HTTP (production)
 - **Per-user token storage** — encrypted at rest with AES-256-GCM in SQLite
@@ -179,7 +179,7 @@ The server acts as an intermediary: it issues its own access tokens to MCP clien
 - Expired tokens are cleaned up automatically every 5 minutes
 - In-process rate limiting on all OAuth endpoints (token bucket per IP, configurable via `RATE_LIMIT_WINDOW_MS` / `RATE_LIMIT_MAX`)
 
-## Tools (44)
+## Tools (52)
 
 Each tool exposes MCP [tool annotations](https://modelcontextprotocol.io/specification/draft/server/tools#tool-annotations) — a human-readable `title` plus behaviour hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so MCP clients can render them appropriately and apply safety policies.
 
@@ -272,18 +272,34 @@ Each tool exposes MCP [tool annotations](https://modelcontextprotocol.io/specifi
 ### Organizations: Memberships (5)
 | Tool | Title | Hint | Description |
 |---|---|---|---|
-| `get_org_memberships` | List Org Memberships | Read | Get all organization memberships |
+| `get_org_memberships` | List Org Memberships | Read | Get all organization memberships; supports `take`/`skip` pagination (`take` max 250) |
 | `create_org_membership` | Create Org Membership | Create | Create an organization membership |
 | `get_org_membership` | Get Org Membership | Read | Get an organization membership |
 | `update_org_membership` | Update Org Membership | Update | Update an organization membership (role, accepted, impersonation) |
 | `delete_org_membership` | Delete Org Membership | Destructive | Delete an organization membership |
 
+### Organizations: Teams (2)
+| Tool | Title | Hint | Description |
+|---|---|---|---|
+| `get_org_teams` | List All Org Teams | Read | List all teams in an organization; requires org admin access; supports `take`/`skip` pagination (`take` max 250) |
+| `get_my_teams` | List My Teams | Read | List teams the authenticated user belongs to; supports `take`/`skip` pagination (`take` max 250) |
+
 ### Organizations: Routing Forms (2)
 | Tool | Title | Hint | Description |
 |---|---|---|---|
 | `get_org_routing_forms` | List Org Routing Forms | Read | Get organization routing forms |
 | `get_org_routing_form_responses` | List Org Routing Form Responses | Read | Get routing form responses |
 
+### Teams: Memberships (6)
+| Tool | Title | Hint | Description |
+|---|---|---|---|
+| `get_team_memberships` | List Team Memberships | Read | Get all team memberships; supports `take`/`skip` pagination (`take` max 250) and email filtering |
+| `get_team_membership` | Get Team Membership | Read | Get a team membership |
+| `create_team_membership` | Create Team Membership | Create | Create a team membership (role defaults to `MEMBER`) |
+| `update_team_membership` | Update Team Membership | Update | Update a team membership (accepted, role, impersonation) |
+| `delete_team_membership` | Delete Team Membership | Destructive | Delete a team membership |
+| `create_team_invite` | Create Team Invite | Create | Generate a team invite link |
+
 ### API Version Notes
 
 - Default API version: `2024-08-13`