docs: make Bedrock configuration optional for Claude Code (#428)

Default settings.json now works with plain Claude Code (direct
Anthropic API) without Bedrock-specific env vars. Bedrock config
moved to an optional section in the README with copy-paste env block.

Fixes #428

Author: Aadil S

README.md

@@ -89,7 +89,7 @@ On Windows, use *either* PowerShell *or* CMD, not both — your prompt shows `PS
 > [!TIP]
 > bun has to be on the PATH that *non-interactive* shells see, since that's what a harness uses to run a hook or tool. Those shells read `~/.zshenv` (zsh) or `~/.bashrc` (bash), not `~/.zshrc` — but the bun installer writes to `~/.zshrc`. So if `which bun` works in your terminal yet the harness can't find bun, copy the `BUN_INSTALL`/`PATH` export into `~/.zshenv` (or `~/.bashrc` for bash and Git Bash).
 
-Every harness runs on **AWS Bedrock**, so set Bedrock up before your first run — enable model access in your AWS account and make sure the harness can see working AWS credentials. Each harness section below has the specifics.
+Every harness supports **AWS Bedrock** as an optional backend. Claude Code works with either the direct Anthropic API or Bedrock; Codex and Kiro harnesses default to Bedrock. If using Bedrock, enable model access in your AWS account and make sure the harness can see working AWS credentials. Each harness section below has the specifics.
 
 ### Install a harness
 
@@ -185,7 +185,27 @@ Then, inside the Claude Code session:
 /aidlc Build a task management API with user authentication   # start a workflow
 ```
 
-The shipped `.claude/settings.json` runs on **AWS Bedrock** (`AWS_REGION=us-east-1`, Fable/Opus/Sonnet/Haiku pinned). Before your first run, enable Anthropic model access in your AWS account and have AWS credentials on your SDK credential chain — see [Getting Started § AWS Bedrock Setup](docs/guide/01-getting-started.md#aws-bedrock-setup) for the model-access form, IAM policy, credential options, and how to change the region. The full prerequisites table, PATH troubleshooting, and Bedrock configuration are in [Getting Started](docs/guide/01-getting-started.md).
+The shipped `.claude/settings.json` works with **plain Claude Code** (direct Anthropic API) out of the box — no additional configuration needed.
+
+<details>
+<summary><b>Optional: Using Amazon Bedrock</b></summary>
+
+To run on AWS Bedrock instead of the direct Anthropic API, add the following to your `.claude/settings.json` `env` block:
+
+```json
+"CLAUDE_CODE_USE_BEDROCK": "1",
+"AWS_REGION": "us-east-1",
+"ANTHROPIC_DEFAULT_FABLE_MODEL": "global.anthropic.claude-fable-5",
+"ANTHROPIC_DEFAULT_OPUS_MODEL": "global.anthropic.claude-opus-4-8",
+"ANTHROPIC_DEFAULT_SONNET_MODEL": "global.anthropic.claude-sonnet-4-6",
+"ANTHROPIC_DEFAULT_HAIKU_MODEL": "global.anthropic.claude-haiku-4-5-20251001-v1:0"
+```
+
+And update the `model` field to use the Bedrock model format (e.g., `"model": "opus[1m]"`).
+
+Enable Anthropic model access in your AWS account and have AWS credentials on your SDK credential chain — see [Getting Started § AWS Bedrock Setup](docs/guide/01-getting-started.md#aws-bedrock-setup) for the model-access form, IAM policy, credential options, and how to change the region.
+
+</details>
 
 </details>
 

dist/claude/.claude/settings.json

@@ -20,15 +20,9 @@
     "command": "bun $CLAUDE_PROJECT_DIR/.claude/hooks/aidlc-statusline.ts"
   },
   "env": {
-    "AWS_AIDLC_DEFAULT_SCOPE": "workshop",
-    "CLAUDE_CODE_USE_BEDROCK": "1",
-    "AWS_REGION": "us-east-1",
-    "ANTHROPIC_DEFAULT_FABLE_MODEL": "global.anthropic.claude-fable-5",
-    "ANTHROPIC_DEFAULT_OPUS_MODEL": "global.anthropic.claude-opus-4-8",
-    "ANTHROPIC_DEFAULT_SONNET_MODEL": "global.anthropic.claude-sonnet-4-6",
-    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "global.anthropic.claude-haiku-4-5-20251001-v1:0"
+    "AWS_AIDLC_DEFAULT_SCOPE": "workshop"
   },
-  "model": "opus[1m]",
+  "model": "opus",
   "effortLevel": "xhigh",
   "hooks": {
     "SessionStart": [

harness/claude/settings.json

@@ -20,15 +20,9 @@
     "command": "bun $CLAUDE_PROJECT_DIR/.claude/hooks/aidlc-statusline.ts"
   },
   "env": {
-    "AWS_AIDLC_DEFAULT_SCOPE": "workshop",
-    "CLAUDE_CODE_USE_BEDROCK": "1",
-    "AWS_REGION": "us-east-1",
-    "ANTHROPIC_DEFAULT_FABLE_MODEL": "global.anthropic.claude-fable-5",
-    "ANTHROPIC_DEFAULT_OPUS_MODEL": "global.anthropic.claude-opus-4-8",
-    "ANTHROPIC_DEFAULT_SONNET_MODEL": "global.anthropic.claude-sonnet-4-6",
-    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "global.anthropic.claude-haiku-4-5-20251001-v1:0"
+    "AWS_AIDLC_DEFAULT_SCOPE": "workshop"
   },
-  "model": "opus[1m]",
+  "model": "opus",
   "effortLevel": "xhigh",
   "hooks": {
     "SessionStart": [

tests/smoke/t03-settings-json.test.ts

@@ -124,9 +124,9 @@ describe("statusLine [.sh test 10]", () => {
 });
 
 describe("orchestrator model pin [.sh test 11]", () => {
-  test("model is pinned to opus[1m]", () => {
-    // .sh asserted exact string equality (`[ "$MODEL" = "opus[1m]" ]`).
-    expect(settings.model).toBe("opus[1m]");
+  test("model is pinned to opus", () => {
+    // Default uses plain Claude Code (no Bedrock suffix).
+    expect(settings.model).toBe("opus");
   });
 });
 
@@ -140,37 +140,21 @@ describe("orchestrator reasoning-effort pin", () => {
   });
 });
 
-describe("Bedrock env block [.sh tests 12-16 + Fable pin]", () => {
+describe("Bedrock env block — optional (#428)", () => {
   const env = settings.env ?? {};
 
-  test("env.CLAUDE_CODE_USE_BEDROCK is 1 [.sh test 12]", () => {
-    expect(env.CLAUDE_CODE_USE_BEDROCK).toBe("1");
+  test("env does NOT include Bedrock vars by default (#428)", () => {
+    // Bedrock configuration is optional — plain Claude Code users should not
+    // need to configure AWS credentials to get started.
+    expect(env.CLAUDE_CODE_USE_BEDROCK).toBeUndefined();
+    expect(env.AWS_REGION).toBeUndefined();
+    expect(env.ANTHROPIC_DEFAULT_FABLE_MODEL).toBeUndefined();
+    expect(env.ANTHROPIC_DEFAULT_OPUS_MODEL).toBeUndefined();
+    expect(env.ANTHROPIC_DEFAULT_SONNET_MODEL).toBeUndefined();
+    expect(env.ANTHROPIC_DEFAULT_HAIKU_MODEL).toBeUndefined();
   });
 
-  test("env.AWS_REGION is set [.sh test 13]", () => {
-    // .sh asserted non-empty (`[ -n "$AWS_REGION_VAL" ]`) — Bedrock requires
-    // a region; Claude Code does not read it from ~/.aws.
-    expect(typeof env.AWS_REGION).toBe("string");
-    expect((env.AWS_REGION ?? "").length).toBeGreaterThan(0);
-  });
-
-  test("env.ANTHROPIC_DEFAULT_FABLE_MODEL is pinned", () => {
-    expect(env.ANTHROPIC_DEFAULT_FABLE_MODEL).toBe("global.anthropic.claude-fable-5");
-  });
-
-  test("env.ANTHROPIC_DEFAULT_OPUS_MODEL is pinned [.sh test 14]", () => {
-    expect(env.ANTHROPIC_DEFAULT_OPUS_MODEL).toBe("global.anthropic.claude-opus-4-8");
-  });
-
-  test("env.ANTHROPIC_DEFAULT_SONNET_MODEL is pinned [.sh test 15]", () => {
-    expect(env.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe(
-      "global.anthropic.claude-sonnet-4-6",
-    );
-  });
-
-  test("env.ANTHROPIC_DEFAULT_HAIKU_MODEL is pinned [.sh test 16]", () => {
-    expect(env.ANTHROPIC_DEFAULT_HAIKU_MODEL).toBe(
-      "global.anthropic.claude-haiku-4-5-20251001-v1:0",
-    );
+  test("env.AWS_AIDLC_DEFAULT_SCOPE is set", () => {
+    expect(env.AWS_AIDLC_DEFAULT_SCOPE).toBe("workshop");
   });
 });