diff --git a/apps/cli/src/commands/config.ts b/apps/cli/src/commands/config.ts
new file mode 100644
index 00000000..f9108aa2
--- /dev/null
+++ b/apps/cli/src/commands/config.ts
@@ -0,0 +1,40 @@
+import { Result } from 'better-result';
+import { Command } from 'commander';
+
+import { updateModel } from '../client/index.ts';
+import { ensureServer } from '../server/manager.ts';
+
+const configModelCommand = new Command('model')
+	.description('Deprecated alias for "btca connect --provider ... --model ..."')
+	.requiredOption('-p, --provider <id>', 'Provider ID')
+	.requiredOption('-m, --model <id>', 'Model ID')
+	.action(async (options: { provider: string; model: string }, command) => {
+		const root = command.parent?.parent;
+		const globalOpts = root?.opts() as { server?: string; port?: number } | undefined;
+
+		const result = await Result.tryPromise(async () => {
+			const server = await ensureServer({
+				serverUrl: globalOpts?.server,
+				port: globalOpts?.port,
+				quiet: true
+			});
+
+			const updated = await updateModel(server.url, options.provider, options.model);
+			server.stop();
+
+			console.warn(
+				'Deprecation: "btca config model" will be removed in a future release. Use "btca connect --provider ... --model ...".'
+			);
+			console.log(`Model updated: ${updated.provider}/${updated.model}`);
+		});
+
+		if (Result.isError(result)) {
+			const message = result.error instanceof Error ? result.error.message : String(result.error);
+			console.error(`Error: ${message}`);
+			process.exit(1);
+		}
+	});
+
+export const configCommand = new Command('config')
+	.description('Deprecated config command compatibility aliases')
+	.addCommand(configModelCommand);
diff --git a/apps/cli/src/index.test.ts b/apps/cli/src/index.test.ts
index d6132bca..5004a223 100644
--- a/apps/cli/src/index.test.ts
+++ b/apps/cli/src/index.test.ts
@@ -27,6 +27,12 @@ describe('cli dispatch', () => {
 		expect(result.output).toContain('Usage: btca add');
 	});
 
+	test('keeps nested subcommand help contextual for btca config model', () => {
+		const result = runCli(['config', 'model', '--help']);
+		expect(result.exitCode).toBe(0);
+		expect(result.output).toContain('Usage: btca config model');
+	});
+
 	test('rejects unknown top-level commands with a suggestion', () => {
 		const result = runCli(['remoev'], 250);
 		expect(result.exitCode).toBe(1);
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 58c1ca82..000b19ea 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import { addCommand } from './commands/add.ts';
 import { askCommand } from './commands/ask.ts';
 import { clearCommand } from './commands/clear.ts';
+import { configCommand } from './commands/config.ts';
 import { connectCommand } from './commands/connect.ts';
 import { disconnectCommand } from './commands/disconnect.ts';
 import { initCommand } from './commands/init.ts';
@@ -53,6 +54,7 @@ program.addCommand(askCommand);
 
 // Configuration commands
 program.addCommand(connectCommand);
+program.addCommand(configCommand);
 program.addCommand(disconnectCommand);
 program.addCommand(initCommand);
 program.addCommand(statusCommand);
diff --git a/apps/docs/guides/cli-reference.mdx b/apps/docs/guides/cli-reference.mdx
index 84f0d6dd..c7b5a026 100644
--- a/apps/docs/guides/cli-reference.mdx
+++ b/apps/docs/guides/cli-reference.mdx
@@ -58,7 +58,7 @@ Options:
 
 - `-g, --global` sets the flag, but target resolution still depends on whether a project config exists.
 - `-n, --name <name>` sets a resource name.
-- `-b, --branch <branch>` sets a branch (default `main`).
+- `-b, --branch <branch>` sets a branch (auto-detected when omitted).
 - `-s, --search-path <path...>` sets one or more search paths.
 - `--notes <notes>` sets special notes.
 - `-t, --type <git|local|npm>` forces the resource type.
@@ -168,6 +168,16 @@ For `openai-compat`, the interactive flow additionally prompts for:
 - Model ID (required): saved as `model` in `btca.config.jsonc`.
 - API key (optional): only if your server requires auth, stored in OpenCode auth.
 
+## `btca config model` (compatibility alias)
+
+Backward-compatible alias for model updates:
+
+```bash
+btca config model --provider <id> --model <id>
+```
+
+This command delegates to the same update path as `btca connect` and prints a deprecation notice.
+
 ## `btca status`
 
 Shows current btca status.