docs: add least-privilege deployment roles and deployment guide

.pre-commit-config.yaml

@@ -54,6 +54,14 @@ repos:
         files: ^agent/.*\.py$
         stages: [pre-commit]
 
+      - id: docs-sync
+        name: sync docs → Starlight mirrors
+        entry: bash -lc 'cd "$(git rev-parse --show-toplevel)/docs" && node scripts/sync-starlight.mjs && git add src/content/docs/'
+        language: system
+        pass_filenames: false
+        files: ^(docs/(design|guides)/.*\.md$|CONTRIBUTING\.md$)
+        stages: [pre-commit]
+
       - id: docs-astro-check
         name: astro check (docs)
         entry: bash -lc 'cd "$(git rev-parse --show-toplevel)/docs" && ./node_modules/.bin/astro check'

AGENTS.md

@@ -38,6 +38,7 @@ Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task.
 ### Common mistakes
 
 - Editing **`docs/src/content/docs/`** instead of **`docs/guides/`** or **`docs/design/`** — content is generated; sync from sources.
+- Adding or editing files in **`docs/design/`** or **`docs/guides/`** without running **`cd docs && node scripts/sync-starlight.mjs`** — CI will reject ("Fail build on mutation") because the Starlight mirror files in `docs/src/content/docs/` are stale. Always commit the regenerated mirrors alongside source changes.
 - Changing **`cdk/.../types.ts`** without updating **`cli/src/types.ts`** — CLI and API drift.
 - Running raw **`jest`/`tsc`/`cdk`** from muscle memory — prefer **`mise //cdk:test`**, **`mise //cdk:compile`**, **`mise //cdk:synth`** (see [Commands you can use](#commands-you-can-use)).
 - **`MISE_EXPERIMENTAL=1`** — required for namespaced tasks like **`mise //cdk:build`** (see [CONTRIBUTING.md](./CONTRIBUTING.md)).
@@ -120,7 +121,7 @@ To build or test only the CLI subproject:
 
 ## Boundaries
 
-- **Generated docs** — If you change docs sources (`docs/guides/`, `docs/design/`, `CONTRIBUTING.md`), run `mise //docs:sync` or `mise //docs:build`.
+- **Generated docs (CI will reject if stale)** — Editing files in `docs/guides/`, `docs/design/`, or `CONTRIBUTING.md` requires regenerating Starlight mirrors under `docs/src/content/docs/`. Run **`cd docs && node scripts/sync-starlight.mjs`** (fast, <1 s) or **`mise //docs:sync`**, then commit the updated mirrors alongside your source changes. The pre-commit hook `docs-sync` does this automatically when prek hooks are installed, but if you bypass hooks (e.g. `--no-verify`), CI's "Fail build on mutation" step will catch it.
 - **Dependencies** — Add dependencies to the owning package `package.json` (`cdk/`, `cli/`, or `docs/`), then install via workspace/root install.
-- **Build before commit** — Run a full build (`mise run build`) when done so tests/synth/docs/security checks stay in sync.
+- **Build before commit** — Run a full build (`mise run build`) when done so tests/synth/docs/security checks stay in sync. This is especially critical for docs changes — the build includes `//docs:sync` which regenerates Starlight mirrors, and CI will fail if the committed mirrors don't match what the build produces.
 - **Major changes** — Before modifying existing files in a major way (large refactors, new stacks, changing the agent contract), ask first.

CLAUDE.md

@@ -1 +1,3 @@
 @AGENTS.md
+
+See also [README.md](./README.md) for the Claude Code plugin (`docs/abca-plugin/`), which provides interactive guided workflows for setup, deployment, repository onboarding, task submission, and troubleshooting via `/setup`, `/deploy`, `/onboard-repo`, `/submit-task`, `/status`, and `/troubleshoot` skills. Run Claude Code with `claude --plugin-dir docs/abca-plugin` to activate it.

docs/abca-plugin/skills/deploy/SKILL.md

@@ -81,3 +81,16 @@ After a successful deploy, remind the user to:
 - Store/update the GitHub PAT in Secrets Manager if this is a fresh deployment
 - Onboard repositories via Blueprint constructs if needed
 - Run a smoke test: `curl -s -H "Authorization: $TOKEN" $API_URL/tasks`
+
+## Least-Privilege Deployment
+
+By default, CDK bootstrap grants `AdministratorAccess` to the CloudFormation execution role. For production or security-sensitive accounts, re-bootstrap with a scoped execution policy:
+
+```bash
+cdk bootstrap aws://ACCOUNT/REGION \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Infrastructure" \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Application" \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Observability"
+```
+
+See `docs/design/DEPLOYMENT_ROLES.md` in the repo root for the complete least-privilege IAM policies, trust policy, runtime role inventory, and iterative tightening recommendations.

docs/abca-plugin/skills/setup/SKILL.md

@@ -52,11 +52,17 @@ If `mise run install` fails with "yarn: command not found", Corepack wasn't acti
 
 ## Phase 3: One-Time AWS Setup
 
+On a fresh AWS account, X-Ray needs a CloudWatch Logs resource policy before it can write spans. Run both commands — the first creates the policy, the second sets the destination:
+
 ```bash
+ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
+aws logs put-resource-policy \
+  --policy-name xray-spans-policy \
+  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"XRaySpansAccess\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"xray.amazonaws.com\"},\"Action\":[\"logs:PutLogEvents\",\"logs:CreateLogGroup\",\"logs:CreateLogStream\"],\"Resource\":[\"arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans\",\"arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans:*\"]}]}"
 aws xray update-trace-segment-destination --destination CloudWatchLogs
 ```
 
-This must be run once per AWS account before first deployment.
+These must be run once per AWS account before first deployment. If the `put-resource-policy` step is skipped, the `update-trace-segment-destination` command fails with `AccessDeniedException`.
 
 ## Phase 4: First Deployment
 

docs/design/COST_MODEL.md

@@ -11,12 +11,16 @@ These costs are incurred regardless of task volume:
 | Component | Estimated cost | Notes |
 |---|---|---|
 | NAT Gateway (1×) | ~$32/month | Fixed hourly cost + data processing. Single AZ (see [COMPUTE.md  - Network architecture](./COMPUTE.md)). |
-| VPC Interface Endpoints (7×) | ~$50/month | $0.01/hr per endpoint per AZ. |
+| VPC Interface Endpoints (7×, 2 AZs) | ~$102/month | $0.01/hr × 7 endpoints × 2 AZs × 730 hrs. |
 | VPC Flow Logs | ~$3/month | CloudWatch ingestion. |
 | DynamoDB (on-demand, idle) | ~$0/month | Pay-per-request; no cost when idle. |
 | CloudWatch Logs retention | ~$1–5/month | Depends on log volume. 90-day retention. |
 | API Gateway (idle) | ~$0/month | Pay-per-request. |
-| **Total baseline** | **~$85–90/month** | |
+| **Total baseline** | **~$140–150/month** | |
+
+### Scale-to-zero characteristics
+
+Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST), Lambda, API Gateway, ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The always-on cost floor (~$140–150/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints across 2 AZs) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](../guides/DEPLOYMENT_GUIDE.md) for the full scale-to-zero breakdown.
 
 ## Per-task variable costs
 
@@ -43,16 +47,16 @@ Assuming a typical task: 1–2 hours, Claude Sonnet, ~100K input tokens, ~20K ou
 | Model choice | 5–10× between Haiku and Opus | Default to Claude Sonnet; allow per-repo override. |
 | Turn count | Linear with turns | `max_turns` cap (default 100, configurable 1–500). |
 | Cost budget | Hard stop at budget | `max_budget_usd` cap (configurable $0.01–$100). Agent stops when budget is reached regardless of remaining turns. |
-| Task duration | Sub-linear (compute is cheap; tokens dominate) | 8-hour max session timeout. |
+| Task duration | Sub-linear (compute is cheap; tokens dominate) | AgentCore: 8-hour service limit; orchestrator: 9-hour `executionTimeout`. |
 | Prompt caching | 50–90% token cost reduction | Enable by default; cache system prompts and repo context. |
 | Concurrency | Linear with parallel tasks | Per-user and system-wide concurrency limits. |
 
 ## Cost at scale
 
 | Scale | Tasks/month | Estimated monthly cost (infra + tasks) |
 |---|---|---|
-| Low (1 developer) | 30–60 | $150–500 |
-| Medium (small team) | 200–500 | $500–3,000 |
+| Low (1 developer) | 30–60 | $200–550 |
+| Medium (small team) | 200–500 | $550–3,000 |
 | High (org-wide) | 2,000–5,000 | $5,000–30,000 |
 
 These estimates assume Claude Sonnet with prompt caching enabled and average task complexity.
@@ -72,8 +76,8 @@ For multi-user deployments, cost should be attributable to individual users and
 |---|---|---|
 | Turn limit | `max_turns` per task | 100 |
 | Cost budget | `max_budget_usd` per task | None (unlimited) |
-| Session timeout | Orchestrator timeout | 8 hours |
-| Concurrency limit | Per-user atomic counter | 2 concurrent tasks |
+| Session timeout | Orchestrator timeout | 9 hours |
+| Concurrency limit | Per-user atomic counter | 3 concurrent tasks |
 | System concurrency | System-wide counter | Account-level AgentCore quota |
 
 ## Additional guardrails
@@ -85,7 +89,8 @@ For multi-user deployments, cost should be attributable to individual users and
 
 ## Reference
 
-- [COMPUTE.md  - Network architecture](./COMPUTE.md)  - VPC infrastructure cost breakdown.
-- [ORCHESTRATOR.md](./ORCHESTRATOR.md)  - Polling cost analysis.
-- [COMPUTE.md](./COMPUTE.md)  - Compute option billing models.
-- [OBSERVABILITY.md](./OBSERVABILITY.md)  - Cost-related metrics (`agent.cost_usd`, token usage).
+- [COMPUTE.md](./COMPUTE.md) -- Compute option billing models and network architecture.
+- [ORCHESTRATOR.md](./ORCHESTRATOR.md) -- Polling cost analysis.
+- [OBSERVABILITY.md](./OBSERVABILITY.md) -- Cost-related metrics (`agent.cost_usd`, token usage).
+- [Deployment guide](../guides/DEPLOYMENT_GUIDE.md) -- Deployment choices, scale-to-zero analysis, AWS services inventory.
+- [DEPLOYMENT_ROLES.md](./DEPLOYMENT_ROLES.md) -- Least-privilege IAM policies for deployment.