diff --git a/.changeset/deprecate-sdk-init.md b/.changeset/deprecate-sdk-init.md
new file mode 100644
index 000000000..148c4a5fc
--- /dev/null
+++ b/.changeset/deprecate-sdk-init.md
@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-cli": patch
+---
+
+Deprecate `squad init --sdk` ahead of its removal in v2 while retaining compatibility for existing `squad.config.ts` projects.
diff --git a/README.md b/README.md
index 01a47d0a8..70c710010 100644
--- a/README.md
+++ b/README.md
@@ -460,26 +460,11 @@ When agents finish, the coordinator records follow-up work and leaves a breadcru
 
 **Commit this folder.** Your team persists. Names persist. Anyone who clones gets the team — with the same cast.
 
-### SDK-First Mode (New in Phase 1)
+### SDK-First Mode (Deprecated)
 
-> ⚠️ **Experimental.** SDK-first mode is under active development and has known bugs. Use markdown-first (the default) for production teams.
+> ⚠️ **Deprecated.** `squad init --sdk` will be removed in v2. Use the default markdown-first `squad init` flow for new teams.
 
-Prefer TypeScript? You can define your team in code instead of markdown. Create a `squad.config.ts` with builder functions, run `squad build`, and the `.squad/` files are generated automatically.
-
-```typescript
-// squad.config.ts
-import { defineSquad, defineTeam, defineAgent } from '@bradygaster/squad-sdk';
-
-export default defineSquad({
-  team: defineTeam({ name: 'Platform Squad', members: ['@edie', '@mcmanus'] }),
-  agents: [
-    defineAgent({ name: 'edie', role: 'TypeScript Engineer', model: 'claude-sonnet-5' }),
-    defineAgent({ name: 'mcmanus', role: 'DevRel', model: 'claude-haiku-4.5' }),
-  ],
-});
-```
-
-Run `squad build` to generate all the markdown. See the [SDK-First Mode Guide](docs/src/content/docs/sdk-first-mode.md) for full documentation.
+Existing projects with a `squad.config.ts` can continue running `squad build` during the transition. See the [legacy SDK-First Mode Guide](docs/src/content/docs/sdk-first-mode.md) for compatibility information.
 
 ---
 
diff --git a/README.zh.md b/README.zh.md
index e629eef2b..97168c0eb 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -262,26 +262,11 @@ Squad 不按人类的时间表工作。当你分配任务时，协调员会同
 
 **提交此文件夹。** 你的团队会持久化。名字会持久化。任何克隆的人都会获得团队 —— 使用相同的演员表。
 
-### SDK 优先模式（Phase 1 新功能）
+### SDK 优先模式（已弃用）
 
-> ⚠️ **实验性功能。** SDK 优先模式正在积极开发中，存在已知 bug。生产环境团队请使用 markdown 优先模式（默认）。
+> ⚠️ **已弃用。** `squad init --sdk` 将在 v2 中移除。新团队请使用默认的 markdown 优先 `squad init` 流程。
 
-更喜欢 TypeScript？你可以用代码而不是 markdown 定义团队。创建一个带有构建器函数的 `squad.config.ts`，运行 `squad build`，`.squad/` 文件就会自动生成。
-
-```typescript
-// squad.config.ts
-import { defineSquad, defineTeam, defineAgent } from '@bradygaster/squad-sdk';
-
-export default defineSquad({
-  team: defineTeam({ name: 'Platform Squad', members: ['@edie', '@mcmanus'] }),
-  agents: [
-    defineAgent({ name: 'edie', role: 'TypeScript Engineer', model: 'claude-sonnet-5' }),
-    defineAgent({ name: 'mcmanus', role: 'DevRel', model: 'claude-haiku-4.5' }),
-  ],
-});
-```
-
-运行 `squad build` 生成所有 markdown 文件。完整文档请参阅 [SDK 优先模式指南](docs/src/content/docs/sdk-first-mode.md)。
+现有的 `squad.config.ts` 项目可以在过渡期间继续运行 `squad build`。兼容性信息请参阅 [旧版 SDK 优先模式指南](docs/src/content/docs/sdk-first-mode.md)。
 
 ---
 
diff --git a/docs/proposals/deprecate-sdk-init.md b/docs/proposals/deprecate-sdk-init.md
new file mode 100644
index 000000000..fe7603091
--- /dev/null
+++ b/docs/proposals/deprecate-sdk-init.md
@@ -0,0 +1,24 @@
+# Proposal: Deprecate SDK-First Initialization
+
+> **Authors:** Brady Gaster and Tamir Dresher
+> **Date:** 2026-09-01
+> **Status:** Accepted
+> **Goal:** Make markdown-first configuration the single recommended authoring model before v2.
+
+## Decision
+
+Deprecate `squad init --sdk` immediately and remove it in v2. Keep the flag functional during the transition, but print a warning and stop recommending it for new teams.
+
+Existing `squad.config.ts` projects retain `squad build` compatibility during the transition.
+This decision deprecates the file-authoring mode, not the programmatic `@bradygaster/squad-sdk` APIs.
+
+## Rationale
+
+The SDK-first builder schema and `squad build` generator represent only a subset of current Squad behavior. Maintaining parity requires two competing configuration models and weakens Squad's portable, CLI-independent markdown model.
+
+## Compatibility
+
+- `squad init --sdk` continues to generate `squad.config.ts` until v2.
+- Existing `squad.config.ts` projects can continue using `squad build`.
+- Default `squad init` behavior is unchanged.
+- User-facing help and documentation identify SDK-first initialization as deprecated.
diff --git a/docs/src/content/blog/024-v0823-release.md b/docs/src/content/blog/024-v0823-release.md
index e3e66ccc2..3ca753e63 100644
--- a/docs/src/content/blog/024-v0823-release.md
+++ b/docs/src/content/blog/024-v0823-release.md
@@ -10,6 +10,8 @@ hero: "v0.8.23 fixes a critical crash when running `squad init` on Node.js 24+ a
 # v0.8.23 Release: Node 24+ Compatibility, Squad RC Docs, and Critical Fixes
 > _v0.8.23 is a critical hotfix addressing a crash when running `squad init` on Node.js 24+ and GitHub Codespaces. It ships comprehensive Squad RC documentation, introduces lazy module loading for faster CLI startup, and includes a postinstall patch for ESM import issues. 2 issues closed, 3 PRs merged, 3,811 tests passing._
 
+> ⚠️ **Historical release note.** SDK-first initialization was deprecated after this release and will be removed in v2. Use markdown-first `squad init` for new teams.
+
 ---
 ## What Shipped
 ### 1. SDK-First Mode (Phase 1) — The Headline Feature
diff --git a/docs/src/content/docs/concepts/what-is-squad.md b/docs/src/content/docs/concepts/what-is-squad.md
index 2b1f1c22c..405a6eb6b 100644
--- a/docs/src/content/docs/concepts/what-is-squad.md
+++ b/docs/src/content/docs/concepts/what-is-squad.md
@@ -35,9 +35,9 @@ Squad enforces explicit safeguards at the framework level:
 - **Reviewer lockout** blocks agents from self-approving work that requires human sign-off.
 - **Escalation points** surface unresolved decisions to the designated human owner before execution continues.
 
-### SDK-first design
+### Markdown-first design
 
-Squad configuration is written in TypeScript (`squad.config.ts`). Configuration is typed, testable, and linted. Teams that already use TypeScript get full editor support, compile-time validation, and familiar tooling.
+Squad configuration lives in portable markdown under `.squad/`, so a team works across supported Copilot surfaces without a build step. The legacy `squad.config.ts` authoring mode is deprecated and will be removed in v2.
 
 ### Extensible
 
@@ -126,4 +126,3 @@ Squad is built on the principle that agentic systems must remain under human con
 
 Agents in Squad propose, draft, and record. Humans review, approve, and are accountable for final output. The governance features built into Squad, including reviewer lockout, escalation points, and auditable decision logs, are not optional settings. They are part of the framework's design contract. Squad extends human teams at scale; it doesn't remove the human from the loop.
 
-
diff --git a/docs/src/content/docs/features/built-in-roles.md b/docs/src/content/docs/features/built-in-roles.md
index 6723078af..d01ab764d 100644
--- a/docs/src/content/docs/features/built-in-roles.md
+++ b/docs/src/content/docs/features/built-in-roles.md
@@ -62,7 +62,9 @@ Suggested team:
 Look right? [Yes] [Add someone] [Change a role] [Browse all roles]
 ```
 
-### In squad.config.ts (SDK Mode)
+### In an existing squad.config.ts (legacy SDK-first mode)
+
+> ⚠️ **Deprecated authoring mode.** Do not adopt `squad.config.ts` for a new team. This example remains for compatibility with existing projects.
 
 ```typescript
 import { useRole, defineSquad } from '@bradygaster/squad-sdk';
diff --git a/docs/src/content/docs/get-started/installation.md b/docs/src/content/docs/get-started/installation.md
index ca23d55e5..b7526dca7 100644
--- a/docs/src/content/docs/get-started/installation.md
+++ b/docs/src/content/docs/get-started/installation.md
@@ -152,6 +152,8 @@ npm install @bradygaster/squad-sdk
 import { defineConfig, loadConfig, resolveSquad } from '@bradygaster/squad-sdk';
 ```
 
+The SDK remains supported for programmatic integrations. The separate `squad.config.ts` file-authoring mode created by `squad init --sdk` is deprecated; use markdown-first `squad init` for new teams.
+
 See the [SDK Reference](../reference/sdk.md) for the typed configuration,
 routing, and agent lifecycle APIs.
 
diff --git a/docs/src/content/docs/guide.md b/docs/src/content/docs/guide.md
index 980becd3b..9503655d3 100644
--- a/docs/src/content/docs/guide.md
+++ b/docs/src/content/docs/guide.md
@@ -44,7 +44,7 @@ Squad works across multiple interfaces — GitHub Copilot CLI, VS Code, Squad CL
 - **GitHub Copilot CLI** — Day-to-day conversational work with your squad (recommended)
 - **VS Code** — Same experience, editor-integrated
 - **Squad CLI** — Setup, diagnostics, monitoring (`squad init`, `squad doctor`, `squad watch`)
-- **SDK** — Build tools on top of Squad with `squad.config.ts`
+- **SDK** — Build programmatic integrations with `@bradygaster/squad-sdk`
 - **Copilot Coding Agent** — Autonomous issue processing via `@copilot`
 
 **Multi-platform support:** Squad also works with Azure DevOps (work items, PRs via `az boards`/`az repos`), GitLab Issues, and Microsoft Planner through pluggable platform adapters. See [Enterprise Platforms](features/enterprise-platforms.md) for details.
@@ -218,46 +218,13 @@ Squad automatically picks the right response speed based on your request complex
 
 ---
 
-## SDK-first mode
+## SDK-first mode (deprecated)
 
-Define your team in TypeScript instead of maintaining markdown files manually. Write a `squad.config.ts` with type-safe builder functions, and `squad build` generates the `.squad/` governance markdown.
+`squad init --sdk` is deprecated and will be removed in v2 because its TypeScript configuration model does not represent the full Squad feature set. Use `squad init` and maintain the generated markdown directly for new teams.
 
-```typescript
-import { defineSquad, defineTeam, defineAgent, defineRouting } from '@bradygaster/squad-sdk';
-
-export default defineSquad({
-  team: defineTeam({
-    name: 'Core Squad',
-    description: 'The main engineering team',
-    members: ['@edie', '@mcmanus'],
-  }),
-  agents: [
-    defineAgent({
-      name: 'edie',
-      role: 'TypeScript Engineer',
-      model: 'claude-sonnet-5',
-      capabilities: [{ name: 'type-system', level: 'expert' }],
-    }),
-  ],
-  routing: defineRouting({
-    rules: [{ pattern: 'feature-*', agents: ['@edie'], tier: 'standard' }],
-    defaultAgent: '@coordinator',
-  }),
-});
-```
-
-**Get started:**
-
-```bash
-squad init --sdk          # New project with SDK config
-squad migrate --to sdk    # Convert existing .squad/ to TypeScript
-squad build               # Generate .squad/ from config
-squad build --check       # Validate in CI without writing
-```
-
-Builder functions: `defineTeam()`, `defineAgent()`, `defineRouting()`, `defineCeremony()`, `defineHooks()`, `defineCasting()`, `defineTelemetry()`, `defineSkill()`, `defineSquad()`.
+Existing `squad.config.ts` projects can continue using `squad build` and `squad build --check` during the transition.
 
-→ [Full guide: SDK-First Mode](sdk-first-mode.md)
+→ [Legacy SDK-First Mode compatibility guide](sdk-first-mode.md)
 
 ---
 
@@ -267,7 +234,7 @@ Squad names agents from fictional universes — Apollo 13 / NASA Mission Control
 
 Casting is **persistent** — once an agent receives a name, it keeps that name across sessions. The casting registry lives in `.squad/casting/registry.json`. You control which universes are available through a policy allowlist and can set per-universe capacity limits.
 
-In SDK-first mode, configure casting with `defineCasting()`:
+Existing SDK-first projects can configure casting with `defineCasting()`:
 
 ```typescript
 defineCasting({
@@ -287,7 +254,7 @@ Skills are reusable knowledge patterns that agents load on demand. They live in
 
 Skills have a confidence lifecycle: `low` → `medium` → `high`, and track their source: `manual` (you wrote it), `observed` (agent saw a pattern), `earned` (validated through use), or `extracted` (imported from another project).
 
-In SDK-first mode, define skills with `defineSkill()`:
+Existing SDK-first projects can define skills with `defineSkill()`:
 
 ```typescript
 defineSkill({
@@ -314,7 +281,7 @@ Skills accumulate as you work. After a few sessions, your team has a knowledge b
 
 Ceremonies are structured team meetings. Squad ships with two default ceremonies — Design Review (triggers before multi-agent work) and Retrospective (triggers after failures). You can trigger ceremonies manually, create custom ones, or disable them. Configuration lives in `.squad/ceremonies.md`.
 
-In SDK-first mode, define ceremonies with `defineCeremony()`:
+Existing SDK-first projects can define ceremonies with `defineCeremony()`:
 
 ```typescript
 defineCeremony({
@@ -539,7 +506,7 @@ Squad maintains a clear ownership model:
 |------|-------|--------------|
 | `.github/agents/squad.agent.md` | Squad (overwritten on upgrade) | No — your changes will be lost |
 | `.squad/` | You and your team | Yes — this is your team's state |
-| `squad.config.ts` | You | Yes — your SDK-first config |
+| `squad.config.ts` | You | Legacy SDK-first projects only |
 | Everything else | You | Yes |
 
 ---
@@ -549,7 +516,7 @@ Squad maintains a clear ownership model:
 | Command | What it does |
 |---------|-------------|
 | `squad init` | Initialize Squad in the current repo |
-| `squad init --sdk` | Initialize with SDK-first TypeScript config |
+| `squad init --sdk` | Deprecated; compatibility only until v2 |
 | `squad init --global` | Initialize a personal squad (cross-project) |
 | `squad build` | Generate `.squad/` from `squad.config.ts` |
 | `squad build --check` | Validate generated files match disk (for CI) |
@@ -563,7 +530,7 @@ Squad maintains a clear ownership model:
 | `squad import <file> --force` | Import, archiving existing agents |
 | `squad plugin install <name>` | Install a plugin from the marketplace |
 | `squad plugin list` | List installed plugins |
-| `squad migrate --to sdk` | Convert existing squad to SDK-first config |
+| `squad migrate --to sdk` | Deprecated; do not start new SDK-first migrations |
 | `squad migrate --from ai-team` | Migrate from `.ai-team/` to `.squad/` |
 | `squad subsquads` | Manage SubSquads |
 | `squad status` | Show team status and global config |
diff --git a/docs/src/content/docs/reference/config.md b/docs/src/content/docs/reference/config.md
index 1d0b62018..160c71600 100644
--- a/docs/src/content/docs/reference/config.md
+++ b/docs/src/content/docs/reference/config.md
@@ -13,7 +13,9 @@ That's it. Squad works out of the box. Everything below is optional.
 
 ## squad.config.ts
 
-For type-safe SDK-First configuration, create this at your project root:
+> ⚠️ **Deprecated authoring mode.** `squad init --sdk` will be removed in v2. The reference below remains for existing projects using `squad build`.
+
+Legacy SDK-first projects may define this file at the project root:
 
 ```typescript
 import {
@@ -127,7 +129,7 @@ rm -rf .squad && squad init         # Full reset (back up agents/decisions first
 
 ## Routing Rules
 
-Control which agent gets which work. Edit `.squad/routing.md` or configure in `squad.config.ts`:
+Control which agent gets which work in `.squad/routing.md`. Existing SDK-first projects may instead configure routing in `squad.config.ts`:
 
 ```markdown
 # Routing Rules
diff --git a/docs/src/content/docs/reference/sdk.md b/docs/src/content/docs/reference/sdk.md
index 00052c8e7..b0f9da44e 100644
--- a/docs/src/content/docs/reference/sdk.md
+++ b/docs/src/content/docs/reference/sdk.md
@@ -90,6 +90,8 @@ Use `result.errors` and `result.warnings` when presenting validation results. Th
 
 ## SDK-First Builders
 
+> ⚠️ **Deprecated authoring mode.** `squad init --sdk` will be removed in v2. These builders remain documented for existing `squad.config.ts` projects and programmatic SDK consumers during the transition.
+
 Builders validate typed team definitions before they are written to `.squad/` by `squad build`.
 
 ```typescript
@@ -340,4 +342,4 @@ Use the [generated API reference](./api/) for the complete list of current expor
 - [Generated API reference](./api/) - exhaustive TypeDoc output
 - [Configuration reference](./config.md) - file format and migration details
 - [Tools and hooks](./tools-and-hooks.md) - focused orchestration examples
-- [SDK-First Mode](../sdk-first-mode.md) - builder workflow and `squad build`
+- [Legacy SDK-First Mode](../sdk-first-mode.md) - compatibility for existing builder workflows
diff --git a/docs/src/content/docs/sdk-first-mode.md b/docs/src/content/docs/sdk-first-mode.md
index 15be49f1a..cf592a09a 100644
--- a/docs/src/content/docs/sdk-first-mode.md
+++ b/docs/src/content/docs/sdk-first-mode.md
@@ -1,8 +1,10 @@
-# SDK-First Squad Mode
+# Legacy SDK-First Squad Mode
+
+> ⚠️ **Deprecated.** `squad init --sdk` will be removed in v2 because `squad.config.ts` does not represent the full Squad feature set. Use markdown-first `squad init` for new teams. Existing projects can continue using `squad build` during the transition.
 
 > **Phase 1** — Type-safe team configuration with builder functions.
 
-Squad now supports **SDK-First Mode**: define your team in TypeScript with full type safety, runtime validation, and editor autocomplete. Instead of manually maintaining markdown files in `.squad/`, you write clean TypeScript, and `squad build` generates the governance markdown.
+Legacy SDK-First Mode defines a team in TypeScript and uses `squad build` to generate governance markdown. This page remains available only for teams maintaining an existing `squad.config.ts`.
 
 ---
 
@@ -35,19 +37,19 @@ In SDK-First Mode:
 
 This replaces manual `.squad/team.md`, `.squad/routing.md`, and agent charters with a single source of truth in code.
 
-**When to use SDK mode:** For a comparison of SDK-first mode versus CLI mode, see the [Getting started guide](/guide#how-teams-form-init-mode).
+The remaining sections document compatibility for teams that already use SDK-first mode. Do not adopt this mode for a new team.
 
 ---
 
-## Quick Start
+## Maintaining an existing SDK-first project
 
-### 1. Install the SDK
+### 1. Keep the SDK dependency installed
 
 ```bash
 npm install @bradygaster/squad-sdk
 ```
 
-### 2. Create `squad.config.ts`
+### 2. Maintain the existing `squad.config.ts`
 
 ```typescript
 import {
@@ -104,50 +106,25 @@ This generates:
 
 ---
 
-## Start a new SDK-first project
+## Legacy initialization
 
 ```bash
 squad init --sdk
 ```
 
-This generates `.squad/` markdown files and a `squad.config.ts` at your project root using the `defineSquad()` builder syntax. Your TypeScript config is the source of truth — edit it, then run `squad build` to regenerate `.squad/`.
+This deprecated command remains available temporarily for compatibility testing. It generates `.squad/` markdown files and a `squad.config.ts` at your project root using the `defineSquad()` builder syntax. Do not use it for new production teams.
 
 For the full team initialization flow, see [How teams form (Init Mode)](/guide#how-teams-form-init-mode) in the getting started guide.
 
 ---
 
-## Migrating an Existing Squad to SDK-First
-
-```bash
-squad migrate --to sdk        # generate squad.config.ts from existing .squad/
-squad migrate --to sdk --dry-run  # preview without writing
-```
-
-The migrate command reads your existing `.squad/` files (team.md, routing.md, agent charters) and generates a `squad.config.ts` that reproduces your current configuration using typed builders.
-
-### What Gets Migrated
-
-| Source | Generated |
-|--------|-----------|
-| `.squad/team.md` roster | `defineTeam({ members: [...] })` |
-| `.squad/agents/*/charter.md` | `defineAgent({ name, role, ... })` per agent |
-| `.squad/routing.md` rules | `defineRouting({ rules: [...] })` |
-| `.squad/ceremonies.md` | `defineCeremony()` entries |
-| `.squad/casting/policy.json` | `defineCasting()` block |
-
-### What's Preserved (Not Migrated)
-
-- `decisions.md` — append-only ledger, stays as-is
-- `agents/*/history.md` — personal knowledge, stays as-is
-- `orchestration-log/`, `log/` — append-only archives
-
-### Reverting to Markdown
+## Migrating away from SDK-first mode
 
 ```bash
 squad migrate --to markdown
 ```
 
-This runs `squad build` to ensure `.squad/` is current, then removes `squad.config.ts`.
+This runs `squad build` to ensure `.squad/` is current, then removes `squad.config.ts`. Review the generated markdown before deleting the TypeScript configuration from version control.
 
 ### Legacy Migration
 
@@ -484,7 +461,7 @@ defineAgent({
 
 You manually maintain this file and agent charters.
 
-### After (SDK-First)
+### Existing SDK-first project
 
 ```typescript
 export default defineSquad({
@@ -519,7 +496,7 @@ Run `squad build` and the markdown is generated. Version control your TypeScript
 
 ## Examples
 
-### Full SDK-First Config
+### Full legacy SDK-first config
 
 ```typescript
 import {
diff --git a/docs/src/content/docs/whatsnew.md b/docs/src/content/docs/whatsnew.md
index 86a899876..ef05b0ec9 100644
--- a/docs/src/content/docs/whatsnew.md
+++ b/docs/src/content/docs/whatsnew.md
@@ -2,6 +2,8 @@
 
 > ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
 
+> ⚠️ **Current status.** SDK-first initialization described in older entries below is now deprecated and will be removed in v2. Use markdown-first `squad init` for new teams.
+
 
 Full release history for Squad — from beta through the v1 TypeScript replatform. Jump to the version you're looking for, or read top-down to see how the project evolved.
 
diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts
index 45f760bfd..c43000337 100644
--- a/docs/src/navigation.ts
+++ b/docs/src/navigation.ts
@@ -167,7 +167,7 @@ export const NAV_SECTIONS: NavSection[] = [
 ];
 export const STANDALONE_PAGES = [
   { title: "What's New", slug: 'whatsnew' },
-  { title: 'SDK-First Mode', slug: 'sdk-first-mode' },
+  { title: 'Legacy SDK-First Mode', slug: 'sdk-first-mode' },
   { title: 'Community', slug: 'community' },
   { title: 'Insider Program', slug: 'insider-program' },
 ];
diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts
index 1a4b160d8..7db30856b 100644
--- a/packages/squad-cli/src/cli-entry.ts
+++ b/packages/squad-cli/src/cli-entry.ts
@@ -154,7 +154,7 @@ async function main(): Promise<void> {
     console.log(`  ${BOLD}(default)${RESET}  Launch interactive shell (no args)`);
     console.log(`             Flags: --global (init in personal squad directory)`);
     console.log(`  ${BOLD}init${RESET}       Initialize Squad (markdown-only, default)`);
-    console.log(`             Flags: --sdk (SDK builder syntax)`);
+    console.log(`             Flags: --sdk (deprecated; removed in v2)`);
     console.log(`                    --roles (use base roles)`);
     console.log(`                    --global (personal squad dir)`);
     console.log(`                    --no-workflows (skip CI setup)`);
@@ -1172,4 +1172,3 @@ main().catch(err => {
   }
   process.exit(1);
 });
-
diff --git a/packages/squad-cli/src/cli/core/command-help.ts b/packages/squad-cli/src/cli/core/command-help.ts
index 90ff42619..bca3e8441 100644
--- a/packages/squad-cli/src/cli/core/command-help.ts
+++ b/packages/squad-cli/src/cli/core/command-help.ts
@@ -37,7 +37,7 @@ const COMMAND_HELP: Record<string, HelpPrinter> = {
     console.log(`Creates a markdown-based squad layout under .squad/ plus default agent`);
     console.log(`workflows under .github/. Safe to re-run — existing files are preserved.\n`);
     console.log(`Options:`);
-    console.log(`  ${BOLD}--sdk${RESET}                       Use SDK builder syntax (squad.config.ts)`);
+    console.log(`  ${BOLD}--sdk${RESET}                       Generate squad.config.ts (deprecated; removed in v2)`);
     console.log(`  ${BOLD}--roles${RESET}                     Seed the team with built-in base roles`);
     console.log(`  ${BOLD}--global${RESET}                    Initialize in the personal (global) squad directory`);
     console.log(`  ${BOLD}--no-workflows${RESET}              Skip writing GitHub Actions workflows`);
diff --git a/packages/squad-cli/src/cli/core/init.ts b/packages/squad-cli/src/cli/core/init.ts
index 48d296804..6af2dd4b3 100644
--- a/packages/squad-cli/src/cli/core/init.ts
+++ b/packages/squad-cli/src/cli/core/init.ts
@@ -7,7 +7,7 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { FSStorageProvider } from '@bradygaster/squad-sdk';
 import { detectSquadDir, resolveWorktreeMainCheckout } from './detect-squad-dir.js';
-import { success, BOLD, RESET, YELLOW, GREEN, DIM } from './output.js';
+import { success, warn, BOLD, RESET, YELLOW, GREEN, DIM } from './output.js';
 import { fatal } from './errors.js';
 import { detectProjectType } from './project-type.js';
 import { getPackageVersion, stampVersion } from './version.js';
@@ -174,6 +174,12 @@ export interface RunInitOptions {
 export async function runInit(dest: string, options: RunInitOptions = {}): Promise<void> {
   const version = getPackageVersion();
 
+  if (options.sdk) {
+    warn('`squad init --sdk` is deprecated and will be removed in v2. Use `squad init` for new teams.');
+    console.log(`${DIM}Existing squad.config.ts users can continue using ${BOLD}squad build${RESET}${DIM} during the transition.${RESET}`);
+    console.log();
+  }
+
   console.log();
   await typewrite(`${DIM}Let's build your team.${RESET}`, 8);
   console.log();
diff --git a/test/cli/command-help.test.ts b/test/cli/command-help.test.ts
index 417643f7c..ea18c3713 100644
--- a/test/cli/command-help.test.ts
+++ b/test/cli/command-help.test.ts
@@ -57,6 +57,8 @@ describe('printCommandHelp', () => {
     const blob = logs.join('\n');
     expect(blob).toContain('squad init');
     expect(blob).toContain('9.9.9-test');
+    expect(blob).toContain('--sdk');
+    expect(blob).toContain('deprecated; removed in v2');
     expect(blob).toContain('Usage:');
   });
 
@@ -197,6 +199,12 @@ describe.skipIf(!cliBuilt)('squad <cmd> --help end-to-end', () => {
     rmSync(tempDir, { recursive: true, force: true });
   });
 
+  it('top-level help marks --sdk as deprecated', async () => {
+    const { stdout, stderr } = await runSquad(['--help'], tempDir);
+    const out = stdout + stderr;
+    expect(out).toContain('--sdk (deprecated; removed in v2)');
+  });
+
   it('init --help prints help and does NOT scaffold files', async () => {
     const { stdout, stderr } = await runSquad(['init', '--help'], tempDir);
     const out = stdout + stderr;
diff --git a/test/cli/init.test.ts b/test/cli/init.test.ts
index 667b90e0b..aaa4a4483 100644
--- a/test/cli/init.test.ts
+++ b/test/cli/init.test.ts
@@ -3,7 +3,7 @@
  * Tests that the init command creates expected files in a temp directory
  */
 
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { mkdir, rm, readdir, readFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
@@ -51,6 +51,21 @@ describe('CLI: init command', () => {
     expect(content).toContain('version:');
   });
 
+  it('warns that --sdk is deprecated while preserving compatibility', async () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      await runInit(TEST_ROOT, { sdk: true });
+
+      const output = log.mock.calls.flat().join('\n');
+      expect(output).toContain('squad init --sdk');
+      expect(output).toContain('deprecated');
+      expect(output).toContain('removed in v2');
+      expect(existsSync(join(TEST_ROOT, 'squad.config.ts'))).toBe(true);
+    } finally {
+      log.mockRestore();
+    }
+  });
+
   it('should stamp CLI version in squad.agent.md during init (#321)', async () => {
     await runInit(TEST_ROOT);