From c9cad806d42efd81ab319ff95438efa9cb587dee Mon Sep 17 00:00:00 2001
From: jariy17 <tjariy+jariy17@users.noreply.github.com>
Date: Thu, 15 Oct 2026 20:18:27 +0000
Subject: [PATCH 1/5] feat(project): add experimental Terraform backend

---
 bun.lock                                      |   3 +
 command.md                                    | 246 +----
 examples/terraform-poc/.gitignore             |   6 +
 examples/terraform-poc/README.md              |  77 ++
 .../terraform-poc/agentcore/agentcore.json    |  87 ++
 examples/terraform-poc/src/agent/main.py      |  93 ++
 .../terraform-poc/src/agent/requirements.txt  |   4 +
 examples/terraform-poc/src/tool/main.py       |   2 +
 package.json                                  |   1 +
 src/core/project/backends/terraform.test.ts   | 255 +++++
 src/core/project/backends/terraform.ts        | 324 ++++++
 .../project/backends/terraform/assets.test.ts | 113 ++
 src/core/project/backends/terraform/assets.ts | 294 ++++++
 .../backends/terraform/compiler.test.ts       | 353 +++++++
 .../project/backends/terraform/compiler.ts    | 969 ++++++++++++++++++
 src/core/project/backends/terraform/state.ts  | 111 ++
 src/core/project/index.tsx                    |   1 +
 src/core/project/manager.test.ts              | 190 +++-
 src/core/project/manager.tsx                  |  47 +-
 src/core/project/templates/project.ts         |  24 +-
 src/handlers/project/create/index.ts          |  34 +-
 src/handlers/project/deploy/index.ts          |   2 +-
 src/handlers/project/project.test.ts          |  35 +
 src/handlers/project/types.ts                 |   6 +-
 src/projectSchemas/project.test.ts            |   8 +
 src/projectSchemas/project.ts                 |   2 +-
 26 files changed, 3041 insertions(+), 246 deletions(-)
 create mode 100644 examples/terraform-poc/.gitignore
 create mode 100644 examples/terraform-poc/README.md
 create mode 100644 examples/terraform-poc/agentcore/agentcore.json
 create mode 100644 examples/terraform-poc/src/agent/main.py
 create mode 100644 examples/terraform-poc/src/agent/requirements.txt
 create mode 100644 examples/terraform-poc/src/tool/main.py
 create mode 100644 src/core/project/backends/terraform.test.ts
 create mode 100644 src/core/project/backends/terraform.ts
 create mode 100644 src/core/project/backends/terraform/assets.test.ts
 create mode 100644 src/core/project/backends/terraform/assets.ts
 create mode 100644 src/core/project/backends/terraform/compiler.test.ts
 create mode 100644 src/core/project/backends/terraform/compiler.ts
 create mode 100644 src/core/project/backends/terraform/state.ts

diff --git a/bun.lock b/bun.lock
index daf00c170f..f8e1da27a6 100644
--- a/bun.lock
+++ b/bun.lock
@@ -29,6 +29,7 @@
         "bedrock-agentcore": "^0.4.3",
         "cli-truncate": "^6.1.1",
         "commander": "^15.0.0",
+        "fflate": "^0.8.3",
         "handlebars": "^4.7.10",
         "ink": "^7.1.0",
         "ink-scroll-view": "^0.3.7",
@@ -878,6 +879,8 @@
 
     "fecha": ["fecha@4.2.3", "", {}, "sha512-OP2IUU6HeYKJi3i0z4A19kHMQoLVs4Hc+DPqqxI2h/DPZHTm/vjsfC6P0b4jCMy14XizLBqvndQ+UilD7707Jw=="],
 
+    "fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="],
+
     "file-entry-cache": ["file-entry-cache@8.0.0", "", { "dependencies": { "flat-cache": "^4.0.0" } }, "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ=="],
 
     "file-stream-rotator": ["file-stream-rotator@0.6.1", "", { "dependencies": { "moment": "^2.29.1" } }, "sha512-u+dBid4PvZw17PmDeRcNOtCP9CCK/9lRN2w+r1xIS7yOL9JFrIBKTvrYsxT4P0pGtThYTn++QS5ChHaUov3+zQ=="],
diff --git a/command.md b/command.md
index d62fe6d1a8..9e4489bb85 100644
--- a/command.md
+++ b/command.md
@@ -42,7 +42,6 @@ This reference was generated from `agentcore --help` for version `1.0.0-rc.5`.
       - [`agentcore add evaluator llm-as-a-judge`](#agentcore-add-evaluator-llm-as-a-judge)
       - [`agentcore add evaluator code-based`](#agentcore-add-evaluator-code-based)
     - [`agentcore add online-eval`](#agentcore-add-online-eval)
-    - [`agentcore add online-insight`](#agentcore-add-online-insight)
     - [`agentcore add config-bundle`](#agentcore-add-config-bundle)
     - [`agentcore add payment-manager`](#agentcore-add-payment-manager)
     - [`agentcore add payment-connector`](#agentcore-add-payment-connector)
@@ -153,14 +152,7 @@ This reference was generated from `agentcore --help` for version `1.0.0-rc.5`.
       - [`agentcore eval online-eval pause`](#agentcore-eval-online-eval-pause)
       - [`agentcore eval online-eval resume`](#agentcore-eval-online-eval-resume)
       - [`agentcore eval online-eval delete`](#agentcore-eval-online-eval-delete)
-    - [`agentcore eval online-insight`](#agentcore-eval-online-insight)
-      - [`agentcore eval online-insight create`](#agentcore-eval-online-insight-create)
-      - [`agentcore eval online-insight get`](#agentcore-eval-online-insight-get)
-      - [`agentcore eval online-insight list`](#agentcore-eval-online-insight-list)
-      - [`agentcore eval online-insight update`](#agentcore-eval-online-insight-update)
-      - [`agentcore eval online-insight pause`](#agentcore-eval-online-insight-pause)
-      - [`agentcore eval online-insight resume`](#agentcore-eval-online-insight-resume)
-      - [`agentcore eval online-insight delete`](#agentcore-eval-online-insight-delete)
+      - [`agentcore eval online-eval logs`](#agentcore-eval-online-eval-logs)
     - [`agentcore eval dataset`](#agentcore-eval-dataset)
       - [`agentcore eval dataset create`](#agentcore-eval-dataset-create)
       - [`agentcore eval dataset get`](#agentcore-eval-dataset-get)
@@ -174,11 +166,6 @@ This reference was generated from `agentcore --help` for version `1.0.0-rc.5`.
       - [`agentcore eval batch-evaluation get`](#agentcore-eval-batch-evaluation-get)
       - [`agentcore eval batch-evaluation list`](#agentcore-eval-batch-evaluation-list)
       - [`agentcore eval batch-evaluation stop`](#agentcore-eval-batch-evaluation-stop)
-    - [`agentcore eval batch-insights`](#agentcore-eval-batch-insights)
-      - [`agentcore eval batch-insights run`](#agentcore-eval-batch-insights-run)
-      - [`agentcore eval batch-insights get`](#agentcore-eval-batch-insights-get)
-      - [`agentcore eval batch-insights list`](#agentcore-eval-batch-insights-list)
-      - [`agentcore eval batch-insights stop`](#agentcore-eval-batch-insights-stop)
     - [`agentcore eval ondemand`](#agentcore-eval-ondemand)
       - [`agentcore eval ondemand evaluate`](#agentcore-eval-ondemand-evaluate)
       - [`agentcore eval ondemand simulate`](#agentcore-eval-ondemand-simulate)
@@ -256,6 +243,7 @@ create a new project
 **Options**
 
 - `--name <name>`: name of the project to create (required)
+- `--managed-by <managed-by>`: infrastructure backend (Terraform is an experimental AWSCC PoC) (default: "CDK")
 - `--template <template>`: the template to scaffold the Runtime from (default: "empty")
 - `--skip-install`: skip installing dependencies (npm install, uv sync) (default: false)
 - `--skip-git`: skip initializing a git repository (default: false)
@@ -266,15 +254,18 @@ create a new project
 agentcore dev [options]
 ```
 
-run the project locally for development
+test project changes: run Runtimes locally or deploy for Harnesses; --mode browser opens Agent Inspector.
 
 **Options**
 
-- `--agent <agent>`: Runtime to run
+- `--agent <agent>`: runtime or harness to run
+- `--ui-port <ui-port>`: port for the Agent Inspector web UI (browser mode)
+- `--mode <mode>`: how to run: browser (Agent Inspector web UI) or headless (runtime output or harness invoke guidance) (default: "headless")
 - `--port <port>`: port for the development server
 - `--no-traces`: disable local OTEL trace collection
-- `--mode <mode>`: how to run: browser (Agent Inspector web UI) or headless (agents stream to the terminal) (default: "headless")
-- `--ui-port <ui-port>`: port for the Agent Inspector web UI (browser mode)
+- `--target <target>`: name of the aws-targets.json entry to deploy; the default target is created automatically from your AWS account and region on first deploy (default: "default")
+- `--yes`: confirm removing the target's stack when the project declares nothing to deploy (default: false)
+- `--skip-deploy`: skip deployment and use the deployed harnesses (default: false)
 
 ### `agentcore deploy`
 
@@ -287,7 +278,7 @@ deploy the project to AWS
 **Options**
 
 - `--target <target>`: name of the aws-targets.json entry to deploy; the default target is created automatically from your AWS account and region on first deploy (default: "default")
-- `--yes`: confirm removing the target's stack when the project declares nothing to deploy (default: false)
+- `--yes`: confirm removing the target's resources when the project declares nothing to deploy (default: false)
 
 ### `agentcore invoke`
 
@@ -813,34 +804,12 @@ add an online evaluation config to the current project (not available in China r
 - `--endpoint <endpoint>`: the agent endpoint qualifier to scope monitoring to (requires --agent)
 - `--log-group-name <log-group-name...>`: CloudWatch log group name(s) for custom data sources (1-5; mutually exclusive with --agent)
 - `--service-name <service-name...>`: service name(s) to filter traces for custom data sources (requires --log-group-name)
-- `--evaluators <evaluators...>`: evaluator name(s), Builtin.\* IDs, or ARNs to apply
+- `--evaluators <evaluators...>`: evaluator name(s), Builtin.\* IDs, or ARNs to apply (required)
 - `--sampling-rate <sampling-rate>`: percentage of sessions to sample (0.01-100) (required)
 - `--description <description>`: a description of the config's monitoring purpose
 - `--enable-on-create <enable-on-create>`: enable evaluation immediately after deploy (default true; pass false to add it paused)
 - `--tags <tags...>`: tags as repeated key=value entries or a JSON object
 
-#### `agentcore add online-insight`
-
-```text
-agentcore add online-insight [options]
-```
-
-add an online insight config to the current project (not available in China regions)
-
-**Options**
-
-- `--name <name>`: the name of the online insight config (required)
-- `--agent <agent>`: Runtime name whose traffic to sample (mutually exclusive with --log-group-name)
-- `--endpoint <endpoint>`: the agent endpoint qualifier to scope monitoring to (requires --agent)
-- `--log-group-name <log-group-name...>`: CloudWatch log group name(s) for custom data sources (1-5; mutually exclusive with --agent)
-- `--service-name <service-name...>`: service name(s) to filter traces for custom data sources (requires --log-group-name)
-- `--insight <insight...>`: insight ID(s) to apply: Builtin.Insight.\* identifiers or full ARNs (required)
-- `--clustering-frequency <clustering-frequency...>`: insight clustering cadence(s): DAILY, WEEKLY, MONTHLY
-- `--sampling-rate <sampling-rate>`: percentage of sessions to sample (0.01-100) (required)
-- `--description <description>`: a description of the config's monitoring purpose
-- `--enable-on-create <enable-on-create>`: enable insights immediately after deploy (default true; pass false to add it paused)
-- `--tags <tags...>`: tags as repeated key=value entries or a JSON object
-
 #### `agentcore add config-bundle`
 
 ```text
@@ -953,7 +922,12 @@ build the project's deployable artifacts
 agentcore migrate [options]
 ```
 
-migrate an AgentCore CLI v0 project to the current project format
+migrate an AgentCore CLI v0 project to the current project format, keeping its deployed resources
+
+**Options**
+
+- `--target <target>`: the deployment target to migrate (required when the project is deployed to several)
+- `--yes`: apply the changes without asking, when they are ready (default: false)
 
 ## Resource commands
 
@@ -2306,119 +2280,23 @@ delete an online evaluation config by ID
 
 - `--id <id>`: the ID of the online evaluation config to delete (required)
 
-#### `agentcore eval online-insight`
-
-```text
-agentcore eval online-insight [options] [command]
-```
-
-manage AgentCore online insight configs
-
-##### `agentcore eval online-insight create`
-
-```text
-agentcore eval online-insight create [options]
-```
-
-create an online insight config
-
-**Options**
-
-- `--name <name>`: the name of the online insight config (required)
-- `--role-arn <role-arn>`: IAM role the online insight assumes (required)
-- `--agent <agent>`: harness ID or Runtime ID whose traffic to sample
-- `--endpoint <endpoint>`: the agent endpoint qualifier to scope monitoring to (default DEFAULT)
-- `--data-source-config <data-source-config>`: the traces to evaluate (JSON DataSourceConfig; inline, file://&lt;path&gt;, or - for stdin), as an alternative to --agent
-- `--insight <insight...>`: insight ID(s) to apply: Builtin.Insight.\* identifiers or full ARNs (required)
-- `--clustering-frequency <clustering-frequency...>`: insight clustering cadence(s): DAILY, WEEKLY, MONTHLY
-- `--sampling-rate <sampling-rate>`: percentage of sessions to sample (0.01-100) (required)
-- `--session-timeout-minutes <session-timeout-minutes>`: minutes of inactivity before a session is considered complete (1-1440, default 15)
-- `--filters <filters>`: trace filters (JSON Filter[]; inline, file://&lt;path&gt;, or - for stdin)
-- `--enable-on-create <enable-on-create>`: whether to enable evaluation immediately (default true; pass false to create it paused)
-- `--description <description>`: a description of the config's monitoring purpose
-
-##### `agentcore eval online-insight get`
-
-```text
-agentcore eval online-insight get [options]
-```
-
-get an online insight config by ID
-
-**Options**
-
-- `--id <id>`: the ID of the online insight config (required)
-
-##### `agentcore eval online-insight list`
-
-```text
-agentcore eval online-insight list [options]
-```
-
-list online insight configs
-
-**Options**
-
-- `--next-token <next-token>`: pagination token returned by a previous request
-- `--max-results <max-results>`: maximum number of items to return
-
-##### `agentcore eval online-insight update`
-
-```text
-agentcore eval online-insight update [options]
-```
-
-update an online insight config
-
-**Options**
-
-- `--id <id>`: the ID of the online insight config to update (required)
-- `--sampling-rate <sampling-rate>`: percentage of sessions to sample (0.01-100)
-- `--session-timeout-minutes <session-timeout-minutes>`: minutes of inactivity before a session is considered complete (1-1440)
-- `--filters <filters>`: trace filters (JSON Filter[]; inline, file://&lt;path&gt;, or - for stdin)
-- `--insight <insight...>`: insight ID(s) to apply (replaces the existing list): Builtin.Insight.\* or ARN
-- `--clustering-frequency <clustering-frequency...>`: insight clustering cadence(s) (replaces the existing set): DAILY, WEEKLY, MONTHLY
-- `--agent <agent>`: repoint at a different Runtime ID
-- `--endpoint <endpoint>`: re-scope monitoring to a different agent endpoint qualifier
-- `--clear-endpoint <clear-endpoint>`: reset the endpoint scope to the default qualifier (pass true)
-- `--data-source-config <data-source-config>`: replace the traces to evaluate (JSON DataSourceConfig; inline, file://&lt;path&gt;, or - for stdin)
-- `--role-arn <role-arn>`: replace the IAM role the online insight assumes
-
-##### `agentcore eval online-insight pause`
-
-```text
-agentcore eval online-insight pause [options]
-```
-
-pause an online insight config
-
-**Options**
-
-- `--id <id>`: the ID of the online insight config to pause (required)
-
-##### `agentcore eval online-insight resume`
-
-```text
-agentcore eval online-insight resume [options]
-```
-
-resume a paused online insight config
-
-**Options**
-
-- `--id <id>`: the ID of the online insight config to resume (required)
-
-##### `agentcore eval online-insight delete`
+##### `agentcore eval online-eval logs`
 
 ```text
-agentcore eval online-insight delete [options]
+agentcore eval online-eval logs [options]
 ```
 
-delete an online insight config by ID
+stream or search online-eval logs
 
 **Options**
 
-- `--id <id>`: the ID of the online insight config to delete (required)
+- `--id <id>`: the ID of the online-eval resource (required)
+- `--since <since>`: search window start: "5m", "1h", ISO 8601, epoch ms, or "now"
+- `--until <until>`: search window end: "5m", "1h", ISO 8601, epoch ms, or "now"
+- `--tail`: tail new log records (default: false)
+- `--level <level>`: filter by log level (error, warn, info, debug)
+- `--query <query>`: CloudWatch Logs filter pattern
+- `--limit <limit>`: maximum number of log records to return in search mode
 
 #### `agentcore eval dataset`
 
@@ -2573,7 +2451,7 @@ replay a dataset against a Runtime, then batch-evaluate the resulting sessions
 agentcore eval batch-evaluation get [options]
 ```
 
-get a batch evaluation by ID, with CloudWatch-backed results when available
+get a batch evaluation by ID, with CloudWatch-backed results and errors when available
 
 **Options**
 
@@ -2605,74 +2483,6 @@ stop a running batch evaluation
 
 - `--id <id>`: the ID of the batch evaluation to stop (required)
 
-#### `agentcore eval batch-insights`
-
-```text
-agentcore eval batch-insights [options] [command]
-```
-
-run and inspect AgentCore batch insights
-
-##### `agentcore eval batch-insights run`
-
-```text
-agentcore eval batch-insights run [options]
-```
-
-start an asynchronous batch insights run over existing sessions
-
-**Options**
-
-- `--name <name>`: batch insights name (must be unique in the account) (required)
-- `--description <description>`: optional description
-- `--kms-key-arn <kms-key-arn>`: KMS key to encrypt insights data at rest
-- `--agent <agent>`: harness ID or Runtime ID whose sessions to use
-- `--online-eval <online-eval>`: use sessions an online-eval config already sampled
-- `--data-source-config <data-source-config>`: the traces to read (JSON DataSourceConfig); escape hatch
-- `--endpoint <endpoint>`: Runtime endpoint qualifier (default DEFAULT; only with --agent)
-- `--start-time <start-time>`: window start (ISO-8601, with --end-time)
-- `--end-time <end-time>`: window end (ISO-8601, with --start-time)
-- `--session-ids <session-ids...>`: specific session IDs (only with --agent)
-- `--insight <insight...>`: insight ID(s) to run
-- `--evaluators <evaluators...>`: optional evaluator ID(s) to run alongside the insights
-
-##### `agentcore eval batch-insights get`
-
-```text
-agentcore eval batch-insights get [options]
-```
-
-get a batch insights run and its reports by ID
-
-**Options**
-
-- `--id <id>`: the ID of the batch insights run (required)
-
-##### `agentcore eval batch-insights list`
-
-```text
-agentcore eval batch-insights list [options]
-```
-
-list batch insights runs
-
-**Options**
-
-- `--next-token <next-token>`: pagination token returned by a previous request
-- `--max-results <max-results>`: maximum number of batch insights runs to return
-
-##### `agentcore eval batch-insights stop`
-
-```text
-agentcore eval batch-insights stop [options]
-```
-
-stop a running batch insights run
-
-**Options**
-
-- `--id <id>`: the ID of the batch insights run to stop (required)
-
 #### `agentcore eval ondemand`
 
 ```text
diff --git a/examples/terraform-poc/.gitignore b/examples/terraform-poc/.gitignore
new file mode 100644
index 0000000000..7903bd9b7b
--- /dev/null
+++ b/examples/terraform-poc/.gitignore
@@ -0,0 +1,6 @@
+agentcore/terraform/
+agentcore/.cli/
+agentcore/aws-targets.json
+.venv/
+__pycache__/
+*.pyc
diff --git a/examples/terraform-poc/README.md b/examples/terraform-poc/README.md
new file mode 100644
index 0000000000..19e050490c
--- /dev/null
+++ b/examples/terraform-poc/README.md
@@ -0,0 +1,77 @@
+# Terraform backend PoC
+
+This example exercises an experimental Terraform deployment backend for a small AgentCore project:
+
+- A Python CodeZip runtime and memory with a semantic strategy.
+- An IAM-authenticated MCP gateway backed by a Python Lambda tool.
+- A policy engine associated with the gateway.
+- Online evaluations using `Builtin.Helpfulness`.
+
+The backend generates Terraform JSON configuration from `agentcore/agentcore.json`. AgentCore resources use AWSCC 1.106.0, except for gateway targets: that release does not expose a gateway target resource, so the example uses AWS provider 6.69.0 for its Lambda target. The AWS provider also manages IAM, S3, Lambda, and logs. Resource creation is owned by Terraform.
+
+The example has been packaged reproducibly, validated against both pinned providers, and planned with Terraform 1.16.6 (25 resources). Live deployment, invocation, policy enforcement, evaluation results, updates, and teardown remain unverified. The steps below describe the experiment to run.
+
+## Prerequisites
+
+- Build this branch of the CLI with `bun install --frozen-lockfile` and `bun run build`.
+- Install Terraform 1.16.6 and `uv`, and make both available on `PATH`.
+- Configure AWS credentials for a disposable development account and an AgentCore-supported region.
+- Ensure the account can invoke the Bedrock model used by the example, `us.amazon.nova-lite-v1:0`. To select another model, add a `MODEL_ID` entry to the runtime's `envVars`.
+
+This example creates billable resources and enables online evaluation at 100% sampling. Use it for a bounded experiment and tear it down afterward. The sample `permit(principal, action, resource);` policy permits all gateway actions to authenticated callers; replace it with your intended policy before using the configuration outside this example.
+
+## Deploy the example
+
+Copy this directory outside the repository before using it so configuration changes and deployment state remain separate from the checked-in fixture. Set `CLI` to the absolute path of this branch's `dist/index.js`.
+
+```sh
+export CLI=/absolute/path/to/agentcore-cli/dist/index.js
+export AWS_PROFILE=your-development-profile
+export AWS_REGION=us-west-2
+cd /path/to/your/copied/terraform-poc
+
+node "$CLI" build
+node "$CLI" deploy --region "$AWS_REGION" --json
+node "$CLI" status --region "$AWS_REGION" --json
+```
+
+The default deployment target is recorded in `agentcore/aws-targets.json`. Terraform configuration, asset archives, dependency locks, and local state live beneath `agentcore/terraform/`. Keep that directory private and preserve it until teardown completes: Terraform state can contain configuration values and is needed to manage the resources. This PoC uses local state for one operator; shared remote state and CDK-to-Terraform migration are outside its scope.
+
+Deploy also follows the existing CLI setting for enabling CloudWatch Transaction Search. That setup is an account-level telemetry prerequisite, runs outside Terraform, and is not reverted when this example is destroyed. A setup warning must be resolved before treating online evaluation as verified.
+
+To start a new project instead:
+
+```sh
+node "$CLI" create --name MyTerraformProject --template empty --managed-by Terraform
+```
+
+Use the existing `agentcore add` commands to populate the project. The backend validates its supported subset before deployment and reports unsupported resource types or settings. A Terraform project is not a promise of coverage for every `agentcore.json` option.
+
+## Exercise the deployed resources
+
+```sh
+node "$CLI" invoke --runtime Agent --payload '{"operation":"ping"}'
+node "$CLI" invoke --runtime Agent --payload '{"operation":"memory","message":"I prefer green tea."}'
+node "$CLI" invoke --runtime Agent --payload '{"operation":"tools"}'
+node "$CLI" invoke --runtime Agent --payload '{"operation":"echo","message":"Hello from Terraform."}'
+node "$CLI" invoke --runtime Agent --payload '{"prompt":"How can I keep a cup of tea warm?"}'
+```
+
+The memory operation writes an event and lists session events. Semantic extraction is asynchronous. The gateway operations use the runtime's IAM credentials to discover and invoke the Lambda tool. The final operation invokes a Strands agent and produces model telemetry for online evaluation; an active evaluation configuration alone does not establish that evaluation results are being produced.
+
+To examine enforcement, change the sample policy to `forbid(principal, action, resource);`, redeploy, and check that calling the tool is denied. Set the policy's `enforcementMode` to `LOG_ONLY`, redeploy, and check its observed behavior before restoring the original policy. The gateway's policy-engine mode remains `ENFORCE`; it is a separate setting.
+
+The compiler also maps the statement through AWSCC's `definition.policy.statement` input. A valid Dogwood statement can be supplied there, but schema support and a successful deployment of a particular Dogwood policy are separate checks.
+
+## Updates and teardown
+
+Change a runtime source file or a supported configuration value and run `deploy` again. Repeating a deployment with unchanged inputs should produce a no-change plan. Stable Terraform addresses are based on resource names; renaming a resource can replace it.
+
+Removing a project resource and deploying reconciles its Terraform resources. To tear down the entire example:
+
+```sh
+node "$CLI" remove all --yes
+node "$CLI" deploy --yes --region "$AWS_REGION" --json
+```
+
+Keep the generated directory after a failed apply or teardown so the operation can be retried. Do not edit `managedBy` on an existing CDK deployment to attempt a migration.
diff --git a/examples/terraform-poc/agentcore/agentcore.json b/examples/terraform-poc/agentcore/agentcore.json
new file mode 100644
index 0000000000..e2bc247086
--- /dev/null
+++ b/examples/terraform-poc/agentcore/agentcore.json
@@ -0,0 +1,87 @@
+{
+  "name": "TerraformPoc",
+  "version": 2,
+  "managedBy": "Terraform",
+  "runtimes": [
+    {
+      "name": "Agent",
+      "build": "CodeZip",
+      "runtimeVersion": "PYTHON_3_12",
+      "entrypoint": "main.py",
+      "codeLocation": "src/agent",
+      "instrumentation": { "enableOtel": true }
+    }
+  ],
+  "memories": [
+    {
+      "name": "Memory",
+      "eventExpiryDuration": 7,
+      "strategies": [
+        {
+          "type": "SEMANTIC",
+          "name": "Facts",
+          "namespaceTemplates": ["/users/{actorId}/facts"]
+        }
+      ]
+    }
+  ],
+  "policyEngines": [
+    {
+      "name": "Rules",
+      "policies": [
+        {
+          "name": "AllowEcho",
+          "statement": "permit(principal, action, resource);",
+          "validationMode": "IGNORE_ALL_FINDINGS",
+          "enforcementMode": "ACTIVE"
+        }
+      ]
+    }
+  ],
+  "agentCoreGateways": [
+    {
+      "name": "tools",
+      "authorizerType": "AWS_IAM",
+      "enableSemanticSearch": false,
+      "policyEngineConfiguration": {
+        "policyEngineName": "Rules",
+        "mode": "ENFORCE"
+      },
+      "targets": [
+        {
+          "name": "echo",
+          "targetType": "lambda",
+          "compute": {
+            "host": "Lambda",
+            "pythonVersion": "PYTHON_3_12",
+            "implementation": {
+              "language": "Python",
+              "path": "src/tool",
+              "handler": "main.handler"
+            }
+          },
+          "toolDefinitions": [
+            {
+              "name": "echo",
+              "description": "Return the supplied message.",
+              "inputSchema": {
+                "type": "object",
+                "properties": { "message": { "type": "string" } },
+                "required": ["message"]
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "onlineEvalConfigs": [
+    {
+      "name": "Quality",
+      "agent": "Agent",
+      "evaluators": ["Builtin.Helpfulness"],
+      "samplingRate": 100,
+      "enableOnCreate": true
+    }
+  ]
+}
diff --git a/examples/terraform-poc/src/agent/main.py b/examples/terraform-poc/src/agent/main.py
new file mode 100644
index 0000000000..4d41869a2a
--- /dev/null
+++ b/examples/terraform-poc/src/agent/main.py
@@ -0,0 +1,93 @@
+"""Small agent with deterministic memory/gateway probes and a model-backed path."""
+
+import json
+import os
+from datetime import datetime, timezone
+from urllib.request import Request, urlopen
+
+import boto3
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+from strands import Agent
+from strands.models import BedrockModel
+
+app = BedrockAgentCoreApp()
+
+
+def call_gateway(method, params=None):
+    session = boto3.Session()
+    endpoint = os.environ["AGENTCORE_GATEWAY_TOOLS_URL"]
+    body = json.dumps(
+        {"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}}
+    ).encode()
+    request = AWSRequest(
+        method="POST",
+        url=endpoint,
+        data=body,
+        headers={"Content-Type": "application/json", "Accept": "application/json"},
+    )
+    credentials = session.get_credentials().get_frozen_credentials()
+    SigV4Auth(credentials, "bedrock-agentcore", session.region_name).add_auth(request)
+    with urlopen(
+        Request(endpoint, data=body, headers=dict(request.headers), method="POST"),
+        timeout=30,
+    ) as response:
+        return json.loads(response.read())
+
+
+@app.entrypoint
+def invoke(payload, context):
+    operation = payload.get("operation", "agent")
+    if operation == "ping":
+        return {"message": "Terraform runtime is responding."}
+    if operation == "memory":
+        client = boto3.client("bedrock-agentcore")
+        memory_id = os.environ["MEMORY_MEMORY_ID"]
+        actor_id = "terraform-poc"
+        session_id = getattr(context, "session_id", None) or "terraform-poc"
+        event = client.create_event(
+            memoryId=memory_id,
+            actorId=actor_id,
+            sessionId=session_id,
+            eventTimestamp=datetime.now(timezone.utc),
+            payload=[
+                {
+                    "conversational": {
+                        "content": {"text": payload.get("message", "I prefer green tea.")},
+                        "role": "USER",
+                    }
+                }
+            ],
+        )
+        events = client.list_events(
+            memoryId=memory_id, actorId=actor_id, sessionId=session_id
+        )
+        return {
+            "eventId": event["event"]["eventId"],
+            "eventCount": len(events.get("events", [])),
+        }
+    if operation == "tools":
+        return call_gateway("tools/list")
+    if operation == "echo":
+        return call_gateway(
+            "tools/call",
+            {
+                "name": "echo___echo",
+                "arguments": {"message": payload.get("message", "Hello from Terraform.")},
+            },
+        )
+    if operation != "agent":
+        raise ValueError("Expected operation: ping, memory, tools, echo, or agent.")
+    agent = Agent(
+        model=BedrockModel(
+            model_id=os.environ.get("MODEL_ID", "us.amazon.nova-lite-v1:0")
+        ),
+        system_prompt="Give a concise, helpful answer to the user's question.",
+    )
+    result = agent(payload.get("prompt", "How can I keep a cup of tea warm?"))
+    return {"response": str(result)}
+
+
+if __name__ == "__main__":
+    app.run()
diff --git a/examples/terraform-poc/src/agent/requirements.txt b/examples/terraform-poc/src/agent/requirements.txt
new file mode 100644
index 0000000000..1f8d8287fa
--- /dev/null
+++ b/examples/terraform-poc/src/agent/requirements.txt
@@ -0,0 +1,4 @@
+aws-opentelemetry-distro ~= 0.21.0
+bedrock-agentcore[strands-agents] >= 1.18.1, < 2.0.0
+botocore[crt] ~= 1.43.0
+strands-agents >= 1.15.0, < 2.0.0
diff --git a/examples/terraform-poc/src/tool/main.py b/examples/terraform-poc/src/tool/main.py
new file mode 100644
index 0000000000..d7fd034246
--- /dev/null
+++ b/examples/terraform-poc/src/tool/main.py
@@ -0,0 +1,2 @@
+def handler(event, context):
+    return {"message": event.get("message", "")}
diff --git a/package.json b/package.json
index 426442a5b6..6fc786a4b5 100644
--- a/package.json
+++ b/package.json
@@ -90,6 +90,7 @@
     "bedrock-agentcore": "^0.4.3",
     "cli-truncate": "^6.1.1",
     "commander": "^15.0.0",
+    "fflate": "^0.8.3",
     "handlebars": "^4.7.10",
     "ink": "^7.1.0",
     "ink-scroll-view": "^0.3.7",
diff --git a/src/core/project/backends/terraform.test.ts b/src/core/project/backends/terraform.test.ts
new file mode 100644
index 0000000000..4ccfb91440
--- /dev/null
+++ b/src/core/project/backends/terraform.test.ts
@@ -0,0 +1,255 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Project, ProjectEvent } from "../../../handlers/project/types";
+import type { ProcessRunner, RunProcessOptions } from "../../../io";
+import { ProjectSpecSchema } from "../../../projectSchemas/project";
+import { createSilentLogger } from "../../../testing";
+import { TerraformBackend, type TerraformBackendConfig } from "./terraform";
+import { TerraformState } from "./terraform/state";
+
+const TARGET = { name: "default", account: "111122223333", region: "us-east-1" } as const;
+const directories: string[] = [];
+afterEach(async () => {
+  await Promise.all(
+    directories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })),
+  );
+});
+
+async function project(): Promise<Project> {
+  const rootPath = await mkdtemp(join(tmpdir(), "agentcore-terraform-"));
+  directories.push(rootPath);
+  return {
+    name: "example",
+    rootPath,
+    spec: ProjectSpecSchema.parse({
+      name: "example",
+      version: 2,
+      managedBy: "Terraform",
+      memories: [{ name: "memory", eventExpiryDuration: 30 }],
+    }),
+  };
+}
+
+async function drain<T>(events: AsyncGenerator<ProjectEvent, T>): Promise<T> {
+  for (;;) {
+    const next = await events.next();
+    if (next.done) return next.value;
+  }
+}
+
+function backend(overrides: Partial<TerraformBackendConfig> = {}) {
+  return new TerraformBackend({
+    logger: createSilentLogger(),
+    checkTool: async () => {},
+    runner: async () => {},
+    resolveCredentials: async () => async () => ({
+      accessKeyId: "test-key",
+      secretAccessKey: "test-secret",
+      sessionToken: "test-session",
+    }),
+    resolveAccount: async () => TARGET.account,
+    packageAssets: async () => ({ runtimes: {}, gatewayTargets: {} }),
+    ...overrides,
+  });
+}
+
+const input = { target: TARGET, confirmTeardown: async () => true };
+
+describe("Terraform lifecycle", () => {
+  test("build validates locally without resolving AWS credentials", async () => {
+    const p = await project();
+    const commands: string[][] = [];
+    const b = backend({
+      runner: async (command) => {
+        commands.push(command);
+      },
+      resolveCredentials: async () => {
+        throw new Error("unexpected credential resolution");
+      },
+    });
+    await drain(b.build(p));
+    expect(commands.map((command) => command[1])).toEqual(["init", "validate"]);
+    expect(commands[0]).toContain("-backend=false");
+    const compiled = await readFile(
+      join(new TerraformState(p, "build").directory, "main.tf.json"),
+      "utf8",
+    );
+    expect(compiled).toContain("000000000000");
+  });
+
+  test("applies the saved plan and resolves resources from target state", async () => {
+    const p = await project();
+    const calls: { command: string[]; options: RunProcessOptions }[] = [];
+    const runner: ProcessRunner = async (command, options) => {
+      calls.push({ command, options });
+      if (command[1] === "apply") {
+        await writeFile(
+          join(options.cwd, "terraform.tfstate"),
+          JSON.stringify({
+            resources: [{ mode: "managed" }],
+            outputs: {
+              memory_arn: {
+                value: "arn:aws:bedrock-agentcore:us-east-1:111122223333:memory/example-123",
+              },
+              project_resources: {
+                value: [{ resourceType: "memory", name: "memory", id: "example-123" }],
+              },
+            },
+          }),
+        );
+      }
+    };
+    const b = backend({ runner });
+    const result = await drain(b.deploy(p, input));
+    expect(calls.map(({ command }) => command[1])).toEqual(["init", "validate", "plan", "apply"]);
+    expect(calls.at(-1)!.command.at(-1)).toBe("deployment.tfplan");
+    expect(calls[2]!.command).toContain("-out=deployment.tfplan");
+    expect(calls.every(({ options }) => options.env?.AWS_SESSION_TOKEN === "test-session")).toBe(
+      true,
+    );
+    expect(result.outputs.memory_arn).toContain(":memory/");
+    expect(await b.resolveProjectResources(p, input)).toEqual([
+      { resourceType: "memory", name: "memory", deploymentState: "deployed", id: "example-123" },
+    ]);
+    expect(
+      existsSync(join(new TerraformState(p, TARGET).directory, ".agentcore-operation.lock")),
+    ).toBe(false);
+  });
+
+  test("does not invoke Terraform when credentials belong to another account", async () => {
+    const p = await project();
+    let invoked = false;
+    const b = backend({
+      resolveAccount: async () => "999900001111",
+      runner: async () => {
+        invoked = true;
+      },
+    });
+    await expect(drain(b.deploy(p, input))).rejects.toThrow("expects AWS account");
+    expect(invoked).toBe(false);
+  });
+
+  test.each(["init", "validate", "plan", "apply"])(
+    "preserves state and releases lock after %s fails",
+    async (failure) => {
+      const p = await project();
+      const state = new TerraformState(p, TARGET);
+      await mkdir(state.directory, { recursive: true });
+      const stateText = JSON.stringify({ resources: [{ mode: "managed" }], outputs: {} });
+      await writeFile(join(state.directory, "terraform.tfstate"), stateText);
+      const calls: string[] = [];
+      const b = backend({
+        runner: async (command) => {
+          calls.push(command[1]!);
+          if (command[1] === failure) throw new Error("simulated failure");
+        },
+      });
+      await expect(drain(b.deploy(p, input))).rejects.toThrow("simulated failure");
+      expect(await readFile(join(state.directory, "terraform.tfstate"), "utf8")).toBe(stateText);
+      expect(existsSync(join(state.directory, ".agentcore-operation.lock"))).toBe(false);
+      expect(calls.at(-1)).toBe(failure);
+    },
+  );
+
+  test("an empty project requires confirmation even after a partial apply without outputs", async () => {
+    const p = await project();
+    p.spec.memories = [];
+    const state = new TerraformState(p, TARGET);
+    await mkdir(state.directory, { recursive: true });
+    await writeFile(
+      join(state.directory, "terraform.tfstate"),
+      JSON.stringify({
+        resources: [{ mode: "managed" }],
+        outputs: {},
+      }),
+    );
+    let invoked = false;
+    const b = backend({
+      runner: async () => {
+        invoked = true;
+      },
+    });
+    await expect(
+      drain(b.deploy(p, { target: TARGET, confirmTeardown: async () => false })),
+    ).rejects.toThrow("cancelled");
+    expect(invoked).toBe(false);
+  });
+
+  test("refuses to adopt a recorded CDK deployment", async () => {
+    const p = await project();
+    await mkdir(join(p.rootPath, "agentcore", ".cli"), { recursive: true });
+    await writeFile(
+      join(p.rootPath, "agentcore", ".cli", "deployed-state.json"),
+      JSON.stringify({
+        targets: { default: { resources: { stackName: "existing-stack" } } },
+      }),
+    );
+    let packaged = false;
+    const b = backend({
+      packageAssets: async () => {
+        packaged = true;
+        return { runtimes: {}, gatewayTargets: {} };
+      },
+    });
+    await expect(drain(b.deploy(p, input))).rejects.toThrow(
+      "automatic migration or adoption is not supported",
+    );
+    expect(packaged).toBe(false);
+  });
+
+  test("isolates state by account and region and excludes removed declarations", async () => {
+    const p = await project();
+    const state = new TerraformState(p, TARGET);
+    await mkdir(state.directory, { recursive: true });
+    await writeFile(
+      join(state.directory, "terraform.tfstate"),
+      JSON.stringify({
+        outputs: {
+          project_resources: { value: [{ resourceType: "memory", name: "memory", id: "old" }] },
+        },
+      }),
+    );
+    const b = backend();
+    expect(
+      await b.resolveProjectResources(p, { target: { ...TARGET, region: "us-west-2" } }),
+    ).toEqual([{ resourceType: "memory", name: "memory", deploymentState: "local-only" }]);
+    p.spec.memories = [];
+    expect(await b.resolveProjectResources(p, input)).toEqual([]);
+  });
+
+  test("exclusive lock covers the whole operation", async () => {
+    const p = await project();
+    const state = new TerraformState(p, TARGET);
+    const unlock = await state.lock();
+    try {
+      await expect(drain(backend().deploy(p, input))).rejects.toThrow("Another operation owns");
+    } finally {
+      await unlock();
+    }
+  });
+
+  test.each([true, false])(
+    "honors transactionSearch=%s after a successful plan",
+    async (enabled) => {
+      const p = await project();
+      const calls: string[] = [];
+      const b = backend({
+        runner: async (command) => {
+          calls.push(command[1]!);
+        },
+        enableTransactionSearch: async () => {
+          calls.push("transaction-search");
+        },
+      });
+      await drain(b.deploy(p, { ...input, transactionSearch: enabled }));
+      expect(calls).toEqual(
+        enabled
+          ? ["init", "validate", "plan", "transaction-search", "apply"]
+          : ["init", "validate", "plan", "apply"],
+      );
+    },
+  );
+});
diff --git a/src/core/project/backends/terraform.ts b/src/core/project/backends/terraform.ts
new file mode 100644
index 0000000000..53b26505c4
--- /dev/null
+++ b/src/core/project/backends/terraform.ts
@@ -0,0 +1,324 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { ProjectStateError } from "../../../errors";
+import type {
+  DeployResult,
+  Project,
+  ProjectEvent,
+  ResolvedDeployedResource,
+  ResolvedProjectResource,
+} from "../../../handlers/project/types";
+import {
+  atomicWrite,
+  createLineSplitter,
+  FsReadWriteJson,
+  requireTool,
+  runProcess,
+  type ProcessRunner,
+  type ReadWriteJson,
+} from "../../../io";
+import type { Logger } from "../../../logging";
+import type { AwsDeploymentTarget } from "../../../projectSchemas/aws-targets";
+import { withOutputEvents } from "../events";
+import type { TransactionSearchEnabler } from "./cdk";
+import { readDeployedState, stackReferenceOf } from "./cdk/deployedState";
+import { resolveAwsAccount, type AccountResolver } from "./cdk/environment";
+import {
+  createCdkCredentialResolver,
+  type CdkCredentialProvider,
+  type CdkCredentialResolver,
+} from "./cdk/toolkit";
+import { TerraformAssetPackager, type TerraformAssetBuilder } from "./terraform/assets";
+import { declaredResources, TerraformCompiler } from "./terraform/compiler";
+import { TerraformState } from "./terraform/state";
+import type {
+  DeployBackendInput,
+  ProjectBackend,
+  ResolveDeployedResourcesBackendInput,
+  ResolveProjectResourcesBackendInput,
+} from "./types";
+
+export type TerraformBackendConfig = {
+  logger: Logger;
+  runner?: ProcessRunner;
+  checkTool?: typeof requireTool;
+  json?: ReadWriteJson;
+  resolveCredentials?: CdkCredentialResolver;
+  resolveAccount?: AccountResolver;
+  packageAssets?: TerraformAssetBuilder;
+  enableTransactionSearch?: TransactionSearchEnabler;
+};
+
+/** Experimental backend: Terraform owns all resources and keeps local state per deployment target. */
+export class TerraformBackend implements ProjectBackend {
+  private readonly runner: ProcessRunner;
+  private readonly checkTool: typeof requireTool;
+  private readonly json: ReadWriteJson;
+  private readonly resolveCredentials: CdkCredentialResolver;
+  private readonly resolveAccount: AccountResolver;
+  private readonly packageAssets: TerraformAssetBuilder;
+  private readonly compiler = new TerraformCompiler();
+
+  constructor(private readonly config: TerraformBackendConfig) {
+    this.runner = config.runner ?? runProcess;
+    this.checkTool = config.checkTool ?? requireTool;
+    this.json = config.json ?? new FsReadWriteJson({ logger: config.logger });
+    this.resolveCredentials =
+      config.resolveCredentials ?? createCdkCredentialResolver(config.logger);
+    this.resolveAccount = config.resolveAccount ?? resolveAwsAccount;
+    const packager = new TerraformAssetPackager(this.runner, this.checkTool);
+    this.packageAssets = config.packageAssets ?? packager.build.bind(packager);
+  }
+
+  async *build(project: Project): AsyncGenerator<ProjectEvent, void> {
+    this.compiler.preflight(project);
+    await this.checkTool(
+      "terraform",
+      "Install Terraform: https://developer.hashicorp.com/terraform/install",
+    );
+    const state = new TerraformState(project, "build");
+    const unlock = await state.lock();
+    try {
+      yield {
+        type: "step",
+        message: "Building Terraform configuration for validation (placeholder account and region)",
+      };
+      yield* this.generate(
+        project,
+        {
+          name: "build",
+          account: "000000000000",
+          region: "us-west-2",
+        },
+        state,
+      );
+      const env = this.environment(state);
+      yield* this.execute(["init", "-backend=false", "-input=false", "-no-color"], state, env);
+      yield* this.execute(["validate", "-no-color"], state, env);
+    } finally {
+      await unlock();
+    }
+  }
+
+  async *deploy(
+    project: Project,
+    input: DeployBackendInput,
+  ): AsyncGenerator<ProjectEvent, DeployResult> {
+    this.compiler.preflight(project);
+    const cdkState = await readDeployedState(this.json, project.rootPath);
+    if (Object.values(cdkState.targets).some((target) => stackReferenceOf(target))) {
+      throw new ProjectStateError(
+        "The Terraform PoC supports new projects only. This project has a recorded CDK deployment; automatic migration or adoption is not supported.",
+      );
+    }
+    await this.checkTool(
+      "terraform",
+      "Install Terraform: https://developer.hashicorp.com/terraform/install",
+    );
+    const { target } = input;
+    const state = new TerraformState(project, target);
+    const unlock = await state.lock();
+    try {
+      const tearingDown =
+        declaredResources(project).length === 0 && (await state.hasManagedResources());
+      if (tearingDown) {
+        const approved = await input.confirmTeardown({
+          projectName: project.name,
+          targetName: target.name,
+          account: target.account,
+          region: target.region,
+          resourceDescription: "all Terraform-managed resources for this target",
+        });
+        if (!approved) throw new ProjectStateError("Terraform teardown was cancelled.");
+      }
+      yield { type: "step", message: "Packaging assets and generating Terraform configuration" };
+      yield* this.generate(project, target, state);
+      const credentials = await this.credentialsForTarget(target);
+      const env = this.environment(state, target, await credentials());
+      yield { type: "step", message: "Initializing and validating Terraform" };
+      yield* this.execute(["init", "-input=false", "-no-color"], state, env);
+      yield* this.execute(["validate", "-no-color"], state, env);
+      yield { type: "step", message: "Planning Terraform deployment" };
+      // Never reuse a plan from a prior operation, particularly after a failed apply.
+      const plan = "deployment.tfplan";
+      await rm(join(state.directory, plan), { force: true });
+      yield* this.execute(
+        ["plan", "-input=false", "-no-color", "-lock-timeout=60s", `-out=${plan}`],
+        state,
+        env,
+      );
+      if (
+        declaredResources(project).length > 0 &&
+        input.transactionSearch !== false &&
+        this.config.enableTransactionSearch
+      ) {
+        yield { type: "step", message: "Enabling CloudWatch Transaction Search" };
+        try {
+          await this.config.enableTransactionSearch(target, credentials);
+        } catch (error) {
+          yield {
+            type: "warning",
+            message: `Could not enable CloudWatch Transaction Search: ${error instanceof Error ? error.message : String(error)}`,
+          };
+        }
+      }
+      yield {
+        type: "step",
+        message: tearingDown ? "Removing Terraform resources" : "Applying Terraform plan",
+      };
+      yield* this.execute(
+        ["apply", "-input=false", "-no-color", "-lock-timeout=60s", plan],
+        state,
+        this.environment(state, target, await credentials()),
+      );
+      const outputs = await state.outputs();
+      return {
+        outputs: Object.fromEntries(
+          Object.entries(outputs).filter(
+            (entry): entry is [string, string] => typeof entry[1] === "string",
+          ),
+        ),
+        ...(tearingDown ? { tornDown: true } : {}),
+      };
+    } finally {
+      // Keep assets, provider lock, plan, and state after failure for retry/cleanup.
+      await unlock();
+    }
+  }
+
+  async resolveDeployedResources(
+    project: Project,
+    { target }: ResolveDeployedResourcesBackendInput,
+  ): Promise<ResolvedDeployedResource[]> {
+    const resources = await new TerraformState(project, target).resources();
+    if (resources.length === 0) {
+      throw new ProjectStateError(
+        `Project '${project.name}' has no Terraform deployment outputs for target '${target.name}'. ` +
+          `Run 'agentcore deploy --target ${target.name}' first.`,
+      );
+    }
+    const declared = new Set(
+      declaredResources(project).map((resource) => `${resource.resourceType}/${resource.name}`),
+    );
+    const credentialProvider = await this.credentialsForTarget(target);
+    return resources.flatMap((resource) =>
+      (resource.resourceType === "runtime" || resource.resourceType === "gateway") &&
+      declared.has(`${resource.resourceType}/${resource.name}`)
+        ? [
+            {
+              resourceType: resource.resourceType,
+              name: resource.name,
+              id: resource.id,
+              target,
+              credentialProvider,
+            },
+          ]
+        : [],
+    );
+  }
+
+  async resolveProjectResources(
+    project: Project,
+    { target }: ResolveProjectResourcesBackendInput,
+  ): Promise<ResolvedProjectResource[]> {
+    const resources = await new TerraformState(project, target).resources();
+    const declarations = declaredResources(project);
+    const resolve = (resource: (typeof declarations)[number]): ResolvedProjectResource => {
+      const deployed = resources.find(
+        (entry) =>
+          entry.resourceType === resource.resourceType &&
+          entry.name === resource.name &&
+          entry.parentName === resource.parentName,
+      );
+      const children = declarations
+        .filter(
+          (entry) =>
+            entry.parentName === resource.name &&
+            ((entry.resourceType === "policy" && resource.resourceType === "policy-engine") ||
+              (entry.resourceType === "gateway-target" && resource.resourceType === "gateway")),
+        )
+        .map(resolve);
+      return {
+        resourceType: resource.resourceType,
+        name: resource.name,
+        ...(children.length ? { children } : {}),
+        ...(deployed
+          ? {
+              deploymentState: "deployed" as const,
+              ...(deployed.arn ? { arn: deployed.arn } : { id: deployed.id }),
+            }
+          : { deploymentState: "local-only" as const }),
+      };
+    };
+    return declarations.filter((resource) => !resource.parentName).map(resolve);
+  }
+
+  private async *generate(project: Project, target: AwsDeploymentTarget, state: TerraformState) {
+    const assets = yield* withOutputEvents((emit) =>
+      this.packageAssets(project, state.directory, emit),
+    );
+    const configuration = this.compiler.compile(project, target, assets);
+    await atomicWrite(
+      join(state.directory, "main.tf.json"),
+      `${JSON.stringify(configuration, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+  }
+
+  private async *execute(args: string[], state: TerraformState, env: NodeJS.ProcessEnv) {
+    yield* withOutputEvents((emit) => {
+      const lines = createLineSplitter(emit);
+      return this.runner(["terraform", ...args], {
+        cwd: state.directory,
+        env,
+        onOutput: (chunk) => lines.push(chunk),
+      }).finally(() => lines.flush());
+    });
+  }
+
+  private async credentialsForTarget(target: AwsDeploymentTarget): Promise<CdkCredentialProvider> {
+    const credentials = await this.resolveCredentials(target.region);
+    const account = await this.resolveAccount(target.region, credentials);
+    if (account !== target.account) {
+      throw new ProjectStateError(
+        `Deployment target '${target.name}' expects AWS account ${target.account}, but the active credentials belong to ${account}.`,
+      );
+    }
+    return credentials;
+  }
+
+  private environment(
+    state: TerraformState,
+    target?: AwsDeploymentTarget,
+    credentials?: Awaited<ReturnType<CdkCredentialProvider>>,
+  ): NodeJS.ProcessEnv {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+      if (key.startsWith("TF_CLI_ARGS") || key.startsWith("TF_VAR_")) delete env[key];
+    }
+    if (credentials && target) {
+      for (const key of [
+        "AWS_PROFILE",
+        "AWS_DEFAULT_PROFILE",
+        "AWS_WEB_IDENTITY_TOKEN_FILE",
+        "AWS_ROLE_ARN",
+        "AWS_ROLE_SESSION_NAME",
+        "AWS_SECURITY_TOKEN",
+      ])
+        delete env[key];
+      env.AWS_ACCESS_KEY_ID = credentials.accessKeyId;
+      env.AWS_SECRET_ACCESS_KEY = credentials.secretAccessKey;
+      if (credentials.sessionToken) env.AWS_SESSION_TOKEN = credentials.sessionToken;
+      else delete env.AWS_SESSION_TOKEN;
+      env.AWS_REGION = target.region;
+      env.AWS_DEFAULT_REGION = target.region;
+    }
+    return {
+      ...env,
+      TF_IN_AUTOMATION: "1",
+      TF_INPUT: "0",
+      TF_DATA_DIR: join(state.directory, ".terraform"),
+      TF_WORKSPACE: "default",
+    };
+  }
+}
diff --git a/src/core/project/backends/terraform/assets.test.ts b/src/core/project/backends/terraform/assets.test.ts
new file mode 100644
index 0000000000..0be2266121
--- /dev/null
+++ b/src/core/project/backends/terraform/assets.test.ts
@@ -0,0 +1,113 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  symlink,
+  truncate,
+  utimes,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { unzipSync } from "fflate";
+import type { Project } from "../../../../handlers/project/types";
+import { ProjectSpecSchema } from "../../../../projectSchemas/project";
+import { TerraformAssetPackager } from "./assets";
+
+const directories: string[] = [];
+afterEach(async () => {
+  await Promise.all(
+    directories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })),
+  );
+});
+
+async function fixture(): Promise<Project> {
+  const rootPath = await mkdtemp(join(tmpdir(), "terraform-assets-"));
+  directories.push(rootPath);
+  await mkdir(join(rootPath, "app"));
+  await writeFile(join(rootPath, "app", "main.py"), "print('hello')\n");
+  return {
+    name: "example",
+    rootPath,
+    spec: ProjectSpecSchema.parse({
+      name: "example",
+      version: 2,
+      managedBy: "Terraform",
+      runtimes: [
+        {
+          name: "agent",
+          build: "CodeZip",
+          codeLocation: "app",
+          entrypoint: "main.py",
+          runtimeVersion: "PYTHON_3_12",
+          instrumentation: { enableOtel: false },
+        },
+      ],
+    }),
+  };
+}
+
+test("ZIP hash ignores file timestamps and excludes secret files and local environments", async () => {
+  const p = await fixture();
+  await mkdir(join(p.rootPath, "app", ".venv"));
+  await writeFile(join(p.rootPath, "app", ".venv", "secret.py"), "private");
+  await writeFile(join(p.rootPath, "app", ".env.local"), "TOKEN=private");
+  const packager = new TerraformAssetPackager(async () => {
+    throw new Error("unexpected process");
+  });
+  const directory = join(p.rootPath, "agentcore", "terraform", "build");
+  const first = await packager.build(p, directory, () => {});
+  await utimes(join(p.rootPath, "app", "main.py"), new Date(), new Date());
+  const second = await packager.build(p, directory, () => {});
+  expect(first.runtimes.agent!.hash).toBe(second.runtimes.agent!.hash);
+  const contents = unzipSync(await readFile(first.runtimes.agent!.path));
+  expect(Object.keys(contents)).toEqual(["main.py"]);
+  await writeFile(join(p.rootPath, "app", "main.py"), "print('changed')\n");
+  const third = await packager.build(p, directory, () => {});
+  expect(third.runtimes.agent!.hash).not.toBe(first.runtimes.agent!.hash);
+});
+
+test("source symlinks fail before their contents are packaged", async () => {
+  if (process.platform === "win32") return;
+  const p = await fixture();
+  await symlink(join(p.rootPath, "app", "main.py"), join(p.rootPath, "app", "linked.py"));
+  const packager = new TerraformAssetPackager(async () => {});
+  await expect(
+    packager.build(p, join(p.rootPath, "agentcore", "terraform", "build"), () => {}),
+  ).rejects.toThrow("symbolic links");
+});
+
+test("instrumentation requires an explicit dependency", async () => {
+  const p = await fixture();
+  p.spec.runtimes[0]!.instrumentation = { enableOtel: true };
+  const packager = new TerraformAssetPackager(async () => {});
+  await expect(
+    packager.build(p, join(p.rootPath, "agentcore", "terraform", "build"), () => {}),
+  ).rejects.toThrow("does not declare aws-opentelemetry-distro");
+});
+
+test("a missing runtime entrypoint fails before installing dependencies", async () => {
+  const p = await fixture();
+  p.spec.runtimes[0]!.entrypoint = "missing.py";
+  let ran = false;
+  const packager = new TerraformAssetPackager(async () => {
+    ran = true;
+  });
+  await expect(
+    packager.build(p, join(p.rootPath, "agentcore", "terraform", "build"), () => {}),
+  ).rejects.toThrow("entrypoint does not exist");
+  expect(ran).toBe(false);
+});
+
+test("rejects assets above the uncompressed Lambda ZIP limit", async () => {
+  const p = await fixture();
+  const largeFile = join(p.rootPath, "app", "large.dat");
+  await writeFile(largeFile, "");
+  await truncate(largeFile, 250 * 1024 * 1024 + 1);
+  const packager = new TerraformAssetPackager(async () => {});
+  await expect(
+    packager.build(p, join(p.rootPath, "agentcore", "terraform", "build"), () => {}),
+  ).rejects.toThrow("250 MiB when uncompressed");
+});
diff --git a/src/core/project/backends/terraform/assets.ts b/src/core/project/backends/terraform/assets.ts
new file mode 100644
index 0000000000..16c441698d
--- /dev/null
+++ b/src/core/project/backends/terraform/assets.ts
@@ -0,0 +1,294 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import {
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  realpath,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { zipSync, type Zippable } from "fflate";
+import { ProjectStateError } from "../../../../errors";
+import type { Project } from "../../../../handlers/project/types";
+import { atomicWrite, requireTool, type ProcessRunner } from "../../../../io";
+import { resolvePathWithinProject } from "../../../dev/path";
+import type { TerraformAssets } from "./compiler";
+
+const EXCLUDED = new Set([
+  ".git",
+  ".venv",
+  "__pycache__",
+  ".pytest_cache",
+  ".DS_Store",
+  "node_modules",
+  "terraform",
+]);
+const MAX_ASSET_BYTES = 250 * 1024 * 1024;
+
+type PackageInput = {
+  name: string;
+  source: string;
+  entrypoint: string;
+  pythonVersion: string;
+  instrumentation: boolean;
+};
+
+export type TerraformAssetBuilder = (
+  project: Project,
+  directory: string,
+  onOutput: (line: string) => void,
+) => Promise<TerraformAssets>;
+
+/** Builds deterministic Python ZIPs without copying local environments or secret files. */
+export class TerraformAssetPackager {
+  constructor(
+    private readonly runner: ProcessRunner,
+    private readonly checkTool: typeof requireTool = requireTool,
+  ) {}
+
+  async build(
+    project: Project,
+    directory: string,
+    onOutput: (line: string) => void,
+  ): Promise<TerraformAssets> {
+    await mkdir(join(directory, "assets"), { recursive: true, mode: 0o700 });
+    const assets: TerraformAssets = { runtimes: {}, gatewayTargets: {} };
+    for (const runtime of project.spec.runtimes) {
+      assets.runtimes[runtime.name] = await this.package(
+        project,
+        directory,
+        {
+          name: `runtime-${runtime.name}`,
+          source: runtime.codeLocation,
+          entrypoint: runtime.entrypoint.split(":")[0]!,
+          pythonVersion: runtime.runtimeVersion!,
+          instrumentation: runtime.instrumentation?.enableOtel !== false,
+        },
+        onOutput,
+      );
+    }
+    for (const gateway of project.spec.agentCoreGateways) {
+      for (const target of gateway.targets) {
+        if (target.targetType !== "lambda" || target.compute?.host !== "Lambda") continue;
+        assets.gatewayTargets[`${gateway.name}/${target.name}`] = await this.package(
+          project,
+          directory,
+          {
+            name: `gateway-${gateway.name}-${target.name}`,
+            source: target.compute.implementation.path,
+            entrypoint: `${target.compute.implementation.handler.replace(/[:.][^:.]+$/, "").replaceAll(".", "/")}.py`,
+            pythonVersion: target.compute.pythonVersion!,
+            instrumentation: false,
+          },
+          onOutput,
+        );
+      }
+    }
+    return assets;
+  }
+
+  private async package(
+    project: Project,
+    directory: string,
+    input: PackageInput,
+    onOutput: (line: string) => void,
+  ): Promise<{ path: string; hash: string }> {
+    const source = resolvePathWithinProject(
+      project.rootPath,
+      resolve(project.rootPath, input.source),
+      `${input.name} code directory`,
+    );
+    if (!(await stat(source)).isDirectory()) {
+      throw new ProjectStateError(`${input.name} source must be a directory`);
+    }
+    // Reject a project-root code location: it would recursively package Terraform's own state.
+    if ((await realpath(project.rootPath)) === source) {
+      throw new ProjectStateError(
+        `${input.name} codeLocation must be a subdirectory of the project`,
+      );
+    }
+    const entrypoint = resolve(source, input.entrypoint);
+    if (!existsSync(entrypoint) || !(await stat(entrypoint)).isFile()) {
+      throw new ProjectStateError(`${input.name} entrypoint does not exist: ${input.entrypoint}`);
+    }
+    resolvePathWithinProject(source, entrypoint, `${input.name} entrypoint`);
+    const staging = await mkdtemp(join(directory, "assets", ".staging-"));
+    try {
+      const pyproject = join(source, "pyproject.toml");
+      const requirements = join(source, "requirements.txt");
+      const hasPyproject = existsSync(pyproject);
+      const manifest = hasPyproject
+        ? pyproject
+        : existsSync(requirements)
+          ? requirements
+          : undefined;
+      if (input.instrumentation) {
+        const text = manifest ? await readFile(manifest, "utf8") : "";
+        if (!/aws[-_]opentelemetry[-_]distro/i.test(text)) {
+          throw new ProjectStateError(
+            `${input.name} enables instrumentation but does not declare aws-opentelemetry-distro. ` +
+              "Add it to the Python dependencies, or set instrumentation.enableOtel to false.",
+          );
+        }
+      }
+      if (manifest) {
+        await this.checkTool(
+          "uv",
+          "Install uv: https://docs.astral.sh/uv/getting-started/installation/",
+        );
+        const version = input.pythonVersion.replace("PYTHON_", "").replaceAll("_", ".");
+        let requirementPath = requirements;
+        if (hasPyproject) {
+          if (!existsSync(join(source, "uv.lock"))) {
+            throw new ProjectStateError(
+              `${input.name} has no uv.lock. Run 'uv lock' in ${source} before building.`,
+            );
+          }
+          requirementPath = join(staging, ".requirements.txt");
+          await this.runner(
+            [
+              "uv",
+              "export",
+              "--frozen",
+              "--no-dev",
+              "--no-emit-project",
+              "--no-editable",
+              "--output-file",
+              requirementPath,
+            ],
+            { cwd: source, onOutput },
+          );
+        } else {
+          const fingerprint = createHash("sha256")
+            .update(version)
+            .update(await readFile(requirements))
+            .digest("hex");
+          requirementPath = join(directory, "assets", `requirements-${fingerprint}.txt`);
+          if (!existsSync(requirementPath)) {
+            await this.runner(
+              [
+                "uv",
+                "pip",
+                "compile",
+                "--python-version",
+                version,
+                "--python-platform",
+                "aarch64-manylinux2014",
+                "--generate-hashes",
+                "--output-file",
+                requirementPath,
+                requirements,
+              ],
+              { cwd: source, onOutput },
+            );
+          }
+        }
+        await this.runner(
+          [
+            "uv",
+            "pip",
+            "install",
+            "--python-version",
+            version,
+            "--python-platform",
+            "aarch64-manylinux2014",
+            "--only-binary",
+            ":all:",
+            "--no-compile-bytecode",
+            "--require-hashes",
+            "--target",
+            staging,
+            "--requirements",
+            requirementPath,
+          ],
+          { cwd: source, onOutput },
+        );
+        await rm(join(staging, ".requirements.txt"), { force: true });
+        // Dependencies' host console scripts embed local interpreter paths.
+        // Runtime invokes only the portable OTEL script below; Lambda invokes its handler directly.
+        await rm(join(staging, "bin"), { recursive: true, force: true });
+        await rm(join(staging, "Scripts"), { recursive: true, force: true });
+      }
+      await this.copySource(source, staging);
+      if (input.instrumentation) {
+        // Host-generated console scripts carry an absolute host Python path.
+        // Replace this entry point with a portable Linux script, including on Windows.
+        await mkdir(join(staging, "bin"), { recursive: true });
+        await writeFile(
+          join(staging, "bin", "opentelemetry-instrument"),
+          "#!/usr/bin/env python3\nfrom opentelemetry.instrumentation.auto_instrumentation import run\nrun()\n",
+          { mode: 0o755 },
+        );
+        await rm(join(staging, "bin", "opentelemetry-instrument.exe"), { force: true });
+      }
+      const files: Zippable = {};
+      await this.collectZipEntries(staging, staging, files, { bytes: 0 });
+      const zip = zipSync(files, { level: 6 });
+      if (zip.byteLength > MAX_ASSET_BYTES) {
+        throw new ProjectStateError(`${input.name} ZIP exceeds 250 MiB`);
+      }
+      const hash = createHash("sha256").update(zip).digest("hex");
+      const path = join(directory, "assets", `${hash}.zip`);
+      await atomicWrite(path, zip, { mode: 0o600 });
+      return { path, hash };
+    } finally {
+      await rm(staging, { recursive: true, force: true });
+    }
+  }
+
+  private async copySource(source: string, destination: string): Promise<void> {
+    await cp(source, destination, {
+      recursive: true,
+      filter: async (path) => {
+        const name = basename(path);
+        if (EXCLUDED.has(name) || name === ".env" || name.startsWith(".env.")) return false;
+        const entry = await lstat(path);
+        if (entry.isSymbolicLink()) {
+          throw new ProjectStateError(
+            `Python asset sources cannot contain symbolic links: ${path}`,
+          );
+        }
+        return true;
+      },
+    });
+  }
+
+  private async collectZipEntries(
+    root: string,
+    directory: string,
+    files: Zippable,
+    total: { bytes: number },
+  ): Promise<void> {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink()) {
+        throw new ProjectStateError(`Python dependencies cannot contain symbolic links: ${path}`);
+      }
+      if (entry.isDirectory()) {
+        await this.collectZipEntries(root, path, files, total);
+      } else if (entry.isFile()) {
+        total.bytes += (await stat(path)).size;
+        if (total.bytes > MAX_ASSET_BYTES) {
+          throw new ProjectStateError("Python asset exceeds 250 MiB when uncompressed");
+        }
+        const name = relative(root, path).replaceAll("\\", "/");
+        files[name] = [
+          await readFile(path),
+          {
+            mtime: new Date("1980-01-01T00:00:00Z"),
+            os: 3,
+            attrs: (name.startsWith("bin/") ? 0o100755 : 0o100644) << 16,
+          },
+        ];
+      }
+    }
+  }
+}
diff --git a/src/core/project/backends/terraform/compiler.test.ts b/src/core/project/backends/terraform/compiler.test.ts
new file mode 100644
index 0000000000..651897f343
--- /dev/null
+++ b/src/core/project/backends/terraform/compiler.test.ts
@@ -0,0 +1,353 @@
+import { describe, expect, test } from "bun:test";
+import type { Project } from "../../../../handlers/project/types";
+import { ProjectSpecSchema } from "../../../../projectSchemas/project";
+import {
+  TerraformCompiler,
+  declaredResources,
+  type TerraformAssets,
+  type TerraformConfiguration,
+} from "./compiler";
+
+const target = { name: "test", account: "111122223333", region: "us-east-1" } as const;
+const archive = { path: "/tmp/agent.zip", hash: "a".repeat(64) };
+const assets: TerraformAssets = {
+  runtimes: { Agent: archive },
+  gatewayTargets: { "tools/echo": archive },
+};
+function project(): Project {
+  return {
+    name: "Example",
+    rootPath: "/tmp/example",
+    spec: ProjectSpecSchema.parse({
+      name: "Example",
+      version: 2,
+      managedBy: "Terraform",
+      runtimes: [
+        {
+          name: "Agent",
+          build: "CodeZip",
+          runtimeVersion: "PYTHON_3_12",
+          codeLocation: "src/agent",
+          entrypoint: "main.py",
+        },
+      ],
+      memories: [{ name: "Memory", eventExpiryDuration: 7, strategies: [{ type: "SEMANTIC" }] }],
+      policyEngines: [
+        {
+          name: "Rules",
+          policies: [
+            {
+              name: "Allow",
+              statement: "permit(principal, action, resource);",
+              enforcementMode: "LOG_ONLY",
+            },
+          ],
+        },
+      ],
+      agentCoreGateways: [
+        {
+          name: "tools",
+          authorizerType: "AWS_IAM",
+          policyEngineConfiguration: { policyEngineName: "Rules", mode: "LOG_ONLY" },
+          targets: [
+            {
+              name: "echo",
+              targetType: "lambda",
+              toolDefinitions: [
+                {
+                  name: "echo",
+                  description: "Echo input",
+                  inputSchema: {
+                    type: "object",
+                    properties: { message: { type: "string" }, optional: { type: "boolean" } },
+                    required: ["message"],
+                  },
+                },
+              ],
+              compute: {
+                host: "Lambda",
+                pythonVersion: "PYTHON_3_12",
+                implementation: { language: "Python", path: "src/tool", handler: "main.handler" },
+              },
+            },
+          ],
+        },
+      ],
+      onlineEvalConfigs: [
+        { name: "Quality", agent: "Agent", samplingRate: 100, evaluators: ["Builtin.Helpfulness"] },
+      ],
+    }),
+  };
+}
+function resource(config: TerraformConfiguration, type: string): Record<string, any> {
+  return Object.values(config.resource[type]!)[0]!;
+}
+function compile(p = project()): TerraformConfiguration {
+  return new TerraformCompiler().compile(p, target, assets);
+}
+
+describe("Terraform project compilation", () => {
+  test("connects runtime, memory, gateway, policies and evaluation with Terraform references", () => {
+    const config = compile();
+    const runtime = resource(config, "awscc_bedrockagentcore_runtime");
+    const gateway = resource(config, "awscc_bedrockagentcore_gateway");
+    const policy = resource(config, "awscc_bedrockagentcore_policy");
+    const evaluation = resource(config, "awscc_bedrockagentcore_online_evaluation_config");
+    const tool = resource(config, "aws_bedrockagentcore_gateway_target");
+    expect(runtime.environment_variables.MEMORY_MEMORY_ID).toMatch(
+      /^\$\{awscc_bedrockagentcore_memory\./,
+    );
+    expect(runtime.environment_variables.AGENTCORE_GATEWAY_TOOLS_URL).toMatch(
+      /^\$\{awscc_bedrockagentcore_gateway\./,
+    );
+    expect(runtime.environment_variables.OTEL_RESOURCE_ATTRIBUTES).toBeUndefined();
+    expect(gateway.exception_level).toBeUndefined();
+    expect(gateway.policy_engine_configuration.arn).toMatch(
+      /^\$\{awscc_bedrockagentcore_policy_engine\./,
+    );
+    expect(gateway.policy_engine_configuration.mode).toBe("LOG_ONLY");
+    expect(policy.definition).toEqual({
+      policy: { statement: "permit(principal, action, resource);" },
+    });
+    expect(policy.enforcement_mode).toBe("LOG_ONLY");
+    expect(evaluation.data_source_config.cloudwatch_logs.log_group_names[0]).toMatch(
+      /^\$\{aws_cloudwatch_log_group\./,
+    );
+    expect(evaluation.evaluators).toEqual([{ evaluator_id: "Builtin.Helpfulness" }]);
+    expect(tool.gateway_identifier).toMatch(/^\$\{awscc_bedrockagentcore_gateway\./);
+    expect(tool.target_configuration[0].mcp[0].lambda[0].lambda_arn).toMatch(
+      /^\$\{aws_lambda_function\./,
+    );
+    expect(config.output.project_resources!.value).toHaveLength(7);
+    expect(declaredResources(project())).toHaveLength(7);
+    expect(config.provider.aws).toEqual({
+      region: "us-east-1",
+      allowed_account_ids: [target.account],
+    });
+  });
+
+  test("escapes literal Terraform interpolation in customer text without escaping resource references", () => {
+    const p = project();
+    p.spec.runtimes[0]!.description = '${file("secret")} %{if true}';
+    p.spec.runtimes[0]!.envVars = [{ name: "CUSTOM", value: "${var.customer}" }];
+    p.spec.policyEngines[0]!.policies[0]!.statement =
+      'permit(principal, action, resource) when { context.value == "${value}" };';
+    const config = compile(p);
+    const runtime = resource(config, "awscc_bedrockagentcore_runtime");
+    expect(runtime.description).toBe('$${file("secret")} %%{if true}');
+    expect(runtime.environment_variables.CUSTOM).toBe("$${var.customer}");
+    expect(runtime.environment_variables.MEMORY_MEMORY_ID).toStartWith("${awscc_");
+    expect(resource(config, "awscc_bedrockagentcore_policy").definition.policy.statement).toContain(
+      '"$${value}"',
+    );
+  });
+
+  test("reordering resources preserves addresses and changes only output ordering", () => {
+    const p = project();
+    p.spec.memories.push({ ...p.spec.memories[0]!, name: "Second" });
+    const first = compile(p);
+    p.spec.memories.reverse();
+    const second = compile(p);
+    expect(second.resource).toEqual(first.resource);
+    expect(Object.keys(second.resource.awscc_bedrockagentcore_memory!)).toEqual(
+      Object.keys(first.resource.awscc_bedrockagentcore_memory!).reverse(),
+    );
+  });
+
+  test("configuration and archive updates preserve runtime addresses", () => {
+    const p = project();
+    const first = compile(p);
+    p.spec.runtimes[0]!.description = "updated";
+    const updated = new TerraformCompiler().compile(p, target, {
+      ...assets,
+      runtimes: { Agent: { ...archive, hash: "b".repeat(64) } },
+    });
+    expect(Object.keys(first.resource.awscc_bedrockagentcore_runtime!)).toEqual(
+      Object.keys(updated.resource.awscc_bedrockagentcore_runtime!),
+    );
+    expect(Object.keys(first.resource.aws_s3_object!)).toEqual(
+      Object.keys(updated.resource.aws_s3_object!),
+    );
+    expect(JSON.stringify(updated.resource.aws_s3_object)).toContain("b".repeat(64));
+  });
+
+  test("empty project generates no remaining support infrastructure for teardown", () => {
+    const p = project();
+    p.spec = ProjectSpecSchema.parse({ name: p.name, version: 2, managedBy: "Terraform" });
+    const config = compile(p);
+    expect(config.resource).toEqual({});
+    expect(config.output.project_resources!.value).toEqual([]);
+  });
+
+  test("permissions and code storage are scoped to the project's owned resources", () => {
+    const config = compile();
+    const bucket = resource(config, "aws_s3_bucket_public_access_block");
+    expect(bucket.block_public_acls).toBe(true);
+    expect(bucket.block_public_policy).toBe(true);
+    const policies = Object.values(config.resource.aws_iam_role_policy!).map((entry) =>
+      JSON.parse(entry.policy as string),
+    );
+    const memoryGrant = policies
+      .flatMap((entry) => entry.Statement)
+      .find((entry) => entry.Action?.includes("bedrock-agentcore:CreateEvent"));
+    expect(memoryGrant.Resource[0]).toStartWith("${awscc_bedrockagentcore_memory.");
+    const invocation = policies
+      .flatMap((entry) => entry.Statement)
+      .find((entry) => entry.Action?.includes("lambda:InvokeFunction"));
+    expect(invocation.Resource[0]).toStartWith("${aws_lambda_function.");
+    const evaluatorGrant = policies
+      .flatMap((entry) => entry.Statement)
+      .find((entry) => entry.Action?.includes("bedrock-agentcore:GetEvaluator"));
+    expect(evaluatorGrant.Resource).toEqual([
+      "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness",
+    ]);
+    const traceGrant = policies
+      .flatMap((entry) => entry.Statement)
+      .find((entry) => entry.Action?.includes("logs:PutResourcePolicy"));
+    expect(traceGrant.Resource[0]).toContain("/aws/bedrock-agentcore/runtimes/Example_test_Agent-");
+    const trust = Object.values(config.resource.aws_iam_role!)
+      .map((entry) => JSON.parse(entry.assume_role_policy as string))
+      .flatMap((entry) => entry.Statement)
+      .find((entry) => entry.Principal.Service === "bedrock-agentcore.amazonaws.com");
+    expect(trust.Condition.StringEquals["aws:SourceAccount"]).toBe(target.account);
+  });
+
+  test("preserves required tool properties and deep JSON schemas", () => {
+    const p = project();
+    const tool = p.spec.agentCoreGateways[0]!.targets[0]!.toolDefinitions![0]!;
+    tool.inputSchema.properties!.deep = {
+      type: "object",
+      properties: {
+        child: { type: "object", properties: { value: { type: "string" } }, required: ["value"] },
+      },
+      required: ["child"],
+    };
+    const result = resource(compile(p), "aws_bedrockagentcore_gateway_target")
+      .target_configuration[0].mcp[0].lambda[0].tool_schema[0].inline_payload[0].input_schema[0];
+    expect(result.property.find((entry: any) => entry.name === "message").required).toBe(true);
+    expect(result.property.find((entry: any) => entry.name === "optional").required).toBe(false);
+    const deep = result.property.find((entry: any) => entry.name === "deep").property[0];
+    expect(deep.required).toBe(true);
+    expect(JSON.parse(deep.properties_json)).toEqual({
+      properties: { value: { type: "string" } },
+      required: ["value"],
+    });
+  });
+
+  test("fails when a required artifact is absent", () => {
+    expect(() =>
+      new TerraformCompiler().compile(project(), target, { runtimes: {}, gatewayTargets: {} }),
+    ).toThrow("Missing packaged Terraform artifact");
+  });
+
+  test("represents array items under object properties using the provider's intermediate blocks", () => {
+    const p = project();
+    const tool = p.spec.agentCoreGateways[0]!.targets[0]!.toolDefinitions![0]!;
+    tool.inputSchema = {
+      type: "object",
+      properties: {
+        rows: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: { value: { type: "string" } },
+            required: ["value"],
+          },
+        },
+      },
+    };
+    const input = resource(compile(p), "aws_bedrockagentcore_gateway_target")
+      .target_configuration[0].mcp[0].lambda[0].tool_schema[0].inline_payload[0].input_schema[0];
+    expect(input.property[0].items[0].properties_json).toBeUndefined();
+    expect(input.property[0].items[0].property).toEqual([
+      { name: "value", type: "string", required: true, description: undefined },
+    ]);
+  });
+
+  test.each([
+    [
+      "migratedFrom",
+      (p: Project) => {
+        p.spec.migratedFrom = "v1";
+      },
+    ],
+    [
+      "runtimes[Agent].build",
+      (p: Project) => {
+        p.spec.runtimes[0]!.build = "Container";
+      },
+    ],
+    [
+      "runtimes[Agent].executionRoleArn",
+      (p: Project) => {
+        p.spec.runtimes[0]!.executionRoleArn = "arn:aws:iam::111122223333:role/existing";
+      },
+    ],
+    [
+      "runtimes[Agent].networkMode",
+      (p: Project) => {
+        p.spec.runtimes[0]!.networkMode = "VPC";
+      },
+    ],
+    [
+      "runtimes[Agent].runtimeVersion",
+      (p: Project) => {
+        p.spec.runtimes[0]!.runtimeVersion = "NODE_22";
+      },
+    ],
+    [
+      "runtimes[Agent].entrypoint",
+      (p: Project) => {
+        p.spec.runtimes[0]!.entrypoint = "main.py:app";
+      },
+    ],
+    [
+      "agentCoreGateways[tools].authorizerType",
+      (p: Project) => {
+        p.spec.agentCoreGateways[0]!.authorizerType = "NONE";
+      },
+    ],
+    [
+      "onlineEvalConfigs[Quality].evaluators",
+      (p: Project) => {
+        p.spec.onlineEvalConfigs[0]!.evaluators = ["Custom"];
+      },
+    ],
+    [
+      "onlineEvalConfigs[Quality].agent",
+      (p: Project) => {
+        p.spec.runtimes[0]!.instrumentation = { enableOtel: false };
+      },
+    ],
+    [
+      "envVars.MEMORY_MEMORY_ID",
+      (p: Project) => {
+        p.spec.runtimes[0]!.envVars = [{ name: "MEMORY_MEMORY_ID", value: "wrong" }];
+      },
+    ],
+    [
+      "memories[memory].name",
+      (p: Project) => {
+        p.spec.memories.push({ ...p.spec.memories[0]!, name: "memory" });
+      },
+    ],
+    [
+      "envVars.OTEL_SERVICE_NAME",
+      (p: Project) => {
+        p.spec.runtimes[0]!.envVars = [{ name: "OTEL_SERVICE_NAME", value: "other" }];
+      },
+    ],
+    [
+      "inputSchema.required",
+      (p: Project) => {
+        p.spec.agentCoreGateways[0]!.targets[0]!.toolDefinitions![0]!.inputSchema.required = [
+          "undeclared",
+        ];
+      },
+    ],
+  ] as const)("rejects unsupported %s before packaging or deployment", (path, change) => {
+    const p = project();
+    change(p);
+    expect(() => new TerraformCompiler().preflight(p)).toThrow(path);
+  });
+});
diff --git a/src/core/project/backends/terraform/compiler.ts b/src/core/project/backends/terraform/compiler.ts
new file mode 100644
index 0000000000..3c5a4c7a26
--- /dev/null
+++ b/src/core/project/backends/terraform/compiler.ts
@@ -0,0 +1,969 @@
+import { createHash } from "node:crypto";
+import { InputValidationError } from "../../../../errors";
+import type { DeployableResource, Project } from "../../../../handlers/project/types";
+import type { AwsDeploymentTarget } from "../../../../projectSchemas/aws-targets";
+import type { AgentCoreGateway } from "../../../../projectSchemas/gateway";
+import type { SchemaDefinition } from "../../../../projectSchemas/mcp-defs";
+import {
+  DEFAULT_STRATEGY_NAMESPACE_TEMPLATES,
+  type Memory,
+} from "../../../../projectSchemas/memory";
+import type { OnlineEvalConfig } from "../../../../projectSchemas/online-eval-config";
+import type { PolicyEngine } from "../../../../projectSchemas/policy";
+import type { ProjectRuntime } from "../../../../projectSchemas/runtime";
+
+type Attributes = Record<string, unknown>;
+export type TerraformArtifact = { path: string; hash: string };
+export type TerraformAssets = {
+  runtimes: Record<string, TerraformArtifact>;
+  /** Keys are gateway-name/target-name. */
+  gatewayTargets: Record<string, TerraformArtifact>;
+};
+export type TerraformResourceDescriptor = {
+  resourceType: DeployableResource;
+  name: string;
+  parentName?: string;
+};
+export type TerraformConfiguration = {
+  terraform: Attributes;
+  provider: Attributes;
+  resource: Record<string, Record<string, Attributes>>;
+  output: Record<string, { value: unknown }>;
+};
+
+export function declaredResources(project: Project): TerraformResourceDescriptor[] {
+  return [
+    ...project.spec.runtimes.map(({ name }) => ({ resourceType: "runtime" as const, name })),
+    ...project.spec.memories.map(({ name }) => ({ resourceType: "memory" as const, name })),
+    ...project.spec.policyEngines.flatMap(({ name, policies }) => [
+      { resourceType: "policy-engine" as const, name },
+      ...policies.map((policy) => ({
+        resourceType: "policy" as const,
+        name: policy.name,
+        parentName: name,
+      })),
+    ]),
+    ...project.spec.agentCoreGateways.flatMap(({ name, targets }) => [
+      { resourceType: "gateway" as const, name },
+      ...targets.map((target) => ({
+        resourceType: "gateway-target" as const,
+        name: target.name,
+        parentName: name,
+      })),
+    ]),
+    ...project.spec.onlineEvalConfigs.map(({ name }) => ({
+      resourceType: "online-eval" as const,
+      name,
+    })),
+  ];
+}
+
+const digest = (value: string) => createHash("sha256").update(value).digest("hex").slice(0, 10);
+const key = (name: string) => `r_${name.replace(/[^a-zA-Z0-9_]/g, "_")}_${digest(name)}`;
+const ref = (address: string, attribute: string) => `\${${address}.${attribute}}`;
+/** All customer strings are Terraform string literals, never expressions. */
+const literal = (value: string) => value.replace(/\$\{/g, () => "$${").replace(/%\{/g, () => "%%{");
+const optional = (value?: string) => (value === undefined ? undefined : literal(value));
+const tagMap = (project: Project, tags?: Record<string, string>) =>
+  Object.fromEntries(
+    Object.entries({ ...project.spec.tags, ...tags }).map(([name, value]) => [
+      name,
+      literal(value),
+    ]),
+  );
+const tagList = (tags: Record<string, string>) =>
+  Object.entries(tags).map(([key, value]) => ({ key, value }));
+const statement = (actions: string[], resources: string[]) => ({
+  Effect: "Allow",
+  Action: actions,
+  Resource: resources,
+});
+const policyDocument = (statements: Attributes[]) =>
+  JSON.stringify({ Version: "2012-10-17", Statement: statements });
+const hasValue = (value: unknown) =>
+  value !== undefined && (!Array.isArray(value) || value.length > 0);
+
+function reject(path: string, detail = "is not supported by the Terraform PoC"): never {
+  throw new InputValidationError(`agentcore.json ${path}: ${detail}.`);
+}
+function fields(value: object, allowed: string[], path: string): void {
+  for (const [name, entry] of Object.entries(value)) {
+    if (hasValue(entry) && !allowed.includes(name)) reject(`${path}.${name}`);
+  }
+}
+
+/** Compiles the deliberately bounded Terraform PoC without performing I/O or deploying resources. */
+export class TerraformCompiler {
+  private resources: TerraformConfiguration["resource"] = {};
+  private outputs: TerraformConfiguration["output"] = {};
+  private deployed: Attributes[] = [];
+  private project!: Project;
+  private target!: AwsDeploymentTarget;
+  private partition = "aws";
+
+  preflight(project: Project): void {
+    fields(
+      project.spec,
+      [
+        "name",
+        "version",
+        "managedBy",
+        "tags",
+        "runtimes",
+        "memories",
+        "policyEngines",
+        "agentCoreGateways",
+        "onlineEvalConfigs",
+      ],
+      "project",
+    );
+    for (const runtime of project.spec.runtimes) {
+      const path = `runtimes[${runtime.name}]`;
+      fields(
+        runtime,
+        [
+          "name",
+          "description",
+          "modelProvider",
+          "modelId",
+          "build",
+          "codeLocation",
+          "entrypoint",
+          "runtimeVersion",
+          "envVars",
+          "instrumentation",
+          "networkMode",
+          "authorizerType",
+          "protocol",
+          "requestHeaderAllowlist",
+          "tags",
+          "lifecycleConfiguration",
+        ],
+        path,
+      );
+      if (runtime.build !== "CodeZip") reject(`${path}.build`, "must be CodeZip for this PoC");
+      if (!runtime.runtimeVersion?.startsWith("PYTHON_3_"))
+        reject(`${path}.runtimeVersion`, "must select a Python managed runtime");
+      if (runtime.networkMode && runtime.networkMode !== "PUBLIC")
+        reject(`${path}.networkMode`, "must be PUBLIC for this PoC");
+      if (runtime.authorizerType && runtime.authorizerType !== "AWS_IAM")
+        reject(`${path}.authorizerType`, "must be AWS_IAM for this PoC");
+      if (!runtime.entrypoint.endsWith(".py"))
+        reject(`${path}.entrypoint`, "must be a Python script without a handler suffix");
+      const environment = new Set<string>();
+      for (const env of runtime.envVars ?? []) {
+        if (environment.has(env.name))
+          reject(`${path}.envVars`, `contains duplicate variable ${env.name}`);
+        environment.add(env.name);
+        const generated =
+          project.spec.memories.some((memory) =>
+            [
+              `MEMORY_${memory.name.toUpperCase()}_ID`,
+              `MEMORY_${memory.name.toUpperCase()}_ARN`,
+            ].includes(env.name),
+          ) ||
+          project.spec.agentCoreGateways.some((gateway) =>
+            ["URL", "ARN", "ID"]
+              .map((suffix) => `${this.gatewayPrefix(gateway.name)}_${suffix}`)
+              .includes(env.name),
+          );
+        if (generated)
+          reject(
+            `${path}.envVars.${env.name}`,
+            "conflicts with a project resource discovery variable",
+          );
+      }
+    }
+    const memoryVariables = new Set<string>();
+    for (const memory of project.spec.memories) {
+      const environmentName = memory.name.toUpperCase();
+      if (memoryVariables.has(environmentName))
+        reject(
+          `memories[${memory.name}].name`,
+          "collides with another memory's discovery variables",
+        );
+      memoryVariables.add(environmentName);
+      fields(
+        memory,
+        ["name", "description", "eventExpiryDuration", "strategies", "indexedKeys", "tags"],
+        `memories[${memory.name}]`,
+      );
+    }
+    for (const engine of project.spec.policyEngines) {
+      fields(
+        engine,
+        ["name", "description", "encryptionKeyArn", "tags", "policies"],
+        `policyEngines[${engine.name}]`,
+      );
+      // sourceFile and authorizationPhase are CLI provenance/inference metadata. Like the L3,
+      // the deployment uses the actual statement and the service determines authorization phase.
+    }
+    const gatewayVariables = new Set<string>();
+    for (const gateway of project.spec.agentCoreGateways) {
+      const path = `agentCoreGateways[${gateway.name}]`;
+      fields(
+        gateway,
+        [
+          "name",
+          "resourceName",
+          "protocolType",
+          "description",
+          "targets",
+          "authorizerType",
+          "enableSemanticSearch",
+          "exceptionLevel",
+          "policyEngineConfiguration",
+          "tags",
+        ],
+        path,
+      );
+      if (gateway.authorizerType !== "AWS_IAM")
+        reject(`${path}.authorizerType`, "must be AWS_IAM for this PoC");
+      if (gateway.protocolType && gateway.protocolType !== "MCP")
+        reject(`${path}.protocolType`, "must be MCP for this PoC");
+      if (gatewayVariables.has(this.gatewayPrefix(gateway.name)))
+        reject(`${path}.name`, "collides with another gateway's discovery variables");
+      gatewayVariables.add(this.gatewayPrefix(gateway.name));
+      const names = new Set<string>();
+      for (const target of gateway.targets) {
+        const targetPath = `${path}.targets[${target.name}]`;
+        fields(
+          target,
+          ["name", "targetType", "toolDefinitions", "compute", "outboundAuth"],
+          targetPath,
+        );
+        if (names.has(target.name)) reject(`${targetPath}.name`, "duplicates another target");
+        names.add(target.name);
+        if (target.targetType !== "lambda")
+          reject(`${targetPath}.targetType`, "must be lambda for this PoC");
+        if (
+          target.compute?.host !== "Lambda" ||
+          target.compute.implementation.language !== "Python"
+        )
+          reject(`${targetPath}.compute`, "must be a Python Lambda for this PoC");
+        fields(
+          target.compute,
+          ["host", "implementation", "pythonVersion", "timeout", "memorySize", "iamPolicy"],
+          `${targetPath}.compute`,
+        );
+        fields(
+          target.compute.implementation,
+          ["language", "path", "handler"],
+          `${targetPath}.compute.implementation`,
+        );
+        if (target.compute.iamPolicy) {
+          fields(
+            target.compute.iamPolicy,
+            ["Version", "Statement"],
+            `${targetPath}.compute.iamPolicy`,
+          );
+          if (target.compute.iamPolicy.Version !== "2012-10-17")
+            reject(`${targetPath}.compute.iamPolicy.Version`, "must be 2012-10-17");
+        }
+        if (target.compute.nodeVersion) reject(`${targetPath}.compute.nodeVersion`);
+        if (target.outboundAuth && Object.keys(target.outboundAuth).some((name) => name !== "type"))
+          reject(`${targetPath}.outboundAuth`);
+        if (target.outboundAuth && target.outboundAuth.type !== "NONE")
+          reject(`${targetPath}.outboundAuth.type`);
+        if (
+          !/^[a-zA-Z_][a-zA-Z0-9_.]*\.[a-zA-Z_][a-zA-Z0-9_]*$/.test(
+            target.compute.implementation.handler,
+          )
+        )
+          reject(
+            `${targetPath}.compute.implementation.handler`,
+            "must use the Lambda module.function format",
+          );
+        for (const tool of target.toolDefinitions ?? []) {
+          this.validateToolSchema(tool.inputSchema, `${targetPath}.${tool.name}.inputSchema`);
+          if (tool.outputSchema)
+            this.validateToolSchema(tool.outputSchema, `${targetPath}.${tool.name}.outputSchema`);
+        }
+      }
+    }
+    for (const config of project.spec.onlineEvalConfigs) {
+      const path = `onlineEvalConfigs[${config.name}]`;
+      if (!config.agent || config.logGroupNames || config.serviceNames)
+        reject(path, "must reference a project runtime for this PoC");
+      if (config.endpoint && config.endpoint !== "DEFAULT")
+        reject(`${path}.endpoint`, "must use DEFAULT for this PoC");
+      if (config.evaluators.some((name) => !name.startsWith("Builtin.")))
+        reject(`${path}.evaluators`, "must contain built-in evaluators for this PoC");
+      const runtime = project.spec.runtimes.find((entry) => entry.name === config.agent);
+      if (!runtime) reject(`${path}.agent`, "references an unknown runtime");
+      if (runtime.instrumentation?.enableOtel === false)
+        reject(
+          `${path}.agent`,
+          "requires runtime OpenTelemetry instrumentation for online evaluation",
+        );
+      for (const env of runtime.envVars ?? []) {
+        if (env.name.startsWith("OTEL_") || env.name === "UNIFIED_TRACES_DESTINATION_ENABLED")
+          reject(
+            `runtimes[${runtime.name}].envVars.${env.name}`,
+            "cannot override service-managed telemetry while a project online evaluation uses this runtime",
+          );
+      }
+    }
+  }
+
+  compile(
+    project: Project,
+    target: AwsDeploymentTarget,
+    assets: TerraformAssets,
+  ): TerraformConfiguration {
+    this.preflight(project);
+    this.resources = {};
+    this.outputs = {};
+    this.deployed = [];
+    this.project = project;
+    this.target = target;
+    this.partition = target.region.startsWith("cn-")
+      ? "aws-cn"
+      : target.region.startsWith("us-gov-")
+        ? "aws-us-gov"
+        : "aws";
+    if (
+      project.spec.runtimes.length ||
+      project.spec.agentCoreGateways.some((gateway) => gateway.targets.length)
+    )
+      this.artifactBucket();
+    for (const memory of project.spec.memories) this.memory(memory);
+    for (const engine of project.spec.policyEngines) this.policyEngine(engine);
+    for (const gateway of project.spec.agentCoreGateways) this.gateway(gateway, assets);
+    for (const runtime of project.spec.runtimes) this.runtime(runtime, assets);
+    for (const config of project.spec.onlineEvalConfigs) this.onlineEvaluation(config);
+    this.outputs.project_resources = { value: this.deployed };
+    return {
+      terraform: {
+        required_version: ">= 1.12.0, < 2.0.0",
+        required_providers: {
+          awscc: { source: "hashicorp/awscc", version: "= 1.106.0" },
+          aws: { source: "hashicorp/aws", version: "= 6.69.0" },
+        },
+      },
+      provider: {
+        awscc: { region: target.region },
+        aws: { region: target.region, allowed_account_ids: [target.account] },
+      },
+      resource: this.resources,
+      output: this.outputs,
+    };
+  }
+
+  private add(type: string, name: string, attributes: Attributes): string {
+    const label = key(name);
+    (this.resources[type] ??= {})[label] = attributes;
+    return `${type}.${label}`;
+  }
+  private address(type: string, name: string): string {
+    return `${type}.${key(name)}`;
+  }
+  private physical(name: string, limit = 48, separator = "_"): string {
+    const full = `${this.project.name}${separator}${this.target.name}${separator}${name}`.replace(
+      separator === "_" ? /[^a-zA-Z0-9_]/g : /[^a-zA-Z0-9-]/g,
+      separator,
+    );
+    return full.length <= limit ? full : `${full.slice(0, limit - 11)}${separator}${digest(full)}`;
+  }
+  private arn(service: string, resource: string): string {
+    return `arn:${this.partition}:${service}:${this.target.region}:${this.target.account}:${resource}`;
+  }
+  private gatewayPrefix(name: string): string {
+    return `AGENTCORE_GATEWAY_${name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+  }
+  private publish(
+    resourceType: DeployableResource,
+    name: string,
+    id: string,
+    arn?: string,
+    parentName?: string,
+  ): void {
+    this.deployed.push({
+      resourceType,
+      name,
+      id,
+      ...(arn ? { arn } : {}),
+      ...(parentName ? { parentName } : {}),
+    });
+    this.outputs[`${key(`${resourceType}/${parentName ?? ""}/${name}`)}_id`] = { value: id };
+    if (arn)
+      this.outputs[`${key(`${resourceType}/${parentName ?? ""}/${name}`)}_arn`] = { value: arn };
+  }
+  private role(
+    name: string,
+    service: string,
+    statements: Attributes[],
+    sourceArn?: string | string[],
+  ): { arn: string; dependency: string } {
+    const role = this.add("aws_iam_role", name, {
+      name: this.physical(name, 64, "-"),
+      assume_role_policy: policyDocument([
+        {
+          Effect: "Allow",
+          Principal: { Service: service },
+          Action: "sts:AssumeRole",
+          ...(sourceArn
+            ? {
+                Condition: {
+                  StringEquals: {
+                    "aws:SourceAccount": this.target.account,
+                    "aws:ResourceAccount": this.target.account,
+                  },
+                  ArnLike: { "aws:SourceArn": sourceArn },
+                },
+              }
+            : {}),
+        },
+      ]),
+      tags: tagMap(this.project),
+    });
+    const dependency = statements.length
+      ? this.add("aws_iam_role_policy", name, {
+          name: "agentcore-poc",
+          role: ref(role, "id"),
+          policy: policyDocument(statements),
+        })
+      : role;
+    return { arn: ref(role, "arn"), dependency };
+  }
+  private artifactBucket(): void {
+    const bucket = this.add("aws_s3_bucket", "artifacts", {
+      bucket: `agentcore-tf-${digest(`${this.project.name}/${this.target.name}/${this.target.account}/${this.target.region}`)}-${this.target.account}`,
+      force_destroy: true,
+      tags: tagMap(this.project),
+    });
+    this.add("aws_s3_bucket_public_access_block", "artifacts", {
+      bucket: ref(bucket, "id"),
+      block_public_acls: true,
+      block_public_policy: true,
+      ignore_public_acls: true,
+      restrict_public_buckets: true,
+    });
+    this.add("aws_s3_bucket_server_side_encryption_configuration", "artifacts", {
+      bucket: ref(bucket, "id"),
+      rule: [{ apply_server_side_encryption_by_default: [{ sse_algorithm: "AES256" }] }],
+    });
+  }
+  private asset(name: string, artifact?: TerraformArtifact): string {
+    if (!artifact)
+      throw new InputValidationError(
+        `Missing packaged Terraform artifact for ${name}. Run agentcore build first.`,
+      );
+    return this.add("aws_s3_object", name, {
+      bucket: ref(this.address("aws_s3_bucket", "artifacts"), "id"),
+      key: `${name}/${artifact.hash}.zip`,
+      source: literal(artifact.path),
+      source_hash: artifact.hash,
+      content_type: "application/zip",
+      server_side_encryption: "AES256",
+    });
+  }
+  private memory(memory: Memory): void {
+    const strategyKeys = {
+      SEMANTIC: "semantic_memory_strategy",
+      SUMMARIZATION: "summary_memory_strategy",
+      USER_PREFERENCE: "user_preference_memory_strategy",
+      EPISODIC: "episodic_memory_strategy",
+    };
+    // Built-in strategies do not require model permissions in the execution role.
+    // Keep the service role explicit, like the L3, so its lifecycle is owned here.
+    const role = this.role(
+      `memory/${memory.name}`,
+      "bedrock-agentcore.amazonaws.com",
+      [],
+      this.arn("bedrock-agentcore", `memory/${this.physical(memory.name)}*`),
+    );
+    const resource = this.add("awscc_bedrockagentcore_memory", memory.name, {
+      name: this.physical(memory.name),
+      description: optional(memory.description),
+      event_expiry_duration: memory.eventExpiryDuration,
+      memory_execution_role_arn: role.arn,
+      indexed_keys: memory.indexedKeys?.map(({ key, type }) => ({ key: literal(key), type })),
+      memory_strategies: memory.strategies.map((strategy) => ({
+        [strategyKeys[strategy.type]]: {
+          name:
+            strategy.name ??
+            `${memory.name}_${strategy.type.charAt(0)}${strategy.type.slice(1).toLowerCase().replace(/_/g, "")}`,
+          description: optional(strategy.description),
+          namespace_templates: (
+            strategy.namespaceTemplates ??
+            strategy.namespaces ??
+            DEFAULT_STRATEGY_NAMESPACE_TEMPLATES[strategy.type]
+          )?.map(literal),
+          ...(strategy.type === "EPISODIC"
+            ? {
+                reflection_configuration: {
+                  namespace_templates: (
+                    strategy.reflectionNamespaceTemplates ?? strategy.reflectionNamespaces
+                  )?.map(literal),
+                },
+              }
+            : {}),
+        },
+      })),
+      tags: tagMap(this.project, memory.tags),
+    });
+    this.publish("memory", memory.name, ref(resource, "memory_id"), ref(resource, "memory_arn"));
+  }
+  private policyEngine(engine: PolicyEngine): void {
+    const resource = this.add("awscc_bedrockagentcore_policy_engine", engine.name, {
+      name: this.physical(engine.name),
+      description: optional(engine.description),
+      encryption_key_arn: optional(engine.encryptionKeyArn),
+      tags: tagList(tagMap(this.project, engine.tags)),
+    });
+    this.publish(
+      "policy-engine",
+      engine.name,
+      ref(resource, "policy_engine_id"),
+      ref(resource, "policy_engine_arn"),
+    );
+    for (const policy of engine.policies) {
+      const policyResource = this.add(
+        "awscc_bedrockagentcore_policy",
+        `${engine.name}/${policy.name}`,
+        {
+          name: policy.name,
+          policy_engine_id: ref(resource, "policy_engine_id"),
+          definition: { policy: { statement: literal(policy.statement) } },
+          description: optional(policy.description),
+          enforcement_mode: policy.enforcementMode,
+          validation_mode: policy.validationMode,
+        },
+      );
+      this.publish(
+        "policy",
+        policy.name,
+        ref(policyResource, "policy_id"),
+        ref(policyResource, "policy_arn"),
+        engine.name,
+      );
+    }
+  }
+  private gateway(gateway: AgentCoreGateway, assets: TerraformAssets): void {
+    const lambdaArns: string[] = [];
+    const lambdaDependencies: string[] = [];
+    for (const target of gateway.targets) {
+      if (target.compute?.host !== "Lambda") continue; // preflight guarantees Lambda
+      const name = `${gateway.name}/${target.name}`;
+      const compute = target.compute;
+      const lambdaName = this.physical(name, 64, "-");
+      const logs = this.add("aws_cloudwatch_log_group", `lambda/${name}`, {
+        name: `/aws/lambda/${lambdaName}`,
+        retention_in_days: 7,
+        tags: tagMap(this.project),
+      });
+      const role = this.role(`lambda/${name}`, "lambda.amazonaws.com", [
+        statement(["logs:CreateLogStream", "logs:PutLogEvents"], [`${ref(logs, "arn")}:*`]),
+        ...(compute.iamPolicy
+          ? compute.iamPolicy.Statement.map(
+              (entry) => JSON.parse(literal(JSON.stringify(entry))) as Attributes,
+            )
+          : []),
+      ]);
+      const asset = this.asset(`lambda/${name}`, assets.gatewayTargets[name]);
+      const lambda = this.add("aws_lambda_function", name, {
+        function_name: lambdaName,
+        role: role.arn,
+        runtime: `python${compute.pythonVersion!.replace("PYTHON_", "").replace("_", ".")}`,
+        handler: compute.implementation.handler,
+        architectures: ["arm64"],
+        timeout: compute.timeout ?? 30,
+        memory_size: compute.memorySize ?? 512,
+        s3_bucket: ref(asset, "bucket"),
+        s3_key: ref(asset, "key"),
+        source_code_hash: Buffer.from(assets.gatewayTargets[name]!.hash, "hex").toString("base64"),
+        tags: tagMap(this.project),
+        depends_on: [role.dependency],
+      });
+      lambdaArns.push(ref(lambda, "arn"));
+      lambdaDependencies.push(lambda);
+    }
+    const policies: Attributes[] = lambdaArns.length
+      ? [statement(["lambda:InvokeFunction"], lambdaArns)]
+      : [];
+    const engine = gateway.policyEngineConfiguration
+      ? this.address(
+          "awscc_bedrockagentcore_policy_engine",
+          gateway.policyEngineConfiguration.policyEngineName,
+        )
+      : undefined;
+    if (engine)
+      policies.push(
+        statement(
+          [
+            "bedrock-agentcore:GetPolicyEngine",
+            "bedrock-agentcore:CheckAuthorizePermissions",
+            "bedrock-agentcore:AuthorizeAction",
+            "bedrock-agentcore:PartiallyAuthorizeActions",
+          ],
+          [ref(engine, "policy_engine_arn"), this.arn("bedrock-agentcore", "gateway/*")],
+        ),
+      );
+    // An empty gateway still needs a role but no arbitrary resource grants.
+    const role = this.role(
+      `gateway/${gateway.name}`,
+      "bedrock-agentcore.amazonaws.com",
+      policies,
+      this.arn("bedrock-agentcore", "gateway/*"),
+    );
+    const resource = this.add("awscc_bedrockagentcore_gateway", gateway.name, {
+      name: gateway.resourceName ?? this.physical(gateway.name, 100, "-"),
+      authorizer_type: "AWS_IAM",
+      role_arn: role.arn,
+      protocol_type: "MCP",
+      description: optional(gateway.description),
+      exception_level: gateway.exceptionLevel === "DEBUG" ? "DEBUG" : undefined,
+      protocol_configuration: {
+        mcp: {
+          ...(gateway.enableSemanticSearch ? { search_type: "SEMANTIC" } : {}),
+          supported_versions: ["2025-03-26"],
+        },
+      },
+      policy_engine_configuration: engine
+        ? { arn: ref(engine, "policy_engine_arn"), mode: gateway.policyEngineConfiguration!.mode }
+        : undefined,
+      tags: tagMap(this.project, gateway.tags),
+      depends_on: [role.dependency],
+    });
+    this.publish(
+      "gateway",
+      gateway.name,
+      ref(resource, "gateway_identifier"),
+      ref(resource, "gateway_arn"),
+    );
+    this.outputs[`${key(`gateway/${gateway.name}`)}_url`] = { value: ref(resource, "gateway_url") };
+    for (const target of gateway.targets) {
+      const name = `${gateway.name}/${target.name}`;
+      const lambda = this.address("aws_lambda_function", name);
+      // AWSCC 1.106.0 does not ship GatewayTarget. The native provider owns this
+      // resource's full CRUD lifecycle while referring to the AWSCC gateway.
+      const resourceTarget = this.add("aws_bedrockagentcore_gateway_target", name, {
+        name: literal(target.name),
+        gateway_identifier: ref(resource, "gateway_identifier"),
+        credential_provider_configuration: [{ gateway_iam_role: [{}] }],
+        target_configuration: [
+          {
+            mcp: [
+              {
+                lambda: [
+                  {
+                    lambda_arn: ref(lambda, "arn"),
+                    tool_schema: [
+                      {
+                        inline_payload: target.toolDefinitions!.map((tool) => ({
+                          name: literal(tool.name),
+                          description: literal(tool.description),
+                          input_schema: [this.toolSchema(tool.inputSchema)],
+                          ...(tool.outputSchema
+                            ? { output_schema: [this.toolSchema(tool.outputSchema)] }
+                            : {}),
+                        })),
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+        depends_on: [role.dependency, ...lambdaDependencies],
+      });
+      this.publish(
+        "gateway-target",
+        target.name,
+        ref(resourceTarget, "target_id"),
+        undefined,
+        gateway.name,
+      );
+    }
+  }
+  private validateToolSchema(schema: SchemaDefinition, path: string): void {
+    if (schema.items && schema.type !== "array")
+      reject(`${path}.items`, "requires an array schema");
+    if ((schema.properties || schema.required?.length) && schema.type !== "object")
+      reject(path, "properties and required are supported only on object schemas");
+    for (const required of schema.required ?? []) {
+      if (!Object.hasOwn(schema.properties ?? {}, required))
+        reject(
+          `${path}.required`,
+          `references property ${required} without a declaration; the native provider cannot preserve it`,
+        );
+    }
+    for (const [name, property] of Object.entries(schema.properties ?? {}))
+      this.validateToolSchema(property, `${path}.properties.${name}`);
+    if (schema.items) this.validateToolSchema(schema.items, `${path}.items`);
+  }
+
+  private toolSchema(
+    schema: SchemaDefinition,
+    kind: "root" | "property" | "items" | "leaf" = "root",
+  ): Attributes {
+    const result: Attributes = { type: schema.type, description: optional(schema.description) };
+    if (kind === "leaf") {
+      if (schema.items) result.items_json = literal(JSON.stringify(schema.items));
+      if (schema.properties)
+        result.properties_json = literal(
+          JSON.stringify({ properties: schema.properties, required: schema.required ?? [] }),
+        );
+    } else {
+      if (schema.items)
+        result.items = [this.toolSchema(schema.items, kind === "items" ? "leaf" : "items")];
+      if (schema.properties)
+        result.property = Object.entries(schema.properties).map(([name, value]) => ({
+          name: literal(name),
+          required: schema.required?.includes(name) ?? false,
+          ...this.toolSchema(value, kind === "root" ? "property" : "leaf"),
+        }));
+    }
+    return result;
+  }
+  private runtime(runtime: ProjectRuntime, assets: TerraformAssets): void {
+    const physicalName = this.physical(runtime.name);
+    const artifact = this.asset(`runtime/${runtime.name}`, assets.runtimes[runtime.name]);
+    const memoryArns = this.project.spec.memories
+      .map((memory) =>
+        ref(this.address("awscc_bedrockagentcore_memory", memory.name), "memory_arn"),
+      )
+      .sort();
+    const gatewayArns = this.project.spec.agentCoreGateways
+      .map((gateway) =>
+        ref(this.address("awscc_bedrockagentcore_gateway", gateway.name), "gateway_arn"),
+      )
+      .sort();
+    const statements: Attributes[] = [
+      statement(["s3:GetObject"], [`${ref(this.address("aws_s3_bucket", "artifacts"), "arn")}/*`]),
+      statement(
+        [
+          "logs:CreateLogGroup",
+          "logs:CreateLogStream",
+          "logs:PutLogEvents",
+          "logs:DescribeLogStreams",
+          "logs:PutResourcePolicy",
+        ],
+        [this.arn("logs", `log-group:/aws/bedrock-agentcore/runtimes/${physicalName}-*`)],
+      ),
+      statement(
+        [
+          "logs:DescribeLogGroups",
+          "xray:PutTraceSegments",
+          "xray:PutTelemetryRecords",
+          "xray:GetSamplingRules",
+          "xray:GetSamplingTargets",
+          "cloudwatch:PutMetricData",
+        ],
+        ["*"],
+      ),
+      statement(
+        ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
+        [
+          `arn:${this.partition}:bedrock:*::foundation-model/*`,
+          `arn:${this.partition}:bedrock:*:${this.target.account}:inference-profile/*`,
+          `arn:${this.partition}:bedrock:*:${this.target.account}:application-inference-profile/*`,
+        ],
+      ),
+      statement(
+        [
+          "bedrock-agentcore:GetWorkloadAccessToken",
+          "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
+          "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
+        ],
+        [
+          this.arn("bedrock-agentcore", "workload-identity-directory/default"),
+          this.arn("bedrock-agentcore", "workload-identity-directory/default/workload-identity/*"),
+        ],
+      ),
+    ];
+    if (memoryArns.length)
+      statements.push(
+        statement(
+          [
+            "bedrock-agentcore:CreateEvent",
+            "bedrock-agentcore:DeleteEvent",
+            "bedrock-agentcore:GetEvent",
+            "bedrock-agentcore:GetMemory",
+            "bedrock-agentcore:GetMemoryRecord",
+            "bedrock-agentcore:ListActors",
+            "bedrock-agentcore:ListEvents",
+            "bedrock-agentcore:ListSessions",
+            "bedrock-agentcore:ListMemoryRecords",
+            "bedrock-agentcore:RetrieveMemoryRecords",
+            "bedrock-agentcore:DeleteMemoryRecord",
+          ],
+          memoryArns,
+        ),
+      );
+    if (gatewayArns.length)
+      statements.push(statement(["bedrock-agentcore:InvokeGateway"], gatewayArns));
+    const role = this.role(
+      `runtime/${runtime.name}`,
+      "bedrock-agentcore.amazonaws.com",
+      statements,
+      this.arn("bedrock-agentcore", "runtime/*"),
+    );
+    const environment: Record<string, string> = Object.fromEntries(
+      (runtime.envVars ?? []).map(({ name, value }) => [name, literal(value)]),
+    );
+    for (const memory of this.project.spec.memories) {
+      const address = this.address("awscc_bedrockagentcore_memory", memory.name);
+      environment[`MEMORY_${memory.name.toUpperCase()}_ID`] = ref(address, "memory_id");
+      environment[`MEMORY_${memory.name.toUpperCase()}_ARN`] = ref(address, "memory_arn");
+    }
+    for (const gateway of this.project.spec.agentCoreGateways) {
+      const address = this.address("awscc_bedrockagentcore_gateway", gateway.name);
+      for (const [suffix, attribute] of Object.entries({
+        URL: "gateway_url",
+        ARN: "gateway_arn",
+        ID: "gateway_identifier",
+      }))
+        environment[`${this.gatewayPrefix(gateway.name)}_${suffix}`] = ref(address, attribute);
+    }
+    const instrumented = runtime.instrumentation?.enableOtel ?? true;
+    // Hosted runtimes inject their OTEL exporter, resource attributes and unified
+    // trace destination. Overriding those here would lose the runtime identifier.
+    const resource = this.add("awscc_bedrockagentcore_runtime", runtime.name, {
+      agent_runtime_name: physicalName,
+      description: optional(runtime.description),
+      role_arn: role.arn,
+      agent_runtime_artifact: {
+        code_configuration: {
+          code: { s3: { bucket: ref(artifact, "bucket"), prefix: ref(artifact, "key") } },
+          runtime: runtime.runtimeVersion,
+          entry_point: instrumented
+            ? ["opentelemetry-instrument", literal(runtime.entrypoint)]
+            : [literal(runtime.entrypoint)],
+        },
+      },
+      network_configuration: { network_mode: "PUBLIC" },
+      protocol_configuration: runtime.protocol ?? "HTTP",
+      environment_variables: environment,
+      request_header_configuration: runtime.requestHeaderAllowlist
+        ? { request_header_allowlist: runtime.requestHeaderAllowlist.map(literal) }
+        : undefined,
+      lifecycle_configuration: runtime.lifecycleConfiguration
+        ? {
+            idle_runtime_session_timeout: runtime.lifecycleConfiguration.idleRuntimeSessionTimeout,
+            max_lifetime: runtime.lifecycleConfiguration.maxLifetime,
+          }
+        : undefined,
+      tags: tagMap(this.project, runtime.tags),
+      depends_on: [role.dependency],
+    });
+    this.publish(
+      "runtime",
+      runtime.name,
+      ref(resource, "agent_runtime_id"),
+      ref(resource, "agent_runtime_arn"),
+    );
+    this.add("aws_cloudwatch_log_group", `runtime/${runtime.name}`, {
+      name: `/aws/bedrock-agentcore/runtimes/${ref(resource, "agent_runtime_id")}-DEFAULT`,
+      retention_in_days: 7,
+      tags: tagMap(this.project),
+    });
+  }
+  private onlineEvaluation(config: OnlineEvalConfig): void {
+    const runtime = this.project.spec.runtimes.find((entry) => entry.name === config.agent)!;
+    const runtimeLogs = this.address("aws_cloudwatch_log_group", `runtime/${runtime.name}`);
+    const name = this.physical(config.name);
+    const outputLogs = this.add("aws_cloudwatch_log_group", `evaluation/${config.name}`, {
+      name: `/aws/bedrock-agentcore/evaluations/${name}`,
+      retention_in_days: 7,
+      tags: tagMap(this.project),
+    });
+    const role = this.role(
+      `evaluation/${config.name}`,
+      "bedrock-agentcore.amazonaws.com",
+      [
+        statement(
+          [
+            "logs:StartQuery",
+            "logs:FilterLogEvents",
+            "logs:GetLogEvents",
+            "logs:DescribeLogStreams",
+          ],
+          [
+            ref(runtimeLogs, "arn"),
+            `${ref(runtimeLogs, "arn")}:*`,
+            this.arn("logs", "log-group:aws/spans"),
+            this.arn("logs", "log-group:aws/spans:*"),
+          ],
+        ),
+        statement(
+          ["logs:DescribeIndexPolicies", "logs:PutIndexPolicy"],
+          [this.arn("logs", "log-group:aws/spans"), this.arn("logs", "log-group:aws/spans:*")],
+        ),
+        statement(
+          [
+            "logs:DescribeLogGroups",
+            "logs:GetQueryResults",
+            "logs:StopQuery",
+            "cloudwatch:GenerateQuery",
+            "cloudwatch:GenerateQueryResultsSummary",
+            "cloudwatch:PutMetricData",
+            "xray:GetTraceSummaries",
+            "xray:BatchGetTraces",
+          ],
+          ["*"],
+        ),
+        statement(["logs:CreateLogStream", "logs:PutLogEvents"], [`${ref(outputLogs, "arn")}:*`]),
+        statement(
+          ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
+          [
+            `arn:${this.partition}:bedrock:*::foundation-model/*`,
+            `arn:${this.partition}:bedrock:*:${this.target.account}:inference-profile/*`,
+            `arn:${this.partition}:bedrock:*:${this.target.account}:application-inference-profile/*`,
+          ],
+        ),
+        statement(
+          ["bedrock-agentcore:Evaluate", "bedrock-agentcore:GetEvaluator"],
+          config.evaluators.map(
+            (evaluator) => `arn:${this.partition}:bedrock-agentcore:::evaluator/${evaluator}`,
+          ),
+        ),
+        statement(
+          ["bedrock-agentcore:StartBatchEvaluation"],
+          [this.arn("bedrock-agentcore", "batch-evaluate/*")],
+        ),
+        statement(
+          ["bedrock-agentcore:GetOnlineEvaluationConfig"],
+          [this.arn("bedrock-agentcore", `online-evaluation-config/${name}-*`)],
+        ),
+      ],
+      [
+        this.arn("bedrock-agentcore", "online-evaluation-config/*"),
+        this.arn("bedrock-agentcore", "evaluator/*"),
+      ],
+    );
+    const resource = this.add("awscc_bedrockagentcore_online_evaluation_config", config.name, {
+      online_evaluation_config_name: name,
+      description: optional(config.description),
+      evaluation_execution_role_arn: role.arn,
+      data_source_config: {
+        cloudwatch_logs: {
+          log_group_names: [ref(runtimeLogs, "name")],
+          service_names: [`${this.physical(runtime.name)}.DEFAULT`],
+        },
+      },
+      evaluators: config.evaluators.map((evaluator) => ({ evaluator_id: literal(evaluator) })),
+      rule: {
+        sampling_config: { sampling_percentage: config.samplingRate },
+        session_config: { session_timeout_minutes: 5 },
+      },
+      execution_status: config.enableOnCreate === false ? "DISABLED" : "ENABLED",
+      output_config: {
+        cloudwatch_config: {
+          log_group_name: ref(outputLogs, "name"),
+          result_destination: "DEDICATED_LOG_GROUP",
+        },
+      },
+      tags: tagList(tagMap(this.project, config.tags)),
+      depends_on: [role.dependency],
+    });
+    this.publish(
+      "online-eval",
+      config.name,
+      ref(resource, "online_evaluation_config_id"),
+      ref(resource, "online_evaluation_config_arn"),
+    );
+  }
+}
diff --git a/src/core/project/backends/terraform/state.ts b/src/core/project/backends/terraform/state.ts
new file mode 100644
index 0000000000..6cc390d1ff
--- /dev/null
+++ b/src/core/project/backends/terraform/state.ts
@@ -0,0 +1,111 @@
+import { mkdir, open, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { ProjectStateError } from "../../../../errors";
+import type { Project } from "../../../../handlers/project/types";
+import type { AwsDeploymentTarget } from "../../../../projectSchemas/aws-targets";
+
+const resourceSchema = z.object({
+  resourceType: z.enum([
+    "runtime",
+    "memory",
+    "gateway",
+    "gateway-target",
+    "policy-engine",
+    "policy",
+    "online-eval",
+  ]),
+  name: z.string(),
+  parentName: z.string().optional(),
+  arn: z.string().optional(),
+  id: z.string(),
+});
+
+export type TerraformResource = z.infer<typeof resourceSchema>;
+
+const stateSchema = z.object({
+  resources: z
+    .array(z.object({ mode: z.string() }).passthrough())
+    .optional()
+    .default([]),
+  outputs: z
+    .record(z.string(), z.object({ value: z.unknown() }).passthrough())
+    .optional()
+    .default({}),
+});
+
+/** A local Terraform state belongs to exactly one project, target, account, and region. */
+export class TerraformState {
+  readonly directory: string;
+
+  constructor(project: Project, target: AwsDeploymentTarget | "build") {
+    const key = target === "build" ? "build" : `${target.name}-${target.account}-${target.region}`;
+    if (!/^[a-zA-Z0-9_-]+$/.test(key)) {
+      throw new ProjectStateError("Invalid Terraform target directory");
+    }
+    this.directory = join(project.rootPath, "agentcore", "terraform", key);
+  }
+
+  async lock(): Promise<() => Promise<void>> {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const path = join(this.directory, ".agentcore-operation.lock");
+    try {
+      const handle = await open(path, "wx", 0o600);
+      try {
+        await handle.writeFile(
+          JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }),
+        );
+      } finally {
+        await handle.close();
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      throw new ProjectStateError(
+        `Another operation owns ${path}. If its process has stopped, remove the lock file and retry.`,
+      );
+    }
+    return () => rm(path, { force: true });
+  }
+
+  private async read() {
+    let text: string;
+    try {
+      text = await readFile(join(this.directory, "terraform.tfstate"), "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    }
+    const parsed = stateSchema.safeParse(JSON.parse(text));
+    if (!parsed.success) {
+      throw new ProjectStateError(
+        `Cannot read Terraform state in ${this.directory}. Preserve the state file and repair it before retrying.`,
+      );
+    }
+    return parsed.data;
+  }
+
+  async hasManagedResources(): Promise<boolean> {
+    return (await this.read())?.resources.some(({ mode }) => mode === "managed") ?? false;
+  }
+
+  async outputs(): Promise<Record<string, unknown>> {
+    return Object.fromEntries(
+      Object.entries((await this.read())?.outputs ?? {}).map(([key, output]) => [
+        key,
+        output.value,
+      ]),
+    );
+  }
+
+  async resources(): Promise<TerraformResource[]> {
+    const outputs = await this.outputs();
+    if (outputs.project_resources === undefined) return [];
+    const parsed = z.array(resourceSchema).safeParse(outputs.project_resources);
+    if (!parsed.success) {
+      throw new ProjectStateError(
+        `Terraform project_resources output in ${this.directory} is not a recognized resource list.`,
+      );
+    }
+    return parsed.data;
+  }
+}
diff --git a/src/core/project/index.tsx b/src/core/project/index.tsx
index a543d8165a..071996988b 100644
--- a/src/core/project/index.tsx
+++ b/src/core/project/index.tsx
@@ -1,5 +1,6 @@
 export { FsProjectManager } from "./manager";
 export { CdkBackend, type CdkBackendConfig } from "./backends/cdk";
+export { TerraformBackend, type TerraformBackendConfig } from "./backends/terraform";
 export type {
   DeployBackendInput,
   ProjectBackend,
diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts
index d635ab500f..67492bcd45 100644
--- a/src/core/project/manager.test.ts
+++ b/src/core/project/manager.test.ts
@@ -148,6 +148,76 @@ async function projectManifest(projectRoot: string): Promise<string[]> {
 }
 
 describe("FsProjectManager.create", () => {
+  test("creates an empty Terraform project without requiring or scaffolding CDK", async () => {
+    await inTempDirectory();
+    const { manager: subject, commands, checkedTools } = manager();
+
+    const { project } = await runCreate(subject, {
+      name: "example",
+      managedBy: "Terraform",
+      skipGit: true,
+    });
+
+    expect(project.spec.managedBy).toBe("Terraform");
+    expect(project.spec.runtimes).toEqual([]);
+    expect(existsSync(join(project.rootPath, "agentcore", "cdk"))).toBe(false);
+    expect(commands).toEqual([]);
+    expect(checkedTools).toEqual([]);
+    const gitignore = await readFile(join(project.rootPath, ".gitignore"), "utf8");
+    expect(gitignore).toContain("agentcore/terraform/");
+    expect(gitignore).toContain("*.tfstate");
+    expect((await subject.resolve({ filePath: project.rootPath }))?.spec.managedBy).toBe(
+      "Terraform",
+    );
+  });
+
+  test("installs Python runtime dependencies for Terraform without installing CDK", async () => {
+    await inTempDirectory();
+    const { manager: subject, commands, checkedTools } = manager();
+
+    const { project } = await runCreate(subject, {
+      name: "example",
+      managedBy: "Terraform",
+      scaffoldRuntimeInput: AGENT_PYTHON_STRANDS,
+      skipGit: true,
+    });
+
+    expect(project.spec.managedBy).toBe("Terraform");
+    expect(project.spec.runtimes).toHaveLength(1);
+    expect(project.spec.memories).toHaveLength(1);
+    expect(commands).toEqual([
+      {
+        command: ["uv", "sync"],
+        cwd: join(project.rootPath, "app", AGENT_PYTHON_STRANDS.runtimeName),
+      },
+    ]);
+    expect(checkedTools).not.toContain("npm");
+    expect(checkedTools).toContain("uv");
+  });
+
+  test.each([
+    { scaffoldRuntimeInput: AGENT_TYPESCRIPT_STRANDS },
+    { scaffoldRuntimeInput: AGENT_PYTHON_STRANDS_CONTAINER },
+    {
+      scaffoldHarnessInput: {
+        name: "agent",
+        model: { provider: "bedrock", modelId: "model" },
+      },
+    },
+  ] as const)(
+    "rejects unsupported Terraform scaffolding before writing files: %j",
+    async (scaffold) => {
+      const directory = await inTempDirectory();
+      const { manager: subject, commands } = manager();
+
+      await expect(
+        runCreate(subject, { name: "example", managedBy: "Terraform", ...scaffold }),
+      ).rejects.toThrow("The Terraform PoC supports empty projects and Python CodeZip");
+      expect(existsSync(join(directory, "example"))).toBe(false);
+      expect(commands).toEqual([]);
+    },
+  );
+
   test("scaffolds the expected file tree into a fresh directory", async () => {
     const directory = await inTempDirectory();
     await runCreate(manager().manager, {
@@ -1795,12 +1865,12 @@ describe("FsProjectManager.build", () => {
     const project = await scaffolded(subject, directory);
     commands.length = 0;
 
-    // CDK is the only backend today; the cast stands in for a future one.
+    // The cast stands in for a backend that is not registered.
     const foreign = {
       ...project,
-      spec: { ...project.spec, managedBy: "Terraform" as Project["spec"]["managedBy"] },
+      spec: { ...project.spec, managedBy: "Other" as Project["spec"]["managedBy"] },
     };
-    await expect(drain(subject.build(foreign))).rejects.toThrow(/unsupported backend: Terraform/);
+    await expect(drain(subject.build(foreign))).rejects.toThrow(/unsupported backend: Other/);
     expect(commands).toEqual([]);
   });
 
@@ -1822,6 +1892,98 @@ describe("FsProjectManager.build", () => {
   });
 });
 
+test("Terraform projects keep add/remove and route build, deploy, and discovery to their backend", async () => {
+  await inTempDirectory();
+  const calls: string[] = [];
+  const target: AwsDeploymentTarget = {
+    name: "default",
+    account: "111122223333",
+    region: "us-west-2",
+  };
+  const backend: ProjectBackend = {
+    async *build(project) {
+      calls.push(`build:${project.spec.managedBy}`);
+      yield { type: "step", message: "Building Terraform configuration" };
+    },
+    async *deploy(project, input) {
+      expect(input.target).toEqual(target);
+      calls.push(`deploy:${project.spec.memories[0]?.name}`);
+      yield { type: "step", message: "Deploying Terraform configuration" };
+      return { outputs: {} };
+    },
+    async resolveDeployedResources(_project, input) {
+      expect(input.target).toEqual(target);
+      calls.push("invoke");
+      return [
+        {
+          resourceType: "runtime",
+          name: "agent",
+          id: "agent-runtime-id",
+          target,
+          credentialProvider: async () => ({
+            accessKeyId: "test-key",
+            secretAccessKey: "test-secret",
+          }),
+        },
+      ];
+    },
+    async resolveProjectResources() {
+      calls.push("status");
+      return [{ resourceType: "memory", name: "recall", deploymentState: "local-only" }];
+    },
+  };
+  const subject = new FsProjectManager({
+    logger: createSilentLogger(),
+    identity: new TestIdentityClient(),
+    enableTransactionSearch: async () => {},
+    backends: { Terraform: backend },
+  });
+  const { project } = await runCreate(subject, {
+    name: "example",
+    managedBy: "Terraform",
+    scaffoldRuntimeInput: { ...AGENT_PYTHON, runtimeName: "agent" },
+    skipInstall: true,
+    skipGit: true,
+  });
+  await writeFile(
+    join(project.rootPath, "agentcore", "aws-targets.json"),
+    JSON.stringify([target]),
+  );
+  const updated = await runAdd(subject, project, {
+    resourceType: "memory",
+    resourceConfig: { name: "recall", eventExpiryDuration: 30, strategies: [] },
+  });
+  for await (const _event of subject.build(updated)) {
+    // Drain the backend operation.
+  }
+  for await (const _event of subject.deploy(updated, {
+    target: "default",
+    region: "us-east-1",
+    confirmTeardown: async () => false,
+  })) {
+    // Drain the backend operation.
+  }
+  expect(
+    (
+      await subject.resolveDeployedResource(updated, {
+        target: "default",
+        resourceType: "runtime",
+        name: "agent",
+      })
+    ).id,
+  ).toBe("agent-runtime-id");
+  expect((await subject.resolveProjectResources(updated, { target: "default" })).resources).toEqual(
+    [{ resourceType: "memory", name: "recall", deploymentState: "local-only" }],
+  );
+  const removed = await subject.removeResource(updated, {
+    resourceType: "memory",
+    name: "recall",
+  });
+  expect(removed.project.spec.managedBy).toBe("Terraform");
+  expect(removed.project.spec.memories).toEqual([]);
+  expect(calls).toEqual(["build:Terraform", "deploy:recall", "invoke", "status"]);
+});
+
 describe("FsProjectManager.deploy", () => {
   type DeployCall = { project: Project; input: DeployBackendInput };
 
@@ -2447,6 +2609,28 @@ describe("FsProjectManager.resolve", () => {
     },
   );
 
+  test("ignores a stale CDK dependency when resolving a Terraform project", async () => {
+    const { root, configPath } = await v1Project("^0.1.0-alpha.19");
+    await writeFile(
+      configPath,
+      JSON.stringify({ name: "example", version: 2, managedBy: "Terraform" }),
+    );
+
+    expect((await manager().manager.resolve({ filePath: root }))?.spec.managedBy).toBe("Terraform");
+  });
+
+  test("reports invalid Terraform configuration instead of a stale CDK dependency", async () => {
+    const { root, configPath } = await v1Project("^0.1.0-alpha.19");
+    await writeFile(
+      configPath,
+      JSON.stringify({ name: "invalid!", version: 2, managedBy: "Terraform" }),
+    );
+
+    await expect(manager().manager.resolve({ filePath: root })).rejects.toBeInstanceOf(
+      DeserializationError,
+    );
+  });
+
   test.each([
     undefined,
     19,
diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx
index f9c329a485..13935336c0 100644
--- a/src/core/project/manager.tsx
+++ b/src/core/project/manager.tsx
@@ -88,6 +88,7 @@ import {
 import { isChinaRegion } from "../partition";
 import z from "zod";
 import { CdkBackend, type TransactionSearchEnabler } from "./backends/cdk";
+import { TerraformBackend } from "./backends/terraform";
 import { resolveAwsAccount } from "./backends/cdk/environment";
 import type { ProjectBackend } from "./backends/types";
 import {
@@ -428,6 +429,13 @@ export class FsProjectManager implements ProjectManager {
         checkTool: config.checkTool,
         json: config.json,
       }),
+      Terraform: new TerraformBackend({
+        logger: config.logger,
+        enableTransactionSearch: config.enableTransactionSearch,
+        runner: config.runner,
+        checkTool: config.checkTool,
+        json: config.json,
+      }),
     };
     this.templateRenderer = config.templateRenderer ?? new HandlebarsTemplateRenderer();
     this.resolveAccount = config.resolveAccount ?? resolveAwsAccount;
@@ -438,10 +446,11 @@ export class FsProjectManager implements ProjectManager {
     if (!rootPath) return undefined;
 
     const configPath = projectSpecPath(rootPath);
-    const cdkDependency = await this.declaredCdkDependency(rootPath);
     try {
       const spec = await this.json.read(configPath, ProjectSpecSchema);
-      assertCdkLibraryMatches("v1", cdkDependency);
+      if (spec.managedBy === "CDK") {
+        assertCdkLibraryMatches("v1", await this.declaredCdkDependency(rootPath));
+      }
       return {
         name: spec.name,
         rootPath,
@@ -450,16 +459,21 @@ export class FsProjectManager implements ProjectManager {
     } catch (error) {
       if (error instanceof DeserializationError) {
         const header = await this.json
-          .read(configPath, z.object({ version: z.unknown().optional() }))
+          .read(
+            configPath,
+            z.object({ version: z.unknown().optional(), managedBy: z.unknown().optional() }),
+          )
           .catch(() => undefined);
         if (projectFormat(header) === "v0") {
+          const cdkDependency = await this.declaredCdkDependency(rootPath);
           const warning = v0DependencyWarning(cdkDependency);
           if (warning) throw new ProjectStateError(warning, { cause: error });
           assertCdkLibraryMatches("v0", cdkDependency, error);
           return loadLegacyProject(rootPath, this.json);
         }
         // An invalid v1 spec on a v0 CDK app is almost always a hand-bumped version.
-        if (header?.version === 2) assertCdkLibraryMatches("v1", cdkDependency, error);
+        if (header?.version === 2 && header.managedBy !== "Terraform")
+          assertCdkLibraryMatches("v1", await this.declaredCdkDependency(rootPath), error);
       }
       throw error;
     }
@@ -490,6 +504,19 @@ export class FsProjectManager implements ProjectManager {
       );
     }
 
+    if (
+      input.managedBy === "Terraform" &&
+      (input.scaffoldHarnessInput ||
+        (input.scaffoldRuntimeInput &&
+          (input.scaffoldRuntimeInput.language !== "Python" ||
+            input.scaffoldRuntimeInput.build !== "CodeZip")))
+    ) {
+      throw new InputValidationError(
+        "The Terraform PoC supports empty projects and Python CodeZip runtime templates. " +
+          "Use --template empty or --template agent-python-minimal.",
+      );
+    }
+
     if (input.scaffoldHarnessInput) {
       validateHarnessTemplateSource(input.scaffoldHarnessInput);
     }
@@ -499,7 +526,7 @@ export class FsProjectManager implements ProjectManager {
 
     const { tree: projectTree, envEntries } = await createProjectTree(
       { templateRenderer: this.templateRenderer, assetSource: this.assetSource },
-      { projectName: input.name },
+      { projectName: input.name, managedBy: input.managedBy },
       { runtime: scaffoldRuntimeInput, importBedrockAgent: input.importBedrockAgent },
     );
 
@@ -534,8 +561,10 @@ export class FsProjectManager implements ProjectManager {
     // A failed step leaves the scaffolded files in place; the error carries the
     // failing command, its directory, and its output.
     if (!input.skipInstall) {
-      yield { type: "step", message: "Installing CDK dependencies with npm" };
-      yield* this.run(NPM_INSTALL, join(destination, "agentcore", "cdk"), npmProgressLine);
+      if ((input.managedBy ?? "CDK") === "CDK") {
+        yield { type: "step", message: "Installing CDK dependencies with npm" };
+        yield* this.run(NPM_INSTALL, join(destination, "agentcore", "cdk"), npmProgressLine);
+      }
 
       if (scaffoldRuntimeInput) {
         const appDir = join(destination, "app", scaffoldRuntimeInput.runtimeName);
@@ -1725,7 +1754,9 @@ export class FsProjectManager implements ProjectManager {
 
   private async checkCreateDependencies(input: CreateProjectInput): Promise<void> {
     if (!input.skipInstall) {
-      await this.checkTool("npm", NODE_INSTALL_HINT);
+      if ((input.managedBy ?? "CDK") === "CDK") {
+        await this.checkTool("npm", NODE_INSTALL_HINT);
+      }
       if (
         input.scaffoldRuntimeInput?.language === "Python" &&
         templateManagesDependencies(resolveRuntimeTemplateProfile(input.scaffoldRuntimeInput))
diff --git a/src/core/project/templates/project.ts b/src/core/project/templates/project.ts
index f2aa53af1a..607faeb7b9 100644
--- a/src/core/project/templates/project.ts
+++ b/src/core/project/templates/project.ts
@@ -10,6 +10,7 @@ import { getRuntimeTemplateResolver } from "./runtime";
 import { mergeSpecEntries } from "./spec";
 import type { Template, TemplateRenderer } from "./types";
 import type { EnvLocalEntry } from "../../../handlers/project/types";
+import type { ManagedBy } from "../../../projectSchemas/project";
 
 type CreateProjectConfig = {
   assetSource: AssetSource;
@@ -18,9 +19,10 @@ type CreateProjectConfig = {
 /** Scaffold a project from scratch, with optional support for rendering a runtime with the project. **/
 export async function createProjectTree(
   config: CreateProjectConfig,
-  input: { projectName: string },
+  input: { projectName: string; managedBy?: ManagedBy },
   options?: { runtime?: ScaffoldRuntimeInput; importBedrockAgent?: ImportBedrockAgentInput },
 ): Promise<{ tree: FsTreeNode; envEntries: EnvLocalEntry[] }> {
+  const managedBy = input.managedBy ?? "CDK";
   const templates: Template[] = [];
   if (options?.runtime) {
     const runtimeConfig: RuntimeResourceConfig = {
@@ -39,16 +41,26 @@ export async function createProjectTree(
   const envEntries = templates.flatMap((template) => template.envEntries ?? []);
 
   const tree = FsTreeNode.createDirectory(".", [
-    FsTreeNode.createFile(".gitignore", () =>
-      config.assetSource.read("templates/shared/gitignore.template"),
-    ),
+    FsTreeNode.createFile(".gitignore", async () => {
+      const shared = await config.assetSource.read("templates/shared/gitignore.template");
+      return managedBy === "Terraform"
+        ? `${shared}\n# Terraform generated configuration, assets, and local state\nagentcore/terraform/\n.terraform/\n*.tfstate\n*.tfstate.*\n*.tfplan\ncrash.log\n`
+        : shared;
+    }),
     FsTreeNode.createDirectory("agentcore", [
-      await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }),
+      ...(managedBy === "CDK"
+        ? [
+            await FsTreeNode.fromAssetSource(
+              { assetSource: config.assetSource },
+              { assetDir: "cdk" },
+            ),
+          ]
+        : []),
       FsTreeNode.createFile("agentcore.json", async () =>
         json({
           name: input.projectName,
           version: 2,
-          managedBy: "CDK",
+          managedBy,
           ...mergeSpecEntries(templates.map(({ spec }) => spec)),
         }),
       ),
diff --git a/src/handlers/project/create/index.ts b/src/handlers/project/create/index.ts
index dfc7ee1852..7fa97bccaa 100644
--- a/src/handlers/project/create/index.ts
+++ b/src/handlers/project/create/index.ts
@@ -16,7 +16,11 @@ import {
   type ProjectManager,
   type ScaffoldHarnessInput,
 } from "../types";
-import { ProjectNameSchema } from "../../../projectSchemas/project";
+import {
+  ManagedBySchema,
+  ProjectNameSchema,
+  type ManagedBy,
+} from "../../../projectSchemas/project";
 import { DEFAULT_TARGET_NAME } from "../../../projectSchemas/aws-targets";
 import {
   HARNESS_DEFAULT_MODEL_IDS,
@@ -64,9 +68,13 @@ export function createNextStep(scaffoldsRuntime: boolean): string {
  * `agentcore add`. Harnesses are left out in China regions, where they are not
  * available.
  */
-export function emptyProjectNextSteps(name: string, china: boolean): string[] {
+export function emptyProjectNextSteps(
+  name: string,
+  china: boolean,
+  managedBy: ManagedBy = "CDK",
+): string[] {
   const steps: [string, string][] = [
-    ...(china
+    ...(china || managedBy === "Terraform"
       ? []
       : [["agentcore add harness", "add a config-based agent: pick a model, prompt, and tools"]]),
     ["agentcore add runtime", "add a code-based agent from a template"],
@@ -86,12 +94,16 @@ export function emptyProjectNextSteps(name: string, china: boolean): string[] {
 export const EMPTY_PROJECT_SUMMARY = "It has no agents or other resources yet.";
 
 /** The full message printed after creating an empty project. */
-export function emptyProjectCreatedMessage(name: string, china: boolean): string {
+export function emptyProjectCreatedMessage(
+  name: string,
+  china: boolean,
+  managedBy: ManagedBy = "CDK",
+): string {
   return [
     `Created empty project '${name}' in ./${name}. ${EMPTY_PROJECT_SUMMARY}`,
     "",
     "Next steps:",
-    ...emptyProjectNextSteps(name, china).map((step) => `  ${step}`),
+    ...emptyProjectNextSteps(name, china, managedBy).map((step) => `  ${step}`),
     "",
   ].join("\n");
 }
@@ -103,6 +115,11 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
     middlewares: config.middlewares,
     flags: [
       flag("name", "name of the project to create", ProjectNameSchema),
+      flag(
+        "managed-by",
+        "infrastructure backend (Terraform is an experimental AWSCC PoC)",
+        ManagedBySchema,
+      ),
       flag(
         "template",
         "the template to scaffold the Runtime from",
@@ -118,7 +135,7 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
     ],
     handle: async (ctx, flags) => {
       const name = flags["name"];
-      if (!flags["skip-install"]) {
+      if (!flags["skip-install"] && flags["managed-by"] === "CDK") {
         assertProjectPathFits(name, ctx.require(PlatformKey), {
           alternative: "pass --skip-install and install the CDK dependencies yourself",
         });
@@ -127,6 +144,7 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
       const template = flags["template"];
       const base = {
         name,
+        managedBy: flags["managed-by"],
         skipInstall: flags["skip-install"],
         skipGit: flags["skip-git"],
       };
@@ -178,7 +196,9 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
         },
         () => {
           if (template === EMPTY_TEMPLATE_NAME) {
-            config.io.stderr.write(emptyProjectCreatedMessage(name, isChinaRegion(region)));
+            config.io.stderr.write(
+              emptyProjectCreatedMessage(name, isChinaRegion(region), flags["managed-by"]),
+            );
             return;
           }
           config.io.stderr.write(`Created project '${name}' in ./${name}\n`);
diff --git a/src/handlers/project/deploy/index.ts b/src/handlers/project/deploy/index.ts
index 8495d8825a..f39043d2e3 100644
--- a/src/handlers/project/deploy/index.ts
+++ b/src/handlers/project/deploy/index.ts
@@ -71,7 +71,7 @@ export const createDeployProjectHandler = (config: DeployProjectHandlerConfig) =
       ),
       flag(
         "yes",
-        "confirm removing the target's stack when the project declares nothing to deploy",
+        "confirm removing the target's resources when the project declares nothing to deploy",
         z.boolean().default(false),
       ),
     ],
diff --git a/src/handlers/project/project.test.ts b/src/handlers/project/project.test.ts
index f98d4a4ea9..b3ace74324 100644
--- a/src/handlers/project/project.test.ts
+++ b/src/handlers/project/project.test.ts
@@ -47,6 +47,41 @@ test("project dev requires an AgentCore project", async () => {
 });
 
 describe("project create", () => {
+  test("creates a Terraform project through --managed-by without CDK installation", async () => {
+    const { path: directory, cleanup } = await inTempDirectory();
+    cleanups.push(cleanup);
+    const { io, core } = await run([
+      "create",
+      "--name",
+      "TerraformProject",
+      "--managed-by",
+      "Terraform",
+      "--skip-git",
+    ]);
+
+    const projectRoot = join(directory, "TerraformProject");
+    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
+    expect(spec.managedBy).toBe("Terraform");
+    expect(existsSync(join(projectRoot, "agentcore", "cdk"))).toBe(false);
+    expect(core.projectCommands).toEqual([]);
+    expect(io.stderr()).toContain("agentcore add runtime");
+    expect(io.stderr()).not.toContain("agentcore add harness");
+  });
+
+  test("does not apply the CDK node_modules Windows path limit to Terraform creation", async () => {
+    const { path, cleanup } = await inTempDirectory();
+    cleanups.push(cleanup);
+    const deep = join(path, "n".repeat(120));
+    await mkdir(deep);
+    process.chdir(deep);
+
+    await run(["create", "--name", "Deep", "--managed-by", "Terraform", "--skip-git"], {
+      platform: "win32",
+    });
+
+    expect(await readdir(deep)).toEqual(["Deep"]);
+  });
+
   test("--json returns the created project without human success text", async () => {
     const { path: directory, cleanup } = await inTempDirectory();
     cleanups.push(cleanup);
diff --git a/src/handlers/project/types.ts b/src/handlers/project/types.ts
index 38e75d2009..0ab639a555 100644
--- a/src/handlers/project/types.ts
+++ b/src/handlers/project/types.ts
@@ -5,7 +5,7 @@ import type { PaymentConnectorSchema, PaymentManagerSchema } from "../../project
 import type { ConfigBundleSchema } from "../../projectSchemas/config-bundle";
 import { MemorySchema } from "../../projectSchemas/memory";
 import type { EvaluatorSchema, EvaluationLevel } from "../../projectSchemas/evaluator";
-import type { ProjectSpecSchema } from "../../projectSchemas/project";
+import type { ManagedBy, ProjectSpecSchema } from "../../projectSchemas/project";
 import z from "zod";
 import type { ImportBedrockAgentInput, RuntimeResourceConfig } from "./add/runtime/types";
 import type { OnlineEvalConfigSchema } from "../../projectSchemas/online-eval-config";
@@ -22,6 +22,8 @@ import { RuntimeTemplateProfileSchema } from "./templateProfile";
 type CreateProjectInputBase = {
   /** The name of the project; also the directory it is scaffolded into. */
   name: string;
+  /** Infrastructure backend for the new project. Defaults to CDK. */
+  managedBy?: ManagedBy;
   /** Skip installing dependencies (npm install, uv sync). */
   skipInstall?: boolean;
   /** Skip initializing a git repository. */
@@ -527,7 +529,7 @@ export interface ProjectManager {
   /** Scaffold a new AgentCore project from the given template. */
   create(input: CreateProjectInput): AsyncGenerator<ProjectEvent, Project>;
 
-  /** Compile the project's CDK app and synthesize its CloudFormation templates. */
+  /** Generate and validate the project's infrastructure configuration. */
   build(project: Project): AsyncGenerator<ProjectEvent, void>;
 
   /** Deploy the project to one of its configured AWS targets. */
diff --git a/src/projectSchemas/project.test.ts b/src/projectSchemas/project.test.ts
index fbba508331..886c5e7123 100644
--- a/src/projectSchemas/project.test.ts
+++ b/src/projectSchemas/project.test.ts
@@ -13,6 +13,14 @@ const runtime = {
 };
 
 describe("project custom validation", () => {
+  test.each([
+    [undefined, "CDK"],
+    ["CDK", "CDK"],
+    ["Terraform", "Terraform"],
+  ] as const)("selects backend %s as %s", (managedBy, expected) => {
+    expect(ProjectSpecSchema.parse({ ...minimalProject, managedBy }).managedBy).toBe(expected);
+  });
+
   test.each([1, 3, "2", undefined, null])("rejects project version %j", (version) => {
     const result = ProjectSpecSchema.safeParse({ ...minimalProject, version });
     expect(result.success).toBe(false);
diff --git a/src/projectSchemas/project.ts b/src/projectSchemas/project.ts
index 756e6eaec7..df23879817 100644
--- a/src/projectSchemas/project.ts
+++ b/src/projectSchemas/project.ts
@@ -13,7 +13,7 @@ import { PolicyEngineSchema } from "./policy";
 import { TagsSchema } from "./tags";
 import { uniqueBy } from "./zod-util";
 import { z } from "zod";
-export const ManagedBySchema = z.enum(["CDK"]).default("CDK");
+export const ManagedBySchema = z.enum(["CDK", "Terraform"]).default("CDK");
 export type ManagedBy = z.infer<typeof ManagedBySchema>;
 export const ProjectNameSchema = z
   .string()

From ba41842515add446657df69c0cd2b41c39872b86 Mon Sep 17 00:00:00 2001
From: jariy17 <tjariy+jariy17@users.noreply.github.com>
Date: Thu, 15 Oct 2026 21:35:52 +0000
Subject: [PATCH 2/5] feat(project): scaffold pinned Terraform module with iac
 selection

---
 command.md                                    |   2 +-
 examples/terraform-poc/README.md              |  61 +-
 examples/terraform-poc/terraform/.gitignore   |   9 +
 examples/terraform-poc/terraform/main.tf      |  10 +
 examples/terraform-poc/terraform/outputs.tf   |  35 +
 examples/terraform-poc/terraform/providers.tf |  24 +
 examples/terraform-poc/terraform/variables.tf |  18 +
 src/core/project/backends/terraform.test.ts   |  66 +-
 src/core/project/backends/terraform.ts        |  99 +-
 src/core/project/backends/terraform/assets.ts |   2 +-
 .../backends/terraform/compiler.test.ts       | 353 -------
 .../project/backends/terraform/compiler.ts    | 969 ------------------
 .../backends/terraform/preflight.test.ts      | 162 +++
 .../project/backends/terraform/preflight.ts   | 271 +++++
 .../backends/terraform/project.test.ts        | 205 ++++
 .../project/backends/terraform/project.ts     | 260 +++++
 .../project/backends/terraform/state.test.ts  | 125 +++
 src/core/project/backends/terraform/state.ts  | 161 ++-
 src/core/project/backends/terraform/types.ts  |  13 +
 src/core/project/manager.test.ts              |  16 +-
 src/core/project/manager.tsx                  |   8 +
 src/core/project/templates/project.ts         |   2 +-
 src/handlers/project/create/index.ts          |  20 +-
 src/handlers/project/project.test.ts          |  69 +-
 src/handlers/project/types.ts                 |   2 +
 25 files changed, 1548 insertions(+), 1414 deletions(-)
 create mode 100644 examples/terraform-poc/terraform/.gitignore
 create mode 100644 examples/terraform-poc/terraform/main.tf
 create mode 100644 examples/terraform-poc/terraform/outputs.tf
 create mode 100644 examples/terraform-poc/terraform/providers.tf
 create mode 100644 examples/terraform-poc/terraform/variables.tf
 delete mode 100644 src/core/project/backends/terraform/compiler.test.ts
 delete mode 100644 src/core/project/backends/terraform/compiler.ts
 create mode 100644 src/core/project/backends/terraform/preflight.test.ts
 create mode 100644 src/core/project/backends/terraform/preflight.ts
 create mode 100644 src/core/project/backends/terraform/project.test.ts
 create mode 100644 src/core/project/backends/terraform/project.ts
 create mode 100644 src/core/project/backends/terraform/state.test.ts
 create mode 100644 src/core/project/backends/terraform/types.ts

diff --git a/command.md b/command.md
index 9e4489bb85..f434a5173a 100644
--- a/command.md
+++ b/command.md
@@ -243,7 +243,7 @@ create a new project
 **Options**
 
 - `--name <name>`: name of the project to create (required)
-- `--managed-by <managed-by>`: infrastructure backend (Terraform is an experimental AWSCC PoC) (default: "CDK")
+- `--iac <iac>`: infrastructure backend: CDK or Terraform (experimental AWSCC PoC) (default: "CDK")
 - `--template <template>`: the template to scaffold the Runtime from (default: "empty")
 - `--skip-install`: skip installing dependencies (npm install, uv sync) (default: false)
 - `--skip-git`: skip initializing a git repository (default: false)
diff --git a/examples/terraform-poc/README.md b/examples/terraform-poc/README.md
index 19e050490c..a387d33f64 100644
--- a/examples/terraform-poc/README.md
+++ b/examples/terraform-poc/README.md
@@ -7,7 +7,9 @@ This example exercises an experimental Terraform deployment backend for a small
 - A policy engine associated with the gateway.
 - Online evaluations using `Builtin.Helpfulness`.
 
-The backend generates Terraform JSON configuration from `agentcore/agentcore.json`. AgentCore resources use AWSCC 1.106.0, except for gateway targets: that release does not expose a gateway target resource, so the example uses AWS provider 6.69.0 for its Lambda target. The AWS provider also manages IAM, S3, Lambda, and logs. Resource creation is owned by Terraform.
+The backend scaffolds HCL root files and references the reusable `agentcore-application` module maintained in the AgentCore L3 constructs repository. The root reads `agentcore/agentcore.json` and passes a typed `spec` object into the module. Terraform reads the JSON on every plan, so changing a supported setting does not require CLI regeneration.
+
+AgentCore resources use AWSCC 1.106.0, except for gateway targets: that release does not expose a gateway target resource, so the example uses AWS provider 6.69.0 for its Lambda target. The AWS provider also manages IAM, S3, Lambda, and logs. Resource creation is owned by Terraform.
 
 The example has been packaged reproducibly, validated against both pinned providers, and planned with Terraform 1.16.6 (25 resources). Live deployment, invocation, policy enforcement, evaluation results, updates, and teardown remain unverified. The steps below describe the experiment to run.
 
@@ -18,9 +20,38 @@ The example has been packaged reproducibly, validated against both pinned provid
 - Configure AWS credentials for a disposable development account and an AgentCore-supported region.
 - Ensure the account can invoke the Bedrock model used by the example, `us.amazon.nova-lite-v1:0`. To select another model, add a `MODEL_ID` entry to the runtime's `envVars`.
 
+Set `CLI` to the absolute path of this branch's `dist/index.js`:
+
+```sh
+export CLI=/absolute/path/to/agentcore-cli/dist/index.js
+```
+
 This example creates billable resources and enables online evaluation at 100% sampling. Use it for a bounded experiment and tear it down afterward. The sample `permit(principal, action, resource);` policy permits all gateway actions to authenticated callers; replace it with your intended policy before using the configuration outside this example.
 
-## Deploy the example
+## Create a project
+
+```sh
+node "$CLI" create --name MyTerraformProject --template empty --iac terraform
+```
+
+`--iac` accepts `cdk` or `terraform`, case-insensitively, and defaults to CDK. Terraform projects immediately contain:
+
+```text
+agentcore/
+  agentcore.json
+  terraform/default/
+    main.tf
+    providers.tf
+    variables.tf
+    outputs.tf
+    artifacts.json
+```
+
+Creation does not require Terraform or AWS credentials. Use the existing `agentcore add` commands to populate the project, or edit its JSON directly. The backend validates its supported subset before deployment and reports unsupported resource types or settings.
+
+The customer owns the root `.tf` files. Build and deploy preserve those edits. The module source is pinned to an immutable commit in the L3 constructs repository; `terraform init` downloads it. During this draft PoC the pin points to the companion PR branch in the contributor fork. Updating the module version is an explicit root HCL change.
+
+## Deploy the connected example
 
 Copy this directory outside the repository before using it so configuration changes and deployment state remain separate from the checked-in fixture. Set `CLI` to the absolute path of this branch's `dist/index.js`.
 
@@ -35,17 +66,31 @@ node "$CLI" deploy --region "$AWS_REGION" --json
 node "$CLI" status --region "$AWS_REGION" --json
 ```
 
-The default deployment target is recorded in `agentcore/aws-targets.json`. Terraform configuration, asset archives, dependency locks, and local state live beneath `agentcore/terraform/`. Keep that directory private and preserve it until teardown completes: Terraform state can contain configuration values and is needed to manage the resources. This PoC uses local state for one operator; shared remote state and CDK-to-Terraform migration are outside its scope.
+Build packages the runtime and Lambda and prepares `agentcore/terraform/default/`. Deploy uses that same directory and writes the account, region, and target variables. The default deployment target is recorded in `agentcore/aws-targets.json`.
+
+Root HCL and the provider lock file can be version-controlled. Generated ZIPs, artifact manifests, deployment variables, plans, and local state are ignored. Preserve state until teardown completes: it can contain sensitive configuration values and is needed to manage resources. This CLI PoC supports default local state for one operator; remote backends, custom state paths, and CDK-to-Terraform migration are outside its scope.
+
+Named targets have separate `agentcore/terraform/<target>/` directories. On first use they inherit the default root's HCL; subsequent builds preserve their own edits. A directory containing managed state is bound to its account, region, and target, so changing those values requires a separate target or an explicit migration.
 
 Deploy also follows the existing CLI setting for enabling CloudWatch Transaction Search. That setup is an account-level telemetry prerequisite, runs outside Terraform, and is not reverted when this example is destroyed. A setup warning must be resolved before treating online evaluation as verified.
 
-To start a new project instead:
+## Change configuration with Terraform directly
+
+After building code artifacts, the generated root works without the CLI:
 
 ```sh
-node "$CLI" create --name MyTerraformProject --template empty --managed-by Terraform
+cd agentcore/terraform/default
+terraform init
+terraform plan -var="account_id=123456789012" -var="region=us-west-2"
 ```
 
-Use the existing `agentcore add` commands to populate the project. The backend validates its supported subset before deployment and reports unsupported resource types or settings. A Terraform project is not a promise of coverage for every `agentcore.json` option.
+Edit a supported value such as memory retention in `agentcore.json`, then run `terraform plan` again. The module receives the updated object immediately. After reviewing the plan, apply it with Terraform. If CLI deploy has already created deployment variables, the `-var` arguments are unnecessary. Changes to application source still require rebuilding the ZIPs and updating their artifact hashes.
+
+The checked-in [`terraform/`](terraform/) directory is also a standalone root example. It references the same pinned module from the L3 constructs repository. Supply `artifacts.json` with the ZIP paths and hashes described in the [module README](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/d3ce7229610ce0bb56d581c55f710e220b58faa4/terraform/modules/agentcore-application/README.md).
+
+The root can pass inline HCL instead of JSON. This allows values from customer resources to enter the `spec` directly, for example `envVars = [{ name = "ORDERS_TABLE", value = aws_dynamodb_table.orders.name }]`. Outputs such as `module.application.runtimes["Agent"].role_name` allow a separate IAM policy to grant that runtime access to the table. Terraform follows these references to order changes.
+
+References between the project's resources are resolved inside the module: policy engine to gateway, Lambda and gateway to target, memories/gateways to runtime, and runtime logs to online evaluation. Circular references are rejected by Terraform. See the [module's inputs and outputs](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/d3ce7229610ce0bb56d581c55f710e220b58faa4/terraform/modules/agentcore-application/README.md) for the contract and limits.
 
 ## Exercise the deployed resources
 
@@ -61,7 +106,7 @@ The memory operation writes an event and lists session events. Semantic extracti
 
 To examine enforcement, change the sample policy to `forbid(principal, action, resource);`, redeploy, and check that calling the tool is denied. Set the policy's `enforcementMode` to `LOG_ONLY`, redeploy, and check its observed behavior before restoring the original policy. The gateway's policy-engine mode remains `ENFORCE`; it is a separate setting.
 
-The compiler also maps the statement through AWSCC's `definition.policy.statement` input. A valid Dogwood statement can be supplied there, but schema support and a successful deployment of a particular Dogwood policy are separate checks.
+The module maps the statement through AWSCC's `definition.policy.statement` input. A valid Dogwood statement can be supplied there, but schema support and a successful deployment of a particular Dogwood policy are separate checks.
 
 ## Updates and teardown
 
@@ -75,3 +120,5 @@ node "$CLI" deploy --yes --region "$AWS_REGION" --json
 ```
 
 Keep the generated directory after a failed apply or teardown so the operation can be retried. Do not edit `managedBy` on an existing CDK deployment to attempt a migration.
+
+The earlier flat-resource Terraform PoC used different resource addresses and directories. This implementation refuses that state rather than silently deploying a second copy; migrating it requires an explicit state migration.
diff --git a/examples/terraform-poc/terraform/.gitignore b/examples/terraform-poc/terraform/.gitignore
new file mode 100644
index 0000000000..fbc6763f53
--- /dev/null
+++ b/examples/terraform-poc/terraform/.gitignore
@@ -0,0 +1,9 @@
+.terraform/
+.terraform.lock.hcl
+*.tfstate
+*.tfstate.*
+*.tfplan
+*.auto.tfvars.json
+artifacts.json
+assets/
+crash.log
diff --git a/examples/terraform-poc/terraform/main.tf b/examples/terraform-poc/terraform/main.tf
new file mode 100644
index 0000000000..767e3a7e36
--- /dev/null
+++ b/examples/terraform-poc/terraform/main.tf
@@ -0,0 +1,10 @@
+# Module implementation is owned by the companion L3 constructs PoC.
+module "application" {
+  source = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=d3ce7229610ce0bb56d581c55f710e220b58faa4"
+
+  spec        = jsondecode(file("${path.module}/../agentcore/agentcore.json"))
+  target_name = var.target_name
+  account_id  = var.account_id
+  region      = var.region
+  artifacts   = jsondecode(file("${path.module}/artifacts.json"))
+}
diff --git a/examples/terraform-poc/terraform/outputs.tf b/examples/terraform-poc/terraform/outputs.tf
new file mode 100644
index 0000000000..0cfe8eabc4
--- /dev/null
+++ b/examples/terraform-poc/terraform/outputs.tf
@@ -0,0 +1,35 @@
+output "project_resources" {
+  value = module.application.project_resources
+  precondition {
+    condition     = data.aws_caller_identity.current.account_id == var.account_id
+    error_message = "AWS credentials do not match account_id."
+  }
+}
+
+output "runtimes" {
+  value = module.application.runtimes
+}
+
+output "memories" {
+  value = module.application.memories
+}
+
+output "gateways" {
+  value = module.application.gateways
+}
+
+output "policy_engines" {
+  value = module.application.policy_engines
+}
+
+output "online_evaluations" {
+  value = module.application.online_evaluations
+}
+
+output "deployment_target" {
+  value = {
+    name    = var.target_name
+    account = var.account_id
+    region  = var.region
+  }
+}
diff --git a/examples/terraform-poc/terraform/providers.tf b/examples/terraform-poc/terraform/providers.tf
new file mode 100644
index 0000000000..ecbdf1b154
--- /dev/null
+++ b/examples/terraform-poc/terraform/providers.tf
@@ -0,0 +1,24 @@
+terraform {
+  required_version = ">= 1.12.0, < 2.0.0"
+  required_providers {
+    awscc = {
+      source  = "hashicorp/awscc"
+      version = "= 1.106.0"
+    }
+    aws = {
+      source  = "hashicorp/aws"
+      version = "= 6.69.0"
+    }
+  }
+}
+
+provider "aws" {
+  region              = var.region
+  allowed_account_ids = [var.account_id]
+}
+
+provider "awscc" {
+  region = var.region
+}
+
+data "aws_caller_identity" "current" {}
diff --git a/examples/terraform-poc/terraform/variables.tf b/examples/terraform-poc/terraform/variables.tf
new file mode 100644
index 0000000000..1fcb3df64f
--- /dev/null
+++ b/examples/terraform-poc/terraform/variables.tf
@@ -0,0 +1,18 @@
+variable "account_id" {
+  type        = string
+  description = "Expected deployment account."
+  validation {
+    condition     = can(regex("^[0-9]{12}$", var.account_id))
+    error_message = "account_id must contain 12 digits."
+  }
+}
+
+variable "region" {
+  type    = string
+  default = "us-west-2"
+}
+
+variable "target_name" {
+  type    = string
+  default = "default"
+}
diff --git a/src/core/project/backends/terraform.test.ts b/src/core/project/backends/terraform.test.ts
index 4ccfb91440..040a9e65e9 100644
--- a/src/core/project/backends/terraform.test.ts
+++ b/src/core/project/backends/terraform.test.ts
@@ -73,11 +73,11 @@ describe("Terraform lifecycle", () => {
     await drain(b.build(p));
     expect(commands.map((command) => command[1])).toEqual(["init", "validate"]);
     expect(commands[0]).toContain("-backend=false");
-    const compiled = await readFile(
-      join(new TerraformState(p, "build").directory, "main.tf.json"),
-      "utf8",
-    );
-    expect(compiled).toContain("000000000000");
+    const root = new TerraformState(p).directory;
+    expect(root).toBe(join(p.rootPath, "agentcore", "terraform", "default"));
+    expect(existsSync(join(root, "main.tf"))).toBe(true);
+    expect(existsSync(join(root, "deployment.auto.tfvars.json"))).toBe(false);
+    expect(await readFile(join(root, "variables.tf"), "utf8")).not.toContain("000000000000");
   });
 
   test("applies the saved plan and resolves resources from target state", async () => {
@@ -89,7 +89,7 @@ describe("Terraform lifecycle", () => {
         await writeFile(
           join(options.cwd, "terraform.tfstate"),
           JSON.stringify({
-            resources: [{ mode: "managed" }],
+            resources: [{ mode: "managed", module: "module.application" }],
             outputs: {
               memory_arn: {
                 value: "arn:aws:bedrock-agentcore:us-east-1:111122223333:memory/example-123",
@@ -107,6 +107,7 @@ describe("Terraform lifecycle", () => {
     expect(calls.map(({ command }) => command[1])).toEqual(["init", "validate", "plan", "apply"]);
     expect(calls.at(-1)!.command.at(-1)).toBe("deployment.tfplan");
     expect(calls[2]!.command).toContain("-out=deployment.tfplan");
+    expect(calls[2]!.command).toContain("-var-file=deployment.auto.tfvars.json");
     expect(calls.every(({ options }) => options.env?.AWS_SESSION_TOKEN === "test-session")).toBe(
       true,
     );
@@ -138,7 +139,10 @@ describe("Terraform lifecycle", () => {
       const p = await project();
       const state = new TerraformState(p, TARGET);
       await mkdir(state.directory, { recursive: true });
-      const stateText = JSON.stringify({ resources: [{ mode: "managed" }], outputs: {} });
+      const stateText = JSON.stringify({
+        resources: [{ mode: "managed", module: "module.application" }],
+        outputs: { deployment_target: { value: TARGET } },
+      });
       await writeFile(join(state.directory, "terraform.tfstate"), stateText);
       const calls: string[] = [];
       const b = backend({
@@ -159,10 +163,11 @@ describe("Terraform lifecycle", () => {
     p.spec.memories = [];
     const state = new TerraformState(p, TARGET);
     await mkdir(state.directory, { recursive: true });
+    await state.bind(TARGET);
     await writeFile(
       join(state.directory, "terraform.tfstate"),
       JSON.stringify({
-        resources: [{ mode: "managed" }],
+        resources: [{ mode: "managed", module: "module.application" }],
         outputs: {},
       }),
     );
@@ -200,7 +205,7 @@ describe("Terraform lifecycle", () => {
     expect(packaged).toBe(false);
   });
 
-  test("isolates state by account and region and excludes removed declarations", async () => {
+  test("refuses to reuse target state in another region and excludes removed declarations", async () => {
     const p = await project();
     const state = new TerraformState(p, TARGET);
     await mkdir(state.directory, { recursive: true });
@@ -208,18 +213,55 @@ describe("Terraform lifecycle", () => {
       join(state.directory, "terraform.tfstate"),
       JSON.stringify({
         outputs: {
+          deployment_target: { value: TARGET },
           project_resources: { value: [{ resourceType: "memory", name: "memory", id: "old" }] },
         },
       }),
     );
     const b = backend();
-    expect(
-      await b.resolveProjectResources(p, { target: { ...TARGET, region: "us-west-2" } }),
-    ).toEqual([{ resourceType: "memory", name: "memory", deploymentState: "local-only" }]);
+    await expect(
+      b.resolveProjectResources(p, { target: { ...TARGET, region: "us-west-2" } }),
+    ).rejects.toThrow("different target, account, or region");
     p.spec.memories = [];
     expect(await b.resolveProjectResources(p, input)).toEqual([]);
   });
 
+  test("build and deploy share the editable default root without resetting target inputs", async () => {
+    const p = await project();
+    const directories: string[] = [];
+    const b = backend({
+      runner: async (_command, options) => {
+        directories.push(options.cwd);
+      },
+    });
+    await drain(b.build(p));
+    const root = new TerraformState(p).directory;
+    await writeFile(join(root, "custom.tf"), "# customer resources\n");
+    await drain(b.deploy(p, input));
+    const targetInputs = await readFile(join(root, "deployment.auto.tfvars.json"), "utf8");
+    await drain(b.build(p));
+    expect(new Set(directories)).toEqual(new Set([root]));
+    expect(await readFile(join(root, "deployment.auto.tfvars.json"), "utf8")).toBe(targetInputs);
+    expect(await readFile(join(root, "custom.tf"), "utf8")).toBe("# customer resources\n");
+  });
+
+  test("rejects a remote backend after init before planning or applying", async () => {
+    const p = await project();
+    const calls: string[] = [];
+    const b = backend({
+      runner: async (command, options) => {
+        calls.push(command[1]!);
+        await mkdir(join(options.cwd, ".terraform"), { recursive: true });
+        await writeFile(
+          join(options.cwd, ".terraform", "terraform.tfstate"),
+          JSON.stringify({ backend: { type: "s3" } }),
+        );
+      },
+    });
+    await expect(drain(b.deploy(p, input))).rejects.toThrow("require local state");
+    expect(calls).toEqual(["init"]);
+  });
+
   test("exclusive lock covers the whole operation", async () => {
     const p = await project();
     const state = new TerraformState(p, TARGET);
diff --git a/src/core/project/backends/terraform.ts b/src/core/project/backends/terraform.ts
index 53b26505c4..1956c140ad 100644
--- a/src/core/project/backends/terraform.ts
+++ b/src/core/project/backends/terraform.ts
@@ -9,7 +9,6 @@ import type {
   ResolvedProjectResource,
 } from "../../../handlers/project/types";
 import {
-  atomicWrite,
   createLineSplitter,
   FsReadWriteJson,
   requireTool,
@@ -18,7 +17,7 @@ import {
   type ReadWriteJson,
 } from "../../../io";
 import type { Logger } from "../../../logging";
-import type { AwsDeploymentTarget } from "../../../projectSchemas/aws-targets";
+import { DEFAULT_TARGET_NAME, type AwsDeploymentTarget } from "../../../projectSchemas/aws-targets";
 import { withOutputEvents } from "../events";
 import type { TransactionSearchEnabler } from "./cdk";
 import { readDeployedState, stackReferenceOf } from "./cdk/deployedState";
@@ -29,7 +28,8 @@ import {
   type CdkCredentialResolver,
 } from "./cdk/toolkit";
 import { TerraformAssetPackager, type TerraformAssetBuilder } from "./terraform/assets";
-import { declaredResources, TerraformCompiler } from "./terraform/compiler";
+import { declaredResources, TerraformProjectValidator } from "./terraform/preflight";
+import { TerraformProjectWriter } from "./terraform/project";
 import { TerraformState } from "./terraform/state";
 import type {
   DeployBackendInput,
@@ -57,7 +57,8 @@ export class TerraformBackend implements ProjectBackend {
   private readonly resolveCredentials: CdkCredentialResolver;
   private readonly resolveAccount: AccountResolver;
   private readonly packageAssets: TerraformAssetBuilder;
-  private readonly compiler = new TerraformCompiler();
+  private readonly validator = new TerraformProjectValidator();
+  private readonly writer: TerraformProjectWriter;
 
   constructor(private readonly config: TerraformBackendConfig) {
     this.runner = config.runner ?? runProcess;
@@ -68,30 +69,24 @@ export class TerraformBackend implements ProjectBackend {
     this.resolveAccount = config.resolveAccount ?? resolveAwsAccount;
     const packager = new TerraformAssetPackager(this.runner, this.checkTool);
     this.packageAssets = config.packageAssets ?? packager.build.bind(packager);
+    this.writer = new TerraformProjectWriter();
   }
 
   async *build(project: Project): AsyncGenerator<ProjectEvent, void> {
-    this.compiler.preflight(project);
+    this.validator.validate(project);
     await this.checkTool(
       "terraform",
       "Install Terraform: https://developer.hashicorp.com/terraform/install",
     );
-    const state = new TerraformState(project, "build");
+    const state = new TerraformState(project);
     const unlock = await state.lock();
     try {
+      await state.assertNoLegacyState();
       yield {
         type: "step",
-        message: "Building Terraform configuration for validation (placeholder account and region)",
+        message: "Preparing Terraform application module for validation",
       };
-      yield* this.generate(
-        project,
-        {
-          name: "build",
-          account: "000000000000",
-          region: "us-west-2",
-        },
-        state,
-      );
+      yield* this.generate(project, undefined, state);
       const env = this.environment(state);
       yield* this.execute(["init", "-backend=false", "-input=false", "-no-color"], state, env);
       yield* this.execute(["validate", "-no-color"], state, env);
@@ -104,7 +99,7 @@ export class TerraformBackend implements ProjectBackend {
     project: Project,
     input: DeployBackendInput,
   ): AsyncGenerator<ProjectEvent, DeployResult> {
-    this.compiler.preflight(project);
+    this.validator.validate(project);
     const cdkState = await readDeployedState(this.json, project.rootPath);
     if (Object.values(cdkState.targets).some((target) => stackReferenceOf(target))) {
       throw new ProjectStateError(
@@ -119,31 +114,49 @@ export class TerraformBackend implements ProjectBackend {
     const state = new TerraformState(project, target);
     const unlock = await state.lock();
     try {
+      await state.assertTarget(target);
+      await this.writer.assertCompatible(state.directory);
+      await this.writer.inheritRoot(
+        state.directory,
+        new TerraformState(project, DEFAULT_TARGET_NAME).directory,
+      );
       const tearingDown =
-        declaredResources(project).length === 0 && (await state.hasManagedResources());
+        declaredResources(project).length === 0 && (await state.hasApplicationResources());
       if (tearingDown) {
         const approved = await input.confirmTeardown({
           projectName: project.name,
           targetName: target.name,
           account: target.account,
           region: target.region,
-          resourceDescription: "all Terraform-managed resources for this target",
+          resourceDescription: "all AgentCore application resources for this target",
         });
         if (!approved) throw new ProjectStateError("Terraform teardown was cancelled.");
       }
-      yield { type: "step", message: "Packaging assets and generating Terraform configuration" };
+      yield {
+        type: "step",
+        message: "Packaging assets and preparing Terraform application module",
+      };
       yield* this.generate(project, target, state);
       const credentials = await this.credentialsForTarget(target);
+      await state.bind(target);
       const env = this.environment(state, target, await credentials());
       yield { type: "step", message: "Initializing and validating Terraform" };
       yield* this.execute(["init", "-input=false", "-no-color"], state, env);
+      await state.assertLocalBackend();
       yield* this.execute(["validate", "-no-color"], state, env);
       yield { type: "step", message: "Planning Terraform deployment" };
       // Never reuse a plan from a prior operation, particularly after a failed apply.
       const plan = "deployment.tfplan";
       await rm(join(state.directory, plan), { force: true });
       yield* this.execute(
-        ["plan", "-input=false", "-no-color", "-lock-timeout=60s", `-out=${plan}`],
+        [
+          "plan",
+          "-input=false",
+          "-no-color",
+          "-lock-timeout=60s",
+          "-var-file=deployment.auto.tfvars.json",
+          `-out=${plan}`,
+        ],
         state,
         env,
       );
@@ -172,13 +185,23 @@ export class TerraformBackend implements ProjectBackend {
         this.environment(state, target, await credentials()),
       );
       const outputs = await state.outputs();
+      const namedOutputs: Record<string, string> = {};
+      const flatten = (prefix: string, value: unknown) => {
+        if (typeof value === "string") namedOutputs[prefix] = value;
+        else if (value && typeof value === "object" && !Array.isArray(value)) {
+          for (const [key, entry] of Object.entries(value)) flatten(`${prefix}.${key}`, entry);
+        }
+      };
+      for (const [key, value] of Object.entries(outputs)) {
+        if (key !== "project_resources") flatten(key, value);
+      }
       return {
-        outputs: Object.fromEntries(
-          Object.entries(outputs).filter(
-            (entry): entry is [string, string] => typeof entry[1] === "string",
-          ),
-        ),
-        ...(tearingDown ? { tornDown: true } : {}),
+        outputs: namedOutputs,
+        ...(tearingDown &&
+        (await state.resources()).length === 0 &&
+        !(await state.hasApplicationResources())
+          ? { tornDown: true }
+          : {}),
       };
     } finally {
       // Keep assets, provider lock, plan, and state after failure for retry/cleanup.
@@ -190,7 +213,9 @@ export class TerraformBackend implements ProjectBackend {
     project: Project,
     { target }: ResolveDeployedResourcesBackendInput,
   ): Promise<ResolvedDeployedResource[]> {
-    const resources = await new TerraformState(project, target).resources();
+    const state = new TerraformState(project, target);
+    await state.assertTarget(target);
+    const resources = await state.resources();
     if (resources.length === 0) {
       throw new ProjectStateError(
         `Project '${project.name}' has no Terraform deployment outputs for target '${target.name}'. ` +
@@ -221,7 +246,9 @@ export class TerraformBackend implements ProjectBackend {
     project: Project,
     { target }: ResolveProjectResourcesBackendInput,
   ): Promise<ResolvedProjectResource[]> {
-    const resources = await new TerraformState(project, target).resources();
+    const state = new TerraformState(project, target);
+    await state.assertTarget(target);
+    const resources = await state.resources();
     const declarations = declaredResources(project);
     const resolve = (resource: (typeof declarations)[number]): ResolvedProjectResource => {
       const deployed = resources.find(
@@ -253,16 +280,16 @@ export class TerraformBackend implements ProjectBackend {
     return declarations.filter((resource) => !resource.parentName).map(resolve);
   }
 
-  private async *generate(project: Project, target: AwsDeploymentTarget, state: TerraformState) {
+  private async *generate(
+    project: Project,
+    target: AwsDeploymentTarget | undefined,
+    state: TerraformState,
+  ) {
+    await this.writer.assertCompatible(state.directory);
     const assets = yield* withOutputEvents((emit) =>
       this.packageAssets(project, state.directory, emit),
     );
-    const configuration = this.compiler.compile(project, target, assets);
-    await atomicWrite(
-      join(state.directory, "main.tf.json"),
-      `${JSON.stringify(configuration, null, 2)}\n`,
-      { mode: 0o600 },
-    );
+    await this.writer.write(state.directory, target, assets);
   }
 
   private async *execute(args: string[], state: TerraformState, env: NodeJS.ProcessEnv) {
diff --git a/src/core/project/backends/terraform/assets.ts b/src/core/project/backends/terraform/assets.ts
index 16c441698d..509cbd6b46 100644
--- a/src/core/project/backends/terraform/assets.ts
+++ b/src/core/project/backends/terraform/assets.ts
@@ -18,7 +18,7 @@ import { ProjectStateError } from "../../../../errors";
 import type { Project } from "../../../../handlers/project/types";
 import { atomicWrite, requireTool, type ProcessRunner } from "../../../../io";
 import { resolvePathWithinProject } from "../../../dev/path";
-import type { TerraformAssets } from "./compiler";
+import type { TerraformAssets } from "./types";
 
 const EXCLUDED = new Set([
   ".git",
diff --git a/src/core/project/backends/terraform/compiler.test.ts b/src/core/project/backends/terraform/compiler.test.ts
deleted file mode 100644
index 651897f343..0000000000
--- a/src/core/project/backends/terraform/compiler.test.ts
+++ /dev/null
@@ -1,353 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { Project } from "../../../../handlers/project/types";
-import { ProjectSpecSchema } from "../../../../projectSchemas/project";
-import {
-  TerraformCompiler,
-  declaredResources,
-  type TerraformAssets,
-  type TerraformConfiguration,
-} from "./compiler";
-
-const target = { name: "test", account: "111122223333", region: "us-east-1" } as const;
-const archive = { path: "/tmp/agent.zip", hash: "a".repeat(64) };
-const assets: TerraformAssets = {
-  runtimes: { Agent: archive },
-  gatewayTargets: { "tools/echo": archive },
-};
-function project(): Project {
-  return {
-    name: "Example",
-    rootPath: "/tmp/example",
-    spec: ProjectSpecSchema.parse({
-      name: "Example",
-      version: 2,
-      managedBy: "Terraform",
-      runtimes: [
-        {
-          name: "Agent",
-          build: "CodeZip",
-          runtimeVersion: "PYTHON_3_12",
-          codeLocation: "src/agent",
-          entrypoint: "main.py",
-        },
-      ],
-      memories: [{ name: "Memory", eventExpiryDuration: 7, strategies: [{ type: "SEMANTIC" }] }],
-      policyEngines: [
-        {
-          name: "Rules",
-          policies: [
-            {
-              name: "Allow",
-              statement: "permit(principal, action, resource);",
-              enforcementMode: "LOG_ONLY",
-            },
-          ],
-        },
-      ],
-      agentCoreGateways: [
-        {
-          name: "tools",
-          authorizerType: "AWS_IAM",
-          policyEngineConfiguration: { policyEngineName: "Rules", mode: "LOG_ONLY" },
-          targets: [
-            {
-              name: "echo",
-              targetType: "lambda",
-              toolDefinitions: [
-                {
-                  name: "echo",
-                  description: "Echo input",
-                  inputSchema: {
-                    type: "object",
-                    properties: { message: { type: "string" }, optional: { type: "boolean" } },
-                    required: ["message"],
-                  },
-                },
-              ],
-              compute: {
-                host: "Lambda",
-                pythonVersion: "PYTHON_3_12",
-                implementation: { language: "Python", path: "src/tool", handler: "main.handler" },
-              },
-            },
-          ],
-        },
-      ],
-      onlineEvalConfigs: [
-        { name: "Quality", agent: "Agent", samplingRate: 100, evaluators: ["Builtin.Helpfulness"] },
-      ],
-    }),
-  };
-}
-function resource(config: TerraformConfiguration, type: string): Record<string, any> {
-  return Object.values(config.resource[type]!)[0]!;
-}
-function compile(p = project()): TerraformConfiguration {
-  return new TerraformCompiler().compile(p, target, assets);
-}
-
-describe("Terraform project compilation", () => {
-  test("connects runtime, memory, gateway, policies and evaluation with Terraform references", () => {
-    const config = compile();
-    const runtime = resource(config, "awscc_bedrockagentcore_runtime");
-    const gateway = resource(config, "awscc_bedrockagentcore_gateway");
-    const policy = resource(config, "awscc_bedrockagentcore_policy");
-    const evaluation = resource(config, "awscc_bedrockagentcore_online_evaluation_config");
-    const tool = resource(config, "aws_bedrockagentcore_gateway_target");
-    expect(runtime.environment_variables.MEMORY_MEMORY_ID).toMatch(
-      /^\$\{awscc_bedrockagentcore_memory\./,
-    );
-    expect(runtime.environment_variables.AGENTCORE_GATEWAY_TOOLS_URL).toMatch(
-      /^\$\{awscc_bedrockagentcore_gateway\./,
-    );
-    expect(runtime.environment_variables.OTEL_RESOURCE_ATTRIBUTES).toBeUndefined();
-    expect(gateway.exception_level).toBeUndefined();
-    expect(gateway.policy_engine_configuration.arn).toMatch(
-      /^\$\{awscc_bedrockagentcore_policy_engine\./,
-    );
-    expect(gateway.policy_engine_configuration.mode).toBe("LOG_ONLY");
-    expect(policy.definition).toEqual({
-      policy: { statement: "permit(principal, action, resource);" },
-    });
-    expect(policy.enforcement_mode).toBe("LOG_ONLY");
-    expect(evaluation.data_source_config.cloudwatch_logs.log_group_names[0]).toMatch(
-      /^\$\{aws_cloudwatch_log_group\./,
-    );
-    expect(evaluation.evaluators).toEqual([{ evaluator_id: "Builtin.Helpfulness" }]);
-    expect(tool.gateway_identifier).toMatch(/^\$\{awscc_bedrockagentcore_gateway\./);
-    expect(tool.target_configuration[0].mcp[0].lambda[0].lambda_arn).toMatch(
-      /^\$\{aws_lambda_function\./,
-    );
-    expect(config.output.project_resources!.value).toHaveLength(7);
-    expect(declaredResources(project())).toHaveLength(7);
-    expect(config.provider.aws).toEqual({
-      region: "us-east-1",
-      allowed_account_ids: [target.account],
-    });
-  });
-
-  test("escapes literal Terraform interpolation in customer text without escaping resource references", () => {
-    const p = project();
-    p.spec.runtimes[0]!.description = '${file("secret")} %{if true}';
-    p.spec.runtimes[0]!.envVars = [{ name: "CUSTOM", value: "${var.customer}" }];
-    p.spec.policyEngines[0]!.policies[0]!.statement =
-      'permit(principal, action, resource) when { context.value == "${value}" };';
-    const config = compile(p);
-    const runtime = resource(config, "awscc_bedrockagentcore_runtime");
-    expect(runtime.description).toBe('$${file("secret")} %%{if true}');
-    expect(runtime.environment_variables.CUSTOM).toBe("$${var.customer}");
-    expect(runtime.environment_variables.MEMORY_MEMORY_ID).toStartWith("${awscc_");
-    expect(resource(config, "awscc_bedrockagentcore_policy").definition.policy.statement).toContain(
-      '"$${value}"',
-    );
-  });
-
-  test("reordering resources preserves addresses and changes only output ordering", () => {
-    const p = project();
-    p.spec.memories.push({ ...p.spec.memories[0]!, name: "Second" });
-    const first = compile(p);
-    p.spec.memories.reverse();
-    const second = compile(p);
-    expect(second.resource).toEqual(first.resource);
-    expect(Object.keys(second.resource.awscc_bedrockagentcore_memory!)).toEqual(
-      Object.keys(first.resource.awscc_bedrockagentcore_memory!).reverse(),
-    );
-  });
-
-  test("configuration and archive updates preserve runtime addresses", () => {
-    const p = project();
-    const first = compile(p);
-    p.spec.runtimes[0]!.description = "updated";
-    const updated = new TerraformCompiler().compile(p, target, {
-      ...assets,
-      runtimes: { Agent: { ...archive, hash: "b".repeat(64) } },
-    });
-    expect(Object.keys(first.resource.awscc_bedrockagentcore_runtime!)).toEqual(
-      Object.keys(updated.resource.awscc_bedrockagentcore_runtime!),
-    );
-    expect(Object.keys(first.resource.aws_s3_object!)).toEqual(
-      Object.keys(updated.resource.aws_s3_object!),
-    );
-    expect(JSON.stringify(updated.resource.aws_s3_object)).toContain("b".repeat(64));
-  });
-
-  test("empty project generates no remaining support infrastructure for teardown", () => {
-    const p = project();
-    p.spec = ProjectSpecSchema.parse({ name: p.name, version: 2, managedBy: "Terraform" });
-    const config = compile(p);
-    expect(config.resource).toEqual({});
-    expect(config.output.project_resources!.value).toEqual([]);
-  });
-
-  test("permissions and code storage are scoped to the project's owned resources", () => {
-    const config = compile();
-    const bucket = resource(config, "aws_s3_bucket_public_access_block");
-    expect(bucket.block_public_acls).toBe(true);
-    expect(bucket.block_public_policy).toBe(true);
-    const policies = Object.values(config.resource.aws_iam_role_policy!).map((entry) =>
-      JSON.parse(entry.policy as string),
-    );
-    const memoryGrant = policies
-      .flatMap((entry) => entry.Statement)
-      .find((entry) => entry.Action?.includes("bedrock-agentcore:CreateEvent"));
-    expect(memoryGrant.Resource[0]).toStartWith("${awscc_bedrockagentcore_memory.");
-    const invocation = policies
-      .flatMap((entry) => entry.Statement)
-      .find((entry) => entry.Action?.includes("lambda:InvokeFunction"));
-    expect(invocation.Resource[0]).toStartWith("${aws_lambda_function.");
-    const evaluatorGrant = policies
-      .flatMap((entry) => entry.Statement)
-      .find((entry) => entry.Action?.includes("bedrock-agentcore:GetEvaluator"));
-    expect(evaluatorGrant.Resource).toEqual([
-      "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness",
-    ]);
-    const traceGrant = policies
-      .flatMap((entry) => entry.Statement)
-      .find((entry) => entry.Action?.includes("logs:PutResourcePolicy"));
-    expect(traceGrant.Resource[0]).toContain("/aws/bedrock-agentcore/runtimes/Example_test_Agent-");
-    const trust = Object.values(config.resource.aws_iam_role!)
-      .map((entry) => JSON.parse(entry.assume_role_policy as string))
-      .flatMap((entry) => entry.Statement)
-      .find((entry) => entry.Principal.Service === "bedrock-agentcore.amazonaws.com");
-    expect(trust.Condition.StringEquals["aws:SourceAccount"]).toBe(target.account);
-  });
-
-  test("preserves required tool properties and deep JSON schemas", () => {
-    const p = project();
-    const tool = p.spec.agentCoreGateways[0]!.targets[0]!.toolDefinitions![0]!;
-    tool.inputSchema.properties!.deep = {
-      type: "object",
-      properties: {
-        child: { type: "object", properties: { value: { type: "string" } }, required: ["value"] },
-      },
-      required: ["child"],
-    };
-    const result = resource(compile(p), "aws_bedrockagentcore_gateway_target")
-      .target_configuration[0].mcp[0].lambda[0].tool_schema[0].inline_payload[0].input_schema[0];
-    expect(result.property.find((entry: any) => entry.name === "message").required).toBe(true);
-    expect(result.property.find((entry: any) => entry.name === "optional").required).toBe(false);
-    const deep = result.property.find((entry: any) => entry.name === "deep").property[0];
-    expect(deep.required).toBe(true);
-    expect(JSON.parse(deep.properties_json)).toEqual({
-      properties: { value: { type: "string" } },
-      required: ["value"],
-    });
-  });
-
-  test("fails when a required artifact is absent", () => {
-    expect(() =>
-      new TerraformCompiler().compile(project(), target, { runtimes: {}, gatewayTargets: {} }),
-    ).toThrow("Missing packaged Terraform artifact");
-  });
-
-  test("represents array items under object properties using the provider's intermediate blocks", () => {
-    const p = project();
-    const tool = p.spec.agentCoreGateways[0]!.targets[0]!.toolDefinitions![0]!;
-    tool.inputSchema = {
-      type: "object",
-      properties: {
-        rows: {
-          type: "array",
-          items: {
-            type: "object",
-            properties: { value: { type: "string" } },
-            required: ["value"],
-          },
-        },
-      },
-    };
-    const input = resource(compile(p), "aws_bedrockagentcore_gateway_target")
-      .target_configuration[0].mcp[0].lambda[0].tool_schema[0].inline_payload[0].input_schema[0];
-    expect(input.property[0].items[0].properties_json).toBeUndefined();
-    expect(input.property[0].items[0].property).toEqual([
-      { name: "value", type: "string", required: true, description: undefined },
-    ]);
-  });
-
-  test.each([
-    [
-      "migratedFrom",
-      (p: Project) => {
-        p.spec.migratedFrom = "v1";
-      },
-    ],
-    [
-      "runtimes[Agent].build",
-      (p: Project) => {
-        p.spec.runtimes[0]!.build = "Container";
-      },
-    ],
-    [
-      "runtimes[Agent].executionRoleArn",
-      (p: Project) => {
-        p.spec.runtimes[0]!.executionRoleArn = "arn:aws:iam::111122223333:role/existing";
-      },
-    ],
-    [
-      "runtimes[Agent].networkMode",
-      (p: Project) => {
-        p.spec.runtimes[0]!.networkMode = "VPC";
-      },
-    ],
-    [
-      "runtimes[Agent].runtimeVersion",
-      (p: Project) => {
-        p.spec.runtimes[0]!.runtimeVersion = "NODE_22";
-      },
-    ],
-    [
-      "runtimes[Agent].entrypoint",
-      (p: Project) => {
-        p.spec.runtimes[0]!.entrypoint = "main.py:app";
-      },
-    ],
-    [
-      "agentCoreGateways[tools].authorizerType",
-      (p: Project) => {
-        p.spec.agentCoreGateways[0]!.authorizerType = "NONE";
-      },
-    ],
-    [
-      "onlineEvalConfigs[Quality].evaluators",
-      (p: Project) => {
-        p.spec.onlineEvalConfigs[0]!.evaluators = ["Custom"];
-      },
-    ],
-    [
-      "onlineEvalConfigs[Quality].agent",
-      (p: Project) => {
-        p.spec.runtimes[0]!.instrumentation = { enableOtel: false };
-      },
-    ],
-    [
-      "envVars.MEMORY_MEMORY_ID",
-      (p: Project) => {
-        p.spec.runtimes[0]!.envVars = [{ name: "MEMORY_MEMORY_ID", value: "wrong" }];
-      },
-    ],
-    [
-      "memories[memory].name",
-      (p: Project) => {
-        p.spec.memories.push({ ...p.spec.memories[0]!, name: "memory" });
-      },
-    ],
-    [
-      "envVars.OTEL_SERVICE_NAME",
-      (p: Project) => {
-        p.spec.runtimes[0]!.envVars = [{ name: "OTEL_SERVICE_NAME", value: "other" }];
-      },
-    ],
-    [
-      "inputSchema.required",
-      (p: Project) => {
-        p.spec.agentCoreGateways[0]!.targets[0]!.toolDefinitions![0]!.inputSchema.required = [
-          "undeclared",
-        ];
-      },
-    ],
-  ] as const)("rejects unsupported %s before packaging or deployment", (path, change) => {
-    const p = project();
-    change(p);
-    expect(() => new TerraformCompiler().preflight(p)).toThrow(path);
-  });
-});
diff --git a/src/core/project/backends/terraform/compiler.ts b/src/core/project/backends/terraform/compiler.ts
deleted file mode 100644
index 3c5a4c7a26..0000000000
--- a/src/core/project/backends/terraform/compiler.ts
+++ /dev/null
@@ -1,969 +0,0 @@
-import { createHash } from "node:crypto";
-import { InputValidationError } from "../../../../errors";
-import type { DeployableResource, Project } from "../../../../handlers/project/types";
-import type { AwsDeploymentTarget } from "../../../../projectSchemas/aws-targets";
-import type { AgentCoreGateway } from "../../../../projectSchemas/gateway";
-import type { SchemaDefinition } from "../../../../projectSchemas/mcp-defs";
-import {
-  DEFAULT_STRATEGY_NAMESPACE_TEMPLATES,
-  type Memory,
-} from "../../../../projectSchemas/memory";
-import type { OnlineEvalConfig } from "../../../../projectSchemas/online-eval-config";
-import type { PolicyEngine } from "../../../../projectSchemas/policy";
-import type { ProjectRuntime } from "../../../../projectSchemas/runtime";
-
-type Attributes = Record<string, unknown>;
-export type TerraformArtifact = { path: string; hash: string };
-export type TerraformAssets = {
-  runtimes: Record<string, TerraformArtifact>;
-  /** Keys are gateway-name/target-name. */
-  gatewayTargets: Record<string, TerraformArtifact>;
-};
-export type TerraformResourceDescriptor = {
-  resourceType: DeployableResource;
-  name: string;
-  parentName?: string;
-};
-export type TerraformConfiguration = {
-  terraform: Attributes;
-  provider: Attributes;
-  resource: Record<string, Record<string, Attributes>>;
-  output: Record<string, { value: unknown }>;
-};
-
-export function declaredResources(project: Project): TerraformResourceDescriptor[] {
-  return [
-    ...project.spec.runtimes.map(({ name }) => ({ resourceType: "runtime" as const, name })),
-    ...project.spec.memories.map(({ name }) => ({ resourceType: "memory" as const, name })),
-    ...project.spec.policyEngines.flatMap(({ name, policies }) => [
-      { resourceType: "policy-engine" as const, name },
-      ...policies.map((policy) => ({
-        resourceType: "policy" as const,
-        name: policy.name,
-        parentName: name,
-      })),
-    ]),
-    ...project.spec.agentCoreGateways.flatMap(({ name, targets }) => [
-      { resourceType: "gateway" as const, name },
-      ...targets.map((target) => ({
-        resourceType: "gateway-target" as const,
-        name: target.name,
-        parentName: name,
-      })),
-    ]),
-    ...project.spec.onlineEvalConfigs.map(({ name }) => ({
-      resourceType: "online-eval" as const,
-      name,
-    })),
-  ];
-}
-
-const digest = (value: string) => createHash("sha256").update(value).digest("hex").slice(0, 10);
-const key = (name: string) => `r_${name.replace(/[^a-zA-Z0-9_]/g, "_")}_${digest(name)}`;
-const ref = (address: string, attribute: string) => `\${${address}.${attribute}}`;
-/** All customer strings are Terraform string literals, never expressions. */
-const literal = (value: string) => value.replace(/\$\{/g, () => "$${").replace(/%\{/g, () => "%%{");
-const optional = (value?: string) => (value === undefined ? undefined : literal(value));
-const tagMap = (project: Project, tags?: Record<string, string>) =>
-  Object.fromEntries(
-    Object.entries({ ...project.spec.tags, ...tags }).map(([name, value]) => [
-      name,
-      literal(value),
-    ]),
-  );
-const tagList = (tags: Record<string, string>) =>
-  Object.entries(tags).map(([key, value]) => ({ key, value }));
-const statement = (actions: string[], resources: string[]) => ({
-  Effect: "Allow",
-  Action: actions,
-  Resource: resources,
-});
-const policyDocument = (statements: Attributes[]) =>
-  JSON.stringify({ Version: "2012-10-17", Statement: statements });
-const hasValue = (value: unknown) =>
-  value !== undefined && (!Array.isArray(value) || value.length > 0);
-
-function reject(path: string, detail = "is not supported by the Terraform PoC"): never {
-  throw new InputValidationError(`agentcore.json ${path}: ${detail}.`);
-}
-function fields(value: object, allowed: string[], path: string): void {
-  for (const [name, entry] of Object.entries(value)) {
-    if (hasValue(entry) && !allowed.includes(name)) reject(`${path}.${name}`);
-  }
-}
-
-/** Compiles the deliberately bounded Terraform PoC without performing I/O or deploying resources. */
-export class TerraformCompiler {
-  private resources: TerraformConfiguration["resource"] = {};
-  private outputs: TerraformConfiguration["output"] = {};
-  private deployed: Attributes[] = [];
-  private project!: Project;
-  private target!: AwsDeploymentTarget;
-  private partition = "aws";
-
-  preflight(project: Project): void {
-    fields(
-      project.spec,
-      [
-        "name",
-        "version",
-        "managedBy",
-        "tags",
-        "runtimes",
-        "memories",
-        "policyEngines",
-        "agentCoreGateways",
-        "onlineEvalConfigs",
-      ],
-      "project",
-    );
-    for (const runtime of project.spec.runtimes) {
-      const path = `runtimes[${runtime.name}]`;
-      fields(
-        runtime,
-        [
-          "name",
-          "description",
-          "modelProvider",
-          "modelId",
-          "build",
-          "codeLocation",
-          "entrypoint",
-          "runtimeVersion",
-          "envVars",
-          "instrumentation",
-          "networkMode",
-          "authorizerType",
-          "protocol",
-          "requestHeaderAllowlist",
-          "tags",
-          "lifecycleConfiguration",
-        ],
-        path,
-      );
-      if (runtime.build !== "CodeZip") reject(`${path}.build`, "must be CodeZip for this PoC");
-      if (!runtime.runtimeVersion?.startsWith("PYTHON_3_"))
-        reject(`${path}.runtimeVersion`, "must select a Python managed runtime");
-      if (runtime.networkMode && runtime.networkMode !== "PUBLIC")
-        reject(`${path}.networkMode`, "must be PUBLIC for this PoC");
-      if (runtime.authorizerType && runtime.authorizerType !== "AWS_IAM")
-        reject(`${path}.authorizerType`, "must be AWS_IAM for this PoC");
-      if (!runtime.entrypoint.endsWith(".py"))
-        reject(`${path}.entrypoint`, "must be a Python script without a handler suffix");
-      const environment = new Set<string>();
-      for (const env of runtime.envVars ?? []) {
-        if (environment.has(env.name))
-          reject(`${path}.envVars`, `contains duplicate variable ${env.name}`);
-        environment.add(env.name);
-        const generated =
-          project.spec.memories.some((memory) =>
-            [
-              `MEMORY_${memory.name.toUpperCase()}_ID`,
-              `MEMORY_${memory.name.toUpperCase()}_ARN`,
-            ].includes(env.name),
-          ) ||
-          project.spec.agentCoreGateways.some((gateway) =>
-            ["URL", "ARN", "ID"]
-              .map((suffix) => `${this.gatewayPrefix(gateway.name)}_${suffix}`)
-              .includes(env.name),
-          );
-        if (generated)
-          reject(
-            `${path}.envVars.${env.name}`,
-            "conflicts with a project resource discovery variable",
-          );
-      }
-    }
-    const memoryVariables = new Set<string>();
-    for (const memory of project.spec.memories) {
-      const environmentName = memory.name.toUpperCase();
-      if (memoryVariables.has(environmentName))
-        reject(
-          `memories[${memory.name}].name`,
-          "collides with another memory's discovery variables",
-        );
-      memoryVariables.add(environmentName);
-      fields(
-        memory,
-        ["name", "description", "eventExpiryDuration", "strategies", "indexedKeys", "tags"],
-        `memories[${memory.name}]`,
-      );
-    }
-    for (const engine of project.spec.policyEngines) {
-      fields(
-        engine,
-        ["name", "description", "encryptionKeyArn", "tags", "policies"],
-        `policyEngines[${engine.name}]`,
-      );
-      // sourceFile and authorizationPhase are CLI provenance/inference metadata. Like the L3,
-      // the deployment uses the actual statement and the service determines authorization phase.
-    }
-    const gatewayVariables = new Set<string>();
-    for (const gateway of project.spec.agentCoreGateways) {
-      const path = `agentCoreGateways[${gateway.name}]`;
-      fields(
-        gateway,
-        [
-          "name",
-          "resourceName",
-          "protocolType",
-          "description",
-          "targets",
-          "authorizerType",
-          "enableSemanticSearch",
-          "exceptionLevel",
-          "policyEngineConfiguration",
-          "tags",
-        ],
-        path,
-      );
-      if (gateway.authorizerType !== "AWS_IAM")
-        reject(`${path}.authorizerType`, "must be AWS_IAM for this PoC");
-      if (gateway.protocolType && gateway.protocolType !== "MCP")
-        reject(`${path}.protocolType`, "must be MCP for this PoC");
-      if (gatewayVariables.has(this.gatewayPrefix(gateway.name)))
-        reject(`${path}.name`, "collides with another gateway's discovery variables");
-      gatewayVariables.add(this.gatewayPrefix(gateway.name));
-      const names = new Set<string>();
-      for (const target of gateway.targets) {
-        const targetPath = `${path}.targets[${target.name}]`;
-        fields(
-          target,
-          ["name", "targetType", "toolDefinitions", "compute", "outboundAuth"],
-          targetPath,
-        );
-        if (names.has(target.name)) reject(`${targetPath}.name`, "duplicates another target");
-        names.add(target.name);
-        if (target.targetType !== "lambda")
-          reject(`${targetPath}.targetType`, "must be lambda for this PoC");
-        if (
-          target.compute?.host !== "Lambda" ||
-          target.compute.implementation.language !== "Python"
-        )
-          reject(`${targetPath}.compute`, "must be a Python Lambda for this PoC");
-        fields(
-          target.compute,
-          ["host", "implementation", "pythonVersion", "timeout", "memorySize", "iamPolicy"],
-          `${targetPath}.compute`,
-        );
-        fields(
-          target.compute.implementation,
-          ["language", "path", "handler"],
-          `${targetPath}.compute.implementation`,
-        );
-        if (target.compute.iamPolicy) {
-          fields(
-            target.compute.iamPolicy,
-            ["Version", "Statement"],
-            `${targetPath}.compute.iamPolicy`,
-          );
-          if (target.compute.iamPolicy.Version !== "2012-10-17")
-            reject(`${targetPath}.compute.iamPolicy.Version`, "must be 2012-10-17");
-        }
-        if (target.compute.nodeVersion) reject(`${targetPath}.compute.nodeVersion`);
-        if (target.outboundAuth && Object.keys(target.outboundAuth).some((name) => name !== "type"))
-          reject(`${targetPath}.outboundAuth`);
-        if (target.outboundAuth && target.outboundAuth.type !== "NONE")
-          reject(`${targetPath}.outboundAuth.type`);
-        if (
-          !/^[a-zA-Z_][a-zA-Z0-9_.]*\.[a-zA-Z_][a-zA-Z0-9_]*$/.test(
-            target.compute.implementation.handler,
-          )
-        )
-          reject(
-            `${targetPath}.compute.implementation.handler`,
-            "must use the Lambda module.function format",
-          );
-        for (const tool of target.toolDefinitions ?? []) {
-          this.validateToolSchema(tool.inputSchema, `${targetPath}.${tool.name}.inputSchema`);
-          if (tool.outputSchema)
-            this.validateToolSchema(tool.outputSchema, `${targetPath}.${tool.name}.outputSchema`);
-        }
-      }
-    }
-    for (const config of project.spec.onlineEvalConfigs) {
-      const path = `onlineEvalConfigs[${config.name}]`;
-      if (!config.agent || config.logGroupNames || config.serviceNames)
-        reject(path, "must reference a project runtime for this PoC");
-      if (config.endpoint && config.endpoint !== "DEFAULT")
-        reject(`${path}.endpoint`, "must use DEFAULT for this PoC");
-      if (config.evaluators.some((name) => !name.startsWith("Builtin.")))
-        reject(`${path}.evaluators`, "must contain built-in evaluators for this PoC");
-      const runtime = project.spec.runtimes.find((entry) => entry.name === config.agent);
-      if (!runtime) reject(`${path}.agent`, "references an unknown runtime");
-      if (runtime.instrumentation?.enableOtel === false)
-        reject(
-          `${path}.agent`,
-          "requires runtime OpenTelemetry instrumentation for online evaluation",
-        );
-      for (const env of runtime.envVars ?? []) {
-        if (env.name.startsWith("OTEL_") || env.name === "UNIFIED_TRACES_DESTINATION_ENABLED")
-          reject(
-            `runtimes[${runtime.name}].envVars.${env.name}`,
-            "cannot override service-managed telemetry while a project online evaluation uses this runtime",
-          );
-      }
-    }
-  }
-
-  compile(
-    project: Project,
-    target: AwsDeploymentTarget,
-    assets: TerraformAssets,
-  ): TerraformConfiguration {
-    this.preflight(project);
-    this.resources = {};
-    this.outputs = {};
-    this.deployed = [];
-    this.project = project;
-    this.target = target;
-    this.partition = target.region.startsWith("cn-")
-      ? "aws-cn"
-      : target.region.startsWith("us-gov-")
-        ? "aws-us-gov"
-        : "aws";
-    if (
-      project.spec.runtimes.length ||
-      project.spec.agentCoreGateways.some((gateway) => gateway.targets.length)
-    )
-      this.artifactBucket();
-    for (const memory of project.spec.memories) this.memory(memory);
-    for (const engine of project.spec.policyEngines) this.policyEngine(engine);
-    for (const gateway of project.spec.agentCoreGateways) this.gateway(gateway, assets);
-    for (const runtime of project.spec.runtimes) this.runtime(runtime, assets);
-    for (const config of project.spec.onlineEvalConfigs) this.onlineEvaluation(config);
-    this.outputs.project_resources = { value: this.deployed };
-    return {
-      terraform: {
-        required_version: ">= 1.12.0, < 2.0.0",
-        required_providers: {
-          awscc: { source: "hashicorp/awscc", version: "= 1.106.0" },
-          aws: { source: "hashicorp/aws", version: "= 6.69.0" },
-        },
-      },
-      provider: {
-        awscc: { region: target.region },
-        aws: { region: target.region, allowed_account_ids: [target.account] },
-      },
-      resource: this.resources,
-      output: this.outputs,
-    };
-  }
-
-  private add(type: string, name: string, attributes: Attributes): string {
-    const label = key(name);
-    (this.resources[type] ??= {})[label] = attributes;
-    return `${type}.${label}`;
-  }
-  private address(type: string, name: string): string {
-    return `${type}.${key(name)}`;
-  }
-  private physical(name: string, limit = 48, separator = "_"): string {
-    const full = `${this.project.name}${separator}${this.target.name}${separator}${name}`.replace(
-      separator === "_" ? /[^a-zA-Z0-9_]/g : /[^a-zA-Z0-9-]/g,
-      separator,
-    );
-    return full.length <= limit ? full : `${full.slice(0, limit - 11)}${separator}${digest(full)}`;
-  }
-  private arn(service: string, resource: string): string {
-    return `arn:${this.partition}:${service}:${this.target.region}:${this.target.account}:${resource}`;
-  }
-  private gatewayPrefix(name: string): string {
-    return `AGENTCORE_GATEWAY_${name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
-  }
-  private publish(
-    resourceType: DeployableResource,
-    name: string,
-    id: string,
-    arn?: string,
-    parentName?: string,
-  ): void {
-    this.deployed.push({
-      resourceType,
-      name,
-      id,
-      ...(arn ? { arn } : {}),
-      ...(parentName ? { parentName } : {}),
-    });
-    this.outputs[`${key(`${resourceType}/${parentName ?? ""}/${name}`)}_id`] = { value: id };
-    if (arn)
-      this.outputs[`${key(`${resourceType}/${parentName ?? ""}/${name}`)}_arn`] = { value: arn };
-  }
-  private role(
-    name: string,
-    service: string,
-    statements: Attributes[],
-    sourceArn?: string | string[],
-  ): { arn: string; dependency: string } {
-    const role = this.add("aws_iam_role", name, {
-      name: this.physical(name, 64, "-"),
-      assume_role_policy: policyDocument([
-        {
-          Effect: "Allow",
-          Principal: { Service: service },
-          Action: "sts:AssumeRole",
-          ...(sourceArn
-            ? {
-                Condition: {
-                  StringEquals: {
-                    "aws:SourceAccount": this.target.account,
-                    "aws:ResourceAccount": this.target.account,
-                  },
-                  ArnLike: { "aws:SourceArn": sourceArn },
-                },
-              }
-            : {}),
-        },
-      ]),
-      tags: tagMap(this.project),
-    });
-    const dependency = statements.length
-      ? this.add("aws_iam_role_policy", name, {
-          name: "agentcore-poc",
-          role: ref(role, "id"),
-          policy: policyDocument(statements),
-        })
-      : role;
-    return { arn: ref(role, "arn"), dependency };
-  }
-  private artifactBucket(): void {
-    const bucket = this.add("aws_s3_bucket", "artifacts", {
-      bucket: `agentcore-tf-${digest(`${this.project.name}/${this.target.name}/${this.target.account}/${this.target.region}`)}-${this.target.account}`,
-      force_destroy: true,
-      tags: tagMap(this.project),
-    });
-    this.add("aws_s3_bucket_public_access_block", "artifacts", {
-      bucket: ref(bucket, "id"),
-      block_public_acls: true,
-      block_public_policy: true,
-      ignore_public_acls: true,
-      restrict_public_buckets: true,
-    });
-    this.add("aws_s3_bucket_server_side_encryption_configuration", "artifacts", {
-      bucket: ref(bucket, "id"),
-      rule: [{ apply_server_side_encryption_by_default: [{ sse_algorithm: "AES256" }] }],
-    });
-  }
-  private asset(name: string, artifact?: TerraformArtifact): string {
-    if (!artifact)
-      throw new InputValidationError(
-        `Missing packaged Terraform artifact for ${name}. Run agentcore build first.`,
-      );
-    return this.add("aws_s3_object", name, {
-      bucket: ref(this.address("aws_s3_bucket", "artifacts"), "id"),
-      key: `${name}/${artifact.hash}.zip`,
-      source: literal(artifact.path),
-      source_hash: artifact.hash,
-      content_type: "application/zip",
-      server_side_encryption: "AES256",
-    });
-  }
-  private memory(memory: Memory): void {
-    const strategyKeys = {
-      SEMANTIC: "semantic_memory_strategy",
-      SUMMARIZATION: "summary_memory_strategy",
-      USER_PREFERENCE: "user_preference_memory_strategy",
-      EPISODIC: "episodic_memory_strategy",
-    };
-    // Built-in strategies do not require model permissions in the execution role.
-    // Keep the service role explicit, like the L3, so its lifecycle is owned here.
-    const role = this.role(
-      `memory/${memory.name}`,
-      "bedrock-agentcore.amazonaws.com",
-      [],
-      this.arn("bedrock-agentcore", `memory/${this.physical(memory.name)}*`),
-    );
-    const resource = this.add("awscc_bedrockagentcore_memory", memory.name, {
-      name: this.physical(memory.name),
-      description: optional(memory.description),
-      event_expiry_duration: memory.eventExpiryDuration,
-      memory_execution_role_arn: role.arn,
-      indexed_keys: memory.indexedKeys?.map(({ key, type }) => ({ key: literal(key), type })),
-      memory_strategies: memory.strategies.map((strategy) => ({
-        [strategyKeys[strategy.type]]: {
-          name:
-            strategy.name ??
-            `${memory.name}_${strategy.type.charAt(0)}${strategy.type.slice(1).toLowerCase().replace(/_/g, "")}`,
-          description: optional(strategy.description),
-          namespace_templates: (
-            strategy.namespaceTemplates ??
-            strategy.namespaces ??
-            DEFAULT_STRATEGY_NAMESPACE_TEMPLATES[strategy.type]
-          )?.map(literal),
-          ...(strategy.type === "EPISODIC"
-            ? {
-                reflection_configuration: {
-                  namespace_templates: (
-                    strategy.reflectionNamespaceTemplates ?? strategy.reflectionNamespaces
-                  )?.map(literal),
-                },
-              }
-            : {}),
-        },
-      })),
-      tags: tagMap(this.project, memory.tags),
-    });
-    this.publish("memory", memory.name, ref(resource, "memory_id"), ref(resource, "memory_arn"));
-  }
-  private policyEngine(engine: PolicyEngine): void {
-    const resource = this.add("awscc_bedrockagentcore_policy_engine", engine.name, {
-      name: this.physical(engine.name),
-      description: optional(engine.description),
-      encryption_key_arn: optional(engine.encryptionKeyArn),
-      tags: tagList(tagMap(this.project, engine.tags)),
-    });
-    this.publish(
-      "policy-engine",
-      engine.name,
-      ref(resource, "policy_engine_id"),
-      ref(resource, "policy_engine_arn"),
-    );
-    for (const policy of engine.policies) {
-      const policyResource = this.add(
-        "awscc_bedrockagentcore_policy",
-        `${engine.name}/${policy.name}`,
-        {
-          name: policy.name,
-          policy_engine_id: ref(resource, "policy_engine_id"),
-          definition: { policy: { statement: literal(policy.statement) } },
-          description: optional(policy.description),
-          enforcement_mode: policy.enforcementMode,
-          validation_mode: policy.validationMode,
-        },
-      );
-      this.publish(
-        "policy",
-        policy.name,
-        ref(policyResource, "policy_id"),
-        ref(policyResource, "policy_arn"),
-        engine.name,
-      );
-    }
-  }
-  private gateway(gateway: AgentCoreGateway, assets: TerraformAssets): void {
-    const lambdaArns: string[] = [];
-    const lambdaDependencies: string[] = [];
-    for (const target of gateway.targets) {
-      if (target.compute?.host !== "Lambda") continue; // preflight guarantees Lambda
-      const name = `${gateway.name}/${target.name}`;
-      const compute = target.compute;
-      const lambdaName = this.physical(name, 64, "-");
-      const logs = this.add("aws_cloudwatch_log_group", `lambda/${name}`, {
-        name: `/aws/lambda/${lambdaName}`,
-        retention_in_days: 7,
-        tags: tagMap(this.project),
-      });
-      const role = this.role(`lambda/${name}`, "lambda.amazonaws.com", [
-        statement(["logs:CreateLogStream", "logs:PutLogEvents"], [`${ref(logs, "arn")}:*`]),
-        ...(compute.iamPolicy
-          ? compute.iamPolicy.Statement.map(
-              (entry) => JSON.parse(literal(JSON.stringify(entry))) as Attributes,
-            )
-          : []),
-      ]);
-      const asset = this.asset(`lambda/${name}`, assets.gatewayTargets[name]);
-      const lambda = this.add("aws_lambda_function", name, {
-        function_name: lambdaName,
-        role: role.arn,
-        runtime: `python${compute.pythonVersion!.replace("PYTHON_", "").replace("_", ".")}`,
-        handler: compute.implementation.handler,
-        architectures: ["arm64"],
-        timeout: compute.timeout ?? 30,
-        memory_size: compute.memorySize ?? 512,
-        s3_bucket: ref(asset, "bucket"),
-        s3_key: ref(asset, "key"),
-        source_code_hash: Buffer.from(assets.gatewayTargets[name]!.hash, "hex").toString("base64"),
-        tags: tagMap(this.project),
-        depends_on: [role.dependency],
-      });
-      lambdaArns.push(ref(lambda, "arn"));
-      lambdaDependencies.push(lambda);
-    }
-    const policies: Attributes[] = lambdaArns.length
-      ? [statement(["lambda:InvokeFunction"], lambdaArns)]
-      : [];
-    const engine = gateway.policyEngineConfiguration
-      ? this.address(
-          "awscc_bedrockagentcore_policy_engine",
-          gateway.policyEngineConfiguration.policyEngineName,
-        )
-      : undefined;
-    if (engine)
-      policies.push(
-        statement(
-          [
-            "bedrock-agentcore:GetPolicyEngine",
-            "bedrock-agentcore:CheckAuthorizePermissions",
-            "bedrock-agentcore:AuthorizeAction",
-            "bedrock-agentcore:PartiallyAuthorizeActions",
-          ],
-          [ref(engine, "policy_engine_arn"), this.arn("bedrock-agentcore", "gateway/*")],
-        ),
-      );
-    // An empty gateway still needs a role but no arbitrary resource grants.
-    const role = this.role(
-      `gateway/${gateway.name}`,
-      "bedrock-agentcore.amazonaws.com",
-      policies,
-      this.arn("bedrock-agentcore", "gateway/*"),
-    );
-    const resource = this.add("awscc_bedrockagentcore_gateway", gateway.name, {
-      name: gateway.resourceName ?? this.physical(gateway.name, 100, "-"),
-      authorizer_type: "AWS_IAM",
-      role_arn: role.arn,
-      protocol_type: "MCP",
-      description: optional(gateway.description),
-      exception_level: gateway.exceptionLevel === "DEBUG" ? "DEBUG" : undefined,
-      protocol_configuration: {
-        mcp: {
-          ...(gateway.enableSemanticSearch ? { search_type: "SEMANTIC" } : {}),
-          supported_versions: ["2025-03-26"],
-        },
-      },
-      policy_engine_configuration: engine
-        ? { arn: ref(engine, "policy_engine_arn"), mode: gateway.policyEngineConfiguration!.mode }
-        : undefined,
-      tags: tagMap(this.project, gateway.tags),
-      depends_on: [role.dependency],
-    });
-    this.publish(
-      "gateway",
-      gateway.name,
-      ref(resource, "gateway_identifier"),
-      ref(resource, "gateway_arn"),
-    );
-    this.outputs[`${key(`gateway/${gateway.name}`)}_url`] = { value: ref(resource, "gateway_url") };
-    for (const target of gateway.targets) {
-      const name = `${gateway.name}/${target.name}`;
-      const lambda = this.address("aws_lambda_function", name);
-      // AWSCC 1.106.0 does not ship GatewayTarget. The native provider owns this
-      // resource's full CRUD lifecycle while referring to the AWSCC gateway.
-      const resourceTarget = this.add("aws_bedrockagentcore_gateway_target", name, {
-        name: literal(target.name),
-        gateway_identifier: ref(resource, "gateway_identifier"),
-        credential_provider_configuration: [{ gateway_iam_role: [{}] }],
-        target_configuration: [
-          {
-            mcp: [
-              {
-                lambda: [
-                  {
-                    lambda_arn: ref(lambda, "arn"),
-                    tool_schema: [
-                      {
-                        inline_payload: target.toolDefinitions!.map((tool) => ({
-                          name: literal(tool.name),
-                          description: literal(tool.description),
-                          input_schema: [this.toolSchema(tool.inputSchema)],
-                          ...(tool.outputSchema
-                            ? { output_schema: [this.toolSchema(tool.outputSchema)] }
-                            : {}),
-                        })),
-                      },
-                    ],
-                  },
-                ],
-              },
-            ],
-          },
-        ],
-        depends_on: [role.dependency, ...lambdaDependencies],
-      });
-      this.publish(
-        "gateway-target",
-        target.name,
-        ref(resourceTarget, "target_id"),
-        undefined,
-        gateway.name,
-      );
-    }
-  }
-  private validateToolSchema(schema: SchemaDefinition, path: string): void {
-    if (schema.items && schema.type !== "array")
-      reject(`${path}.items`, "requires an array schema");
-    if ((schema.properties || schema.required?.length) && schema.type !== "object")
-      reject(path, "properties and required are supported only on object schemas");
-    for (const required of schema.required ?? []) {
-      if (!Object.hasOwn(schema.properties ?? {}, required))
-        reject(
-          `${path}.required`,
-          `references property ${required} without a declaration; the native provider cannot preserve it`,
-        );
-    }
-    for (const [name, property] of Object.entries(schema.properties ?? {}))
-      this.validateToolSchema(property, `${path}.properties.${name}`);
-    if (schema.items) this.validateToolSchema(schema.items, `${path}.items`);
-  }
-
-  private toolSchema(
-    schema: SchemaDefinition,
-    kind: "root" | "property" | "items" | "leaf" = "root",
-  ): Attributes {
-    const result: Attributes = { type: schema.type, description: optional(schema.description) };
-    if (kind === "leaf") {
-      if (schema.items) result.items_json = literal(JSON.stringify(schema.items));
-      if (schema.properties)
-        result.properties_json = literal(
-          JSON.stringify({ properties: schema.properties, required: schema.required ?? [] }),
-        );
-    } else {
-      if (schema.items)
-        result.items = [this.toolSchema(schema.items, kind === "items" ? "leaf" : "items")];
-      if (schema.properties)
-        result.property = Object.entries(schema.properties).map(([name, value]) => ({
-          name: literal(name),
-          required: schema.required?.includes(name) ?? false,
-          ...this.toolSchema(value, kind === "root" ? "property" : "leaf"),
-        }));
-    }
-    return result;
-  }
-  private runtime(runtime: ProjectRuntime, assets: TerraformAssets): void {
-    const physicalName = this.physical(runtime.name);
-    const artifact = this.asset(`runtime/${runtime.name}`, assets.runtimes[runtime.name]);
-    const memoryArns = this.project.spec.memories
-      .map((memory) =>
-        ref(this.address("awscc_bedrockagentcore_memory", memory.name), "memory_arn"),
-      )
-      .sort();
-    const gatewayArns = this.project.spec.agentCoreGateways
-      .map((gateway) =>
-        ref(this.address("awscc_bedrockagentcore_gateway", gateway.name), "gateway_arn"),
-      )
-      .sort();
-    const statements: Attributes[] = [
-      statement(["s3:GetObject"], [`${ref(this.address("aws_s3_bucket", "artifacts"), "arn")}/*`]),
-      statement(
-        [
-          "logs:CreateLogGroup",
-          "logs:CreateLogStream",
-          "logs:PutLogEvents",
-          "logs:DescribeLogStreams",
-          "logs:PutResourcePolicy",
-        ],
-        [this.arn("logs", `log-group:/aws/bedrock-agentcore/runtimes/${physicalName}-*`)],
-      ),
-      statement(
-        [
-          "logs:DescribeLogGroups",
-          "xray:PutTraceSegments",
-          "xray:PutTelemetryRecords",
-          "xray:GetSamplingRules",
-          "xray:GetSamplingTargets",
-          "cloudwatch:PutMetricData",
-        ],
-        ["*"],
-      ),
-      statement(
-        ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
-        [
-          `arn:${this.partition}:bedrock:*::foundation-model/*`,
-          `arn:${this.partition}:bedrock:*:${this.target.account}:inference-profile/*`,
-          `arn:${this.partition}:bedrock:*:${this.target.account}:application-inference-profile/*`,
-        ],
-      ),
-      statement(
-        [
-          "bedrock-agentcore:GetWorkloadAccessToken",
-          "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
-          "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
-        ],
-        [
-          this.arn("bedrock-agentcore", "workload-identity-directory/default"),
-          this.arn("bedrock-agentcore", "workload-identity-directory/default/workload-identity/*"),
-        ],
-      ),
-    ];
-    if (memoryArns.length)
-      statements.push(
-        statement(
-          [
-            "bedrock-agentcore:CreateEvent",
-            "bedrock-agentcore:DeleteEvent",
-            "bedrock-agentcore:GetEvent",
-            "bedrock-agentcore:GetMemory",
-            "bedrock-agentcore:GetMemoryRecord",
-            "bedrock-agentcore:ListActors",
-            "bedrock-agentcore:ListEvents",
-            "bedrock-agentcore:ListSessions",
-            "bedrock-agentcore:ListMemoryRecords",
-            "bedrock-agentcore:RetrieveMemoryRecords",
-            "bedrock-agentcore:DeleteMemoryRecord",
-          ],
-          memoryArns,
-        ),
-      );
-    if (gatewayArns.length)
-      statements.push(statement(["bedrock-agentcore:InvokeGateway"], gatewayArns));
-    const role = this.role(
-      `runtime/${runtime.name}`,
-      "bedrock-agentcore.amazonaws.com",
-      statements,
-      this.arn("bedrock-agentcore", "runtime/*"),
-    );
-    const environment: Record<string, string> = Object.fromEntries(
-      (runtime.envVars ?? []).map(({ name, value }) => [name, literal(value)]),
-    );
-    for (const memory of this.project.spec.memories) {
-      const address = this.address("awscc_bedrockagentcore_memory", memory.name);
-      environment[`MEMORY_${memory.name.toUpperCase()}_ID`] = ref(address, "memory_id");
-      environment[`MEMORY_${memory.name.toUpperCase()}_ARN`] = ref(address, "memory_arn");
-    }
-    for (const gateway of this.project.spec.agentCoreGateways) {
-      const address = this.address("awscc_bedrockagentcore_gateway", gateway.name);
-      for (const [suffix, attribute] of Object.entries({
-        URL: "gateway_url",
-        ARN: "gateway_arn",
-        ID: "gateway_identifier",
-      }))
-        environment[`${this.gatewayPrefix(gateway.name)}_${suffix}`] = ref(address, attribute);
-    }
-    const instrumented = runtime.instrumentation?.enableOtel ?? true;
-    // Hosted runtimes inject their OTEL exporter, resource attributes and unified
-    // trace destination. Overriding those here would lose the runtime identifier.
-    const resource = this.add("awscc_bedrockagentcore_runtime", runtime.name, {
-      agent_runtime_name: physicalName,
-      description: optional(runtime.description),
-      role_arn: role.arn,
-      agent_runtime_artifact: {
-        code_configuration: {
-          code: { s3: { bucket: ref(artifact, "bucket"), prefix: ref(artifact, "key") } },
-          runtime: runtime.runtimeVersion,
-          entry_point: instrumented
-            ? ["opentelemetry-instrument", literal(runtime.entrypoint)]
-            : [literal(runtime.entrypoint)],
-        },
-      },
-      network_configuration: { network_mode: "PUBLIC" },
-      protocol_configuration: runtime.protocol ?? "HTTP",
-      environment_variables: environment,
-      request_header_configuration: runtime.requestHeaderAllowlist
-        ? { request_header_allowlist: runtime.requestHeaderAllowlist.map(literal) }
-        : undefined,
-      lifecycle_configuration: runtime.lifecycleConfiguration
-        ? {
-            idle_runtime_session_timeout: runtime.lifecycleConfiguration.idleRuntimeSessionTimeout,
-            max_lifetime: runtime.lifecycleConfiguration.maxLifetime,
-          }
-        : undefined,
-      tags: tagMap(this.project, runtime.tags),
-      depends_on: [role.dependency],
-    });
-    this.publish(
-      "runtime",
-      runtime.name,
-      ref(resource, "agent_runtime_id"),
-      ref(resource, "agent_runtime_arn"),
-    );
-    this.add("aws_cloudwatch_log_group", `runtime/${runtime.name}`, {
-      name: `/aws/bedrock-agentcore/runtimes/${ref(resource, "agent_runtime_id")}-DEFAULT`,
-      retention_in_days: 7,
-      tags: tagMap(this.project),
-    });
-  }
-  private onlineEvaluation(config: OnlineEvalConfig): void {
-    const runtime = this.project.spec.runtimes.find((entry) => entry.name === config.agent)!;
-    const runtimeLogs = this.address("aws_cloudwatch_log_group", `runtime/${runtime.name}`);
-    const name = this.physical(config.name);
-    const outputLogs = this.add("aws_cloudwatch_log_group", `evaluation/${config.name}`, {
-      name: `/aws/bedrock-agentcore/evaluations/${name}`,
-      retention_in_days: 7,
-      tags: tagMap(this.project),
-    });
-    const role = this.role(
-      `evaluation/${config.name}`,
-      "bedrock-agentcore.amazonaws.com",
-      [
-        statement(
-          [
-            "logs:StartQuery",
-            "logs:FilterLogEvents",
-            "logs:GetLogEvents",
-            "logs:DescribeLogStreams",
-          ],
-          [
-            ref(runtimeLogs, "arn"),
-            `${ref(runtimeLogs, "arn")}:*`,
-            this.arn("logs", "log-group:aws/spans"),
-            this.arn("logs", "log-group:aws/spans:*"),
-          ],
-        ),
-        statement(
-          ["logs:DescribeIndexPolicies", "logs:PutIndexPolicy"],
-          [this.arn("logs", "log-group:aws/spans"), this.arn("logs", "log-group:aws/spans:*")],
-        ),
-        statement(
-          [
-            "logs:DescribeLogGroups",
-            "logs:GetQueryResults",
-            "logs:StopQuery",
-            "cloudwatch:GenerateQuery",
-            "cloudwatch:GenerateQueryResultsSummary",
-            "cloudwatch:PutMetricData",
-            "xray:GetTraceSummaries",
-            "xray:BatchGetTraces",
-          ],
-          ["*"],
-        ),
-        statement(["logs:CreateLogStream", "logs:PutLogEvents"], [`${ref(outputLogs, "arn")}:*`]),
-        statement(
-          ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
-          [
-            `arn:${this.partition}:bedrock:*::foundation-model/*`,
-            `arn:${this.partition}:bedrock:*:${this.target.account}:inference-profile/*`,
-            `arn:${this.partition}:bedrock:*:${this.target.account}:application-inference-profile/*`,
-          ],
-        ),
-        statement(
-          ["bedrock-agentcore:Evaluate", "bedrock-agentcore:GetEvaluator"],
-          config.evaluators.map(
-            (evaluator) => `arn:${this.partition}:bedrock-agentcore:::evaluator/${evaluator}`,
-          ),
-        ),
-        statement(
-          ["bedrock-agentcore:StartBatchEvaluation"],
-          [this.arn("bedrock-agentcore", "batch-evaluate/*")],
-        ),
-        statement(
-          ["bedrock-agentcore:GetOnlineEvaluationConfig"],
-          [this.arn("bedrock-agentcore", `online-evaluation-config/${name}-*`)],
-        ),
-      ],
-      [
-        this.arn("bedrock-agentcore", "online-evaluation-config/*"),
-        this.arn("bedrock-agentcore", "evaluator/*"),
-      ],
-    );
-    const resource = this.add("awscc_bedrockagentcore_online_evaluation_config", config.name, {
-      online_evaluation_config_name: name,
-      description: optional(config.description),
-      evaluation_execution_role_arn: role.arn,
-      data_source_config: {
-        cloudwatch_logs: {
-          log_group_names: [ref(runtimeLogs, "name")],
-          service_names: [`${this.physical(runtime.name)}.DEFAULT`],
-        },
-      },
-      evaluators: config.evaluators.map((evaluator) => ({ evaluator_id: literal(evaluator) })),
-      rule: {
-        sampling_config: { sampling_percentage: config.samplingRate },
-        session_config: { session_timeout_minutes: 5 },
-      },
-      execution_status: config.enableOnCreate === false ? "DISABLED" : "ENABLED",
-      output_config: {
-        cloudwatch_config: {
-          log_group_name: ref(outputLogs, "name"),
-          result_destination: "DEDICATED_LOG_GROUP",
-        },
-      },
-      tags: tagList(tagMap(this.project, config.tags)),
-      depends_on: [role.dependency],
-    });
-    this.publish(
-      "online-eval",
-      config.name,
-      ref(resource, "online_evaluation_config_id"),
-      ref(resource, "online_evaluation_config_arn"),
-    );
-  }
-}
diff --git a/src/core/project/backends/terraform/preflight.test.ts b/src/core/project/backends/terraform/preflight.test.ts
new file mode 100644
index 0000000000..869079cbf2
--- /dev/null
+++ b/src/core/project/backends/terraform/preflight.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, test } from "bun:test";
+import type { Project } from "../../../../handlers/project/types";
+import { ProjectSpecSchema } from "../../../../projectSchemas/project";
+import { TerraformProjectValidator, declaredResources } from "./preflight";
+
+function project(): Project {
+  return {
+    name: "Example",
+    rootPath: "/tmp/example",
+    spec: ProjectSpecSchema.parse({
+      name: "Example",
+      version: 2,
+      managedBy: "Terraform",
+      runtimes: [
+        {
+          name: "Agent",
+          build: "CodeZip",
+          runtimeVersion: "PYTHON_3_12",
+          codeLocation: "src/agent",
+          entrypoint: "main.py",
+        },
+      ],
+      memories: [{ name: "Memory", eventExpiryDuration: 7, strategies: [{ type: "SEMANTIC" }] }],
+      policyEngines: [
+        {
+          name: "Rules",
+          policies: [
+            {
+              name: "Allow",
+              statement: "permit(principal, action, resource);",
+              enforcementMode: "LOG_ONLY",
+            },
+          ],
+        },
+      ],
+      agentCoreGateways: [
+        {
+          name: "tools",
+          authorizerType: "AWS_IAM",
+          policyEngineConfiguration: { policyEngineName: "Rules", mode: "LOG_ONLY" },
+          targets: [
+            {
+              name: "echo",
+              targetType: "lambda",
+              toolDefinitions: [
+                {
+                  name: "echo",
+                  description: "Echo input",
+                  inputSchema: {
+                    type: "object",
+                    properties: { message: { type: "string" }, optional: { type: "boolean" } },
+                    required: ["message"],
+                  },
+                },
+              ],
+              compute: {
+                host: "Lambda",
+                pythonVersion: "PYTHON_3_12",
+                implementation: { language: "Python", path: "src/tool", handler: "main.handler" },
+              },
+            },
+          ],
+        },
+      ],
+      onlineEvalConfigs: [
+        { name: "Quality", agent: "Agent", samplingRate: 100, evaluators: ["Builtin.Helpfulness"] },
+      ],
+    }),
+  };
+}
+describe("Terraform project preflight", () => {
+  test("accepts the scoped connected project", () => {
+    expect(() => new TerraformProjectValidator().validate(project())).not.toThrow();
+    expect(declaredResources(project())).toHaveLength(7);
+  });
+  test.each([
+    [
+      "migratedFrom",
+      (p: Project) => {
+        p.spec.migratedFrom = "v1";
+      },
+    ],
+    [
+      "runtimes[Agent].build",
+      (p: Project) => {
+        p.spec.runtimes[0]!.build = "Container";
+      },
+    ],
+    [
+      "runtimes[Agent].executionRoleArn",
+      (p: Project) => {
+        p.spec.runtimes[0]!.executionRoleArn = "arn:aws:iam::111122223333:role/existing";
+      },
+    ],
+    [
+      "runtimes[Agent].networkMode",
+      (p: Project) => {
+        p.spec.runtimes[0]!.networkMode = "VPC";
+      },
+    ],
+    [
+      "runtimes[Agent].runtimeVersion",
+      (p: Project) => {
+        p.spec.runtimes[0]!.runtimeVersion = "NODE_22";
+      },
+    ],
+    [
+      "runtimes[Agent].entrypoint",
+      (p: Project) => {
+        p.spec.runtimes[0]!.entrypoint = "main.py:app";
+      },
+    ],
+    [
+      "agentCoreGateways[tools].authorizerType",
+      (p: Project) => {
+        p.spec.agentCoreGateways[0]!.authorizerType = "NONE";
+      },
+    ],
+    [
+      "onlineEvalConfigs[Quality].evaluators",
+      (p: Project) => {
+        p.spec.onlineEvalConfigs[0]!.evaluators = ["Custom"];
+      },
+    ],
+    [
+      "onlineEvalConfigs[Quality].agent",
+      (p: Project) => {
+        p.spec.runtimes[0]!.instrumentation = { enableOtel: false };
+      },
+    ],
+    [
+      "envVars.MEMORY_MEMORY_ID",
+      (p: Project) => {
+        p.spec.runtimes[0]!.envVars = [{ name: "MEMORY_MEMORY_ID", value: "wrong" }];
+      },
+    ],
+    [
+      "memories[memory].name",
+      (p: Project) => {
+        p.spec.memories.push({ ...p.spec.memories[0]!, name: "memory" });
+      },
+    ],
+    [
+      "envVars.OTEL_SERVICE_NAME",
+      (p: Project) => {
+        p.spec.runtimes[0]!.envVars = [{ name: "OTEL_SERVICE_NAME", value: "other" }];
+      },
+    ],
+    [
+      "inputSchema.required",
+      (p: Project) => {
+        p.spec.agentCoreGateways[0]!.targets[0]!.toolDefinitions![0]!.inputSchema.required = [
+          "undeclared",
+        ];
+      },
+    ],
+  ] as const)("rejects unsupported %s before packaging or deployment", (path, change) => {
+    const p = project();
+    change(p);
+    expect(() => new TerraformProjectValidator().validate(p)).toThrow(path);
+  });
+});
diff --git a/src/core/project/backends/terraform/preflight.ts b/src/core/project/backends/terraform/preflight.ts
new file mode 100644
index 0000000000..53d073ced4
--- /dev/null
+++ b/src/core/project/backends/terraform/preflight.ts
@@ -0,0 +1,271 @@
+import { InputValidationError } from "../../../../errors";
+import type { Project } from "../../../../handlers/project/types";
+import type { SchemaDefinition } from "../../../../projectSchemas/mcp-defs";
+import type { TerraformResourceDescriptor } from "./types";
+
+export function declaredResources(project: Project): TerraformResourceDescriptor[] {
+  return [
+    ...project.spec.runtimes.map(({ name }) => ({ resourceType: "runtime" as const, name })),
+    ...project.spec.memories.map(({ name }) => ({ resourceType: "memory" as const, name })),
+    ...project.spec.policyEngines.flatMap(({ name, policies }) => [
+      { resourceType: "policy-engine" as const, name },
+      ...policies.map((policy) => ({
+        resourceType: "policy" as const,
+        name: policy.name,
+        parentName: name,
+      })),
+    ]),
+    ...project.spec.agentCoreGateways.flatMap(({ name, targets }) => [
+      { resourceType: "gateway" as const, name },
+      ...targets.map((target) => ({
+        resourceType: "gateway-target" as const,
+        name: target.name,
+        parentName: name,
+      })),
+    ]),
+    ...project.spec.onlineEvalConfigs.map(({ name }) => ({
+      resourceType: "online-eval" as const,
+      name,
+    })),
+  ];
+}
+
+const hasValue = (value: unknown) =>
+  value !== undefined && (!Array.isArray(value) || value.length > 0);
+
+function reject(path: string, detail = "is not supported by the Terraform PoC"): never {
+  throw new InputValidationError(`agentcore.json ${path}: ${detail}.`);
+}
+function fields(value: object, allowed: string[], path: string): void {
+  for (const [name, entry] of Object.entries(value)) {
+    if (hasValue(entry) && !allowed.includes(name)) reject(`${path}.${name}`);
+  }
+}
+
+/** Checks the deliberately bounded CLI Terraform PoC before packaging or cloud operations. */
+export class TerraformProjectValidator {
+  validate(project: Project): void {
+    fields(
+      project.spec,
+      [
+        "name",
+        "version",
+        "managedBy",
+        "tags",
+        "runtimes",
+        "memories",
+        "policyEngines",
+        "agentCoreGateways",
+        "onlineEvalConfigs",
+      ],
+      "project",
+    );
+    for (const runtime of project.spec.runtimes) {
+      const path = `runtimes[${runtime.name}]`;
+      fields(
+        runtime,
+        [
+          "name",
+          "description",
+          "modelProvider",
+          "modelId",
+          "build",
+          "codeLocation",
+          "entrypoint",
+          "runtimeVersion",
+          "envVars",
+          "instrumentation",
+          "networkMode",
+          "authorizerType",
+          "protocol",
+          "requestHeaderAllowlist",
+          "tags",
+          "lifecycleConfiguration",
+        ],
+        path,
+      );
+      if (runtime.build !== "CodeZip") reject(`${path}.build`, "must be CodeZip for this PoC");
+      if (!runtime.runtimeVersion?.startsWith("PYTHON_3_"))
+        reject(`${path}.runtimeVersion`, "must select a Python managed runtime");
+      if (runtime.networkMode && runtime.networkMode !== "PUBLIC")
+        reject(`${path}.networkMode`, "must be PUBLIC for this PoC");
+      if (runtime.authorizerType && runtime.authorizerType !== "AWS_IAM")
+        reject(`${path}.authorizerType`, "must be AWS_IAM for this PoC");
+      if (!runtime.entrypoint.endsWith(".py"))
+        reject(`${path}.entrypoint`, "must be a Python script without a handler suffix");
+      const environment = new Set<string>();
+      for (const env of runtime.envVars ?? []) {
+        if (environment.has(env.name))
+          reject(`${path}.envVars`, `contains duplicate variable ${env.name}`);
+        environment.add(env.name);
+        const generated =
+          project.spec.memories.some((memory) =>
+            [
+              `MEMORY_${memory.name.toUpperCase()}_ID`,
+              `MEMORY_${memory.name.toUpperCase()}_ARN`,
+            ].includes(env.name),
+          ) ||
+          project.spec.agentCoreGateways.some((gateway) =>
+            ["URL", "ARN", "ID"]
+              .map((suffix) => `${this.gatewayPrefix(gateway.name)}_${suffix}`)
+              .includes(env.name),
+          );
+        if (generated)
+          reject(
+            `${path}.envVars.${env.name}`,
+            "conflicts with a project resource discovery variable",
+          );
+      }
+    }
+    const memoryVariables = new Set<string>();
+    for (const memory of project.spec.memories) {
+      const environmentName = memory.name.toUpperCase();
+      if (memoryVariables.has(environmentName))
+        reject(
+          `memories[${memory.name}].name`,
+          "collides with another memory's discovery variables",
+        );
+      memoryVariables.add(environmentName);
+      fields(
+        memory,
+        ["name", "description", "eventExpiryDuration", "strategies", "indexedKeys", "tags"],
+        `memories[${memory.name}]`,
+      );
+    }
+    for (const engine of project.spec.policyEngines) {
+      fields(
+        engine,
+        ["name", "description", "encryptionKeyArn", "tags", "policies"],
+        `policyEngines[${engine.name}]`,
+      );
+      // sourceFile and authorizationPhase are CLI provenance/inference metadata. Like the L3,
+      // the deployment uses the actual statement and the service determines authorization phase.
+    }
+    const gatewayVariables = new Set<string>();
+    for (const gateway of project.spec.agentCoreGateways) {
+      const path = `agentCoreGateways[${gateway.name}]`;
+      fields(
+        gateway,
+        [
+          "name",
+          "resourceName",
+          "protocolType",
+          "description",
+          "targets",
+          "authorizerType",
+          "enableSemanticSearch",
+          "exceptionLevel",
+          "policyEngineConfiguration",
+          "tags",
+        ],
+        path,
+      );
+      if (gateway.authorizerType !== "AWS_IAM")
+        reject(`${path}.authorizerType`, "must be AWS_IAM for this PoC");
+      if (gateway.protocolType && gateway.protocolType !== "MCP")
+        reject(`${path}.protocolType`, "must be MCP for this PoC");
+      if (gatewayVariables.has(this.gatewayPrefix(gateway.name)))
+        reject(`${path}.name`, "collides with another gateway's discovery variables");
+      gatewayVariables.add(this.gatewayPrefix(gateway.name));
+      const names = new Set<string>();
+      for (const target of gateway.targets) {
+        const targetPath = `${path}.targets[${target.name}]`;
+        fields(
+          target,
+          ["name", "targetType", "toolDefinitions", "compute", "outboundAuth"],
+          targetPath,
+        );
+        if (names.has(target.name)) reject(`${targetPath}.name`, "duplicates another target");
+        names.add(target.name);
+        if (target.targetType !== "lambda")
+          reject(`${targetPath}.targetType`, "must be lambda for this PoC");
+        if (
+          target.compute?.host !== "Lambda" ||
+          target.compute.implementation.language !== "Python"
+        )
+          reject(`${targetPath}.compute`, "must be a Python Lambda for this PoC");
+        fields(
+          target.compute,
+          ["host", "implementation", "pythonVersion", "timeout", "memorySize", "iamPolicy"],
+          `${targetPath}.compute`,
+        );
+        fields(
+          target.compute.implementation,
+          ["language", "path", "handler"],
+          `${targetPath}.compute.implementation`,
+        );
+        if (target.compute.iamPolicy) {
+          fields(
+            target.compute.iamPolicy,
+            ["Version", "Statement"],
+            `${targetPath}.compute.iamPolicy`,
+          );
+          if (target.compute.iamPolicy.Version !== "2012-10-17")
+            reject(`${targetPath}.compute.iamPolicy.Version`, "must be 2012-10-17");
+        }
+        if (target.compute.nodeVersion) reject(`${targetPath}.compute.nodeVersion`);
+        if (target.outboundAuth && Object.keys(target.outboundAuth).some((name) => name !== "type"))
+          reject(`${targetPath}.outboundAuth`);
+        if (target.outboundAuth && target.outboundAuth.type !== "NONE")
+          reject(`${targetPath}.outboundAuth.type`);
+        if (
+          !/^[a-zA-Z_][a-zA-Z0-9_.]*\.[a-zA-Z_][a-zA-Z0-9_]*$/.test(
+            target.compute.implementation.handler,
+          )
+        )
+          reject(
+            `${targetPath}.compute.implementation.handler`,
+            "must use the Lambda module.function format",
+          );
+        for (const tool of target.toolDefinitions ?? []) {
+          this.validateToolSchema(tool.inputSchema, `${targetPath}.${tool.name}.inputSchema`);
+          if (tool.outputSchema)
+            this.validateToolSchema(tool.outputSchema, `${targetPath}.${tool.name}.outputSchema`);
+        }
+      }
+    }
+    for (const config of project.spec.onlineEvalConfigs) {
+      const path = `onlineEvalConfigs[${config.name}]`;
+      if (!config.agent || config.logGroupNames || config.serviceNames)
+        reject(path, "must reference a project runtime for this PoC");
+      if (config.endpoint && config.endpoint !== "DEFAULT")
+        reject(`${path}.endpoint`, "must use DEFAULT for this PoC");
+      if (config.evaluators.some((name) => !name.startsWith("Builtin.")))
+        reject(`${path}.evaluators`, "must contain built-in evaluators for this PoC");
+      const runtime = project.spec.runtimes.find((entry) => entry.name === config.agent);
+      if (!runtime) reject(`${path}.agent`, "references an unknown runtime");
+      if (runtime.instrumentation?.enableOtel === false)
+        reject(
+          `${path}.agent`,
+          "requires runtime OpenTelemetry instrumentation for online evaluation",
+        );
+      for (const env of runtime.envVars ?? []) {
+        if (env.name.startsWith("OTEL_") || env.name === "UNIFIED_TRACES_DESTINATION_ENABLED")
+          reject(
+            `runtimes[${runtime.name}].envVars.${env.name}`,
+            "cannot override service-managed telemetry while a project online evaluation uses this runtime",
+          );
+      }
+    }
+  }
+
+  private gatewayPrefix(name: string): string {
+    return `AGENTCORE_GATEWAY_${name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+  }
+  private validateToolSchema(schema: SchemaDefinition, path: string): void {
+    if (schema.items && schema.type !== "array")
+      reject(`${path}.items`, "requires an array schema");
+    if ((schema.properties || schema.required?.length) && schema.type !== "object")
+      reject(path, "properties and required are supported only on object schemas");
+    for (const required of schema.required ?? []) {
+      if (!Object.hasOwn(schema.properties ?? {}, required))
+        reject(
+          `${path}.required`,
+          `references property ${required} without a declaration; the native provider cannot preserve it`,
+        );
+    }
+    for (const [name, property] of Object.entries(schema.properties ?? {}))
+      this.validateToolSchema(property, `${path}.properties.${name}`);
+    if (schema.items) this.validateToolSchema(schema.items, `${path}.items`);
+  }
+}
diff --git a/src/core/project/backends/terraform/project.test.ts b/src/core/project/backends/terraform/project.test.ts
new file mode 100644
index 0000000000..ef27e5b7ac
--- /dev/null
+++ b/src/core/project/backends/terraform/project.test.ts
@@ -0,0 +1,205 @@
+import { afterEach, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { TerraformProjectWriter } from "./project";
+
+const target = { name: "test", account: "111122223333", region: "us-east-1" } as const;
+const directories: string[] = [];
+afterEach(async () => {
+  await Promise.all(
+    directories.splice(0).map((path) => rm(path, { recursive: true, force: true })),
+  );
+});
+async function directory() {
+  const path = await mkdtemp(join(tmpdir(), "terraform-project-"));
+  directories.push(path);
+  return path;
+}
+const emptyAssets = { runtimes: {}, gatewayTargets: {} };
+const modulePath = (root: string, name = "main.tf") =>
+  join(root, "modules", "agentcore-application", name);
+
+test("scaffolds immediately with a required account and no placeholder deployment inputs", async () => {
+  const root = await directory();
+  await new TerraformProjectWriter().scaffold(root, "eu-west-1");
+  expect(existsSync(join(root, "main.tf"))).toBe(true);
+  expect(existsSync(join(root, "deployment.auto.tfvars.json"))).toBe(false);
+  const variables = await readFile(join(root, "variables.tf"), "utf8");
+  expect(variables).toContain('default     = "default"');
+  expect(variables).toContain('default     = "eu-west-1"');
+  expect(variables).not.toContain("000000000000");
+  expect(variables.split('variable "account_id"')[1]!.split('variable "region"')[0]).not.toContain(
+    "default",
+  );
+});
+
+test("a named target inherits customer Terraform source without copying state or target inputs", async () => {
+  const parent = await directory();
+  const original = join(parent, "default");
+  const named = join(parent, "production");
+  const writer = new TerraformProjectWriter();
+  await writer.scaffold(original);
+  await writeFile(join(original, "custom.tf"), "# custom resource\n");
+  await writeFile(join(original, "custom.tf.json"), '{"resource":{}}\n');
+  await writeFile(join(original, "terraform.tfstate"), '{"resources":[]}\n');
+  await writeFile(join(original, "deployment.auto.tfvars.json"), '{"account_id":"111122223333"}\n');
+  await writer.inheritRoot(named, original);
+  await writer.write(named, { ...target, name: "production" }, emptyAssets);
+  expect(await readFile(join(named, "custom.tf"), "utf8")).toBe("# custom resource\n");
+  expect(await readFile(join(named, "custom.tf.json"), "utf8")).toBe('{"resource":{}}\n');
+  expect(existsSync(join(named, "terraform.tfstate"))).toBe(false);
+  expect(
+    JSON.parse(await readFile(join(named, "deployment.auto.tfvars.json"), "utf8")).target_name,
+  ).toBe("production");
+});
+
+test("scaffolds native HCL with a direct project file reference and portable artifact manifest", async () => {
+  const root = await directory();
+  await new TerraformProjectWriter().write(root, target, {
+    runtimes: { Agent: { path: join(root, "assets", "agent.zip"), hash: "a".repeat(64) } },
+    gatewayTargets: {},
+  });
+  const main = await readFile(join(root, "main.tf"), "utf8");
+  expect(main).toContain(
+    "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=",
+  );
+  expect(existsSync(join(root, "modules"))).toBe(false);
+  expect(existsSync(join(root, ".terraform"))).toBe(false);
+  expect(main).toContain('jsondecode(file("${path.module}/../../agentcore.json"))');
+  expect(main).toContain('jsondecode(file("${path.module}/artifacts.json"))');
+  expect(existsSync(join(root, "main.tf.json"))).toBe(false);
+  expect(JSON.parse(await readFile(join(root, "artifacts.json"), "utf8")).runtimes.Agent.path).toBe(
+    "assets/agent.zip",
+  );
+  expect(await readFile(join(root, "providers.tf"), "utf8")).toContain(
+    "allowed_account_ids = [var.account_id]",
+  );
+  expect(await readFile(join(root, "outputs.tf"), "utf8")).toContain(
+    "module.application.project_resources",
+  );
+  expect((await readdir(root, { recursive: true })).sort()).toEqual([
+    "artifacts.json",
+    "deployment.auto.tfvars.json",
+    "main.tf",
+    "outputs.tf",
+    "providers.tf",
+    "variables.tf",
+  ]);
+});
+
+test("the module source is pinned to an immutable commit", async () => {
+  const root = await directory();
+  await new TerraformProjectWriter().scaffold(root);
+  expect(await readFile(join(root, "main.tf"), "utf8")).toMatch(/\?ref=[a-f0-9]{40}"/);
+});
+
+test("preserves the customer's module source and inline spec", async () => {
+  const root = await directory();
+  const writer = new TerraformProjectWriter();
+  await writer.write(root, target, emptyAssets);
+  const custom =
+    'module "application" { source = "./modules/custom" spec = { name = "Custom" } }\n';
+  await writeFile(join(root, "main.tf"), custom);
+  await writer.write(root, target, emptyAssets);
+  expect(await readFile(join(root, "main.tf"), "utf8")).toBe(custom);
+});
+
+test("preserves customer root configuration and Terraform state, plans, and provider lock", async () => {
+  const root = await directory();
+  const writer = new TerraformProjectWriter();
+  await writer.write(root, target, emptyAssets);
+  const preserved: Record<string, string> = {
+    "main.tf": "# custom main\n",
+    "providers.tf": "# custom providers\n",
+    "variables.tf": "# custom variables\n",
+    "outputs.tf": "# custom outputs\n",
+    "custom.tf": "# custom extra resources\n",
+    ".terraform.lock.hcl": "# selected provider hashes\n",
+    "deployment.tfplan": "saved plan",
+    "terraform.tfstate": JSON.stringify({
+      resources: [{ mode: "managed", type: "aws_s3_bucket", name: "customer" }],
+    }),
+  };
+  for (const [name, text] of Object.entries(preserved)) await writeFile(join(root, name), text);
+  await writer.write(root, target, emptyAssets);
+  for (const [name, text] of Object.entries(preserved)) {
+    expect(await readFile(join(root, name), "utf8")).toBe(text);
+  }
+});
+
+test("inherits local customer modules without copying Terraform working files", async () => {
+  const parent = await directory();
+  const original = join(parent, "default");
+  const named = join(parent, "production");
+  const writer = new TerraformProjectWriter();
+  await writer.scaffold(original);
+  await mkdir(modulePath(original, ".terraform"), { recursive: true });
+  await writeFile(modulePath(original), "# customer module\n");
+  await writeFile(modulePath(original, ".terraform/provider"), "binary");
+  await writeFile(modulePath(original, "terraform.tfstate"), "{}");
+  await writer.inheritRoot(named, original);
+  expect(await readdir(modulePath(named, ""))).toEqual(["main.tf"]);
+  expect(await readFile(modulePath(named), "utf8")).toBe("# customer module\n");
+});
+
+test("refuses to follow local module symlinks during target inheritance", async () => {
+  const parent = await directory();
+  const outside = await directory();
+  const original = join(parent, "default");
+  const writer = new TerraformProjectWriter();
+  await writer.scaffold(original);
+  await symlink(outside, join(original, "modules"));
+  await expect(writer.inheritRoot(join(parent, "production"), original)).rejects.toThrow(
+    "symlinked",
+  );
+});
+
+test.each(["main.tf.json", "terraform.tfstate", "terraform.tfstate.backup"])(
+  "refuses the earlier flat PoC %s",
+  async (filename) => {
+    const root = await directory();
+    const contents =
+      filename === "main.tf.json"
+        ? "{}"
+        : JSON.stringify({
+            resources: [{ mode: "managed", type: "awscc_bedrockagentcore_memory", name: "old" }],
+          });
+    await writeFile(join(root, filename), contents);
+    await expect(new TerraformProjectWriter().write(root, target, emptyAssets)).rejects.toThrow(
+      "migration",
+    );
+    expect(await readFile(join(root, filename), "utf8")).toBe(contents);
+    expect(existsSync(join(root, "main.tf"))).toBe(false);
+  },
+);
+
+test("an empty state permits initializing a module root", async () => {
+  const root = await directory();
+  await writeFile(join(root, "terraform.tfstate"), JSON.stringify({ resources: [] }));
+  await new TerraformProjectWriter().write(root, target, emptyAssets);
+  expect(existsSync(join(root, "main.tf"))).toBe(true);
+});
+
+test("refuses an existing state from a differently named module", async () => {
+  const root = await directory();
+  await writeFile(
+    join(root, "terraform.tfstate"),
+    JSON.stringify({ resources: [{ mode: "managed", module: "module.application_custom" }] }),
+  );
+  await expect(new TerraformProjectWriter().write(root, target, emptyAssets)).rejects.toThrow(
+    "migration",
+  );
+});
+
+test("rejects assets outside the root rather than writing a nonportable manifest", async () => {
+  const root = await directory();
+  await expect(
+    new TerraformProjectWriter().write(root, target, {
+      runtimes: { Agent: { path: join(root, "..", "outside.zip"), hash: "a".repeat(64) } },
+      gatewayTargets: {},
+    }),
+  ).rejects.toThrow("Invalid Terraform artifact path");
+  expect(existsSync(join(root, "main.tf"))).toBe(false);
+});
diff --git a/src/core/project/backends/terraform/project.ts b/src/core/project/backends/terraform/project.ts
new file mode 100644
index 0000000000..02e75942d1
--- /dev/null
+++ b/src/core/project/backends/terraform/project.ts
@@ -0,0 +1,260 @@
+import { existsSync } from "node:fs";
+import { cp, lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+import { ProjectStateError } from "../../../../errors";
+import { atomicWrite } from "../../../../io";
+import type { AwsDeploymentTarget } from "../../../../projectSchemas/aws-targets";
+import type { TerraformAssets } from "./types";
+
+const ROOT_FILES: Record<string, string> = {
+  "main.tf": `# This root is yours to edit. The CLI refreshes artifacts.json and target inputs.
+module "application" {
+  source      = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=d3ce7229610ce0bb56d581c55f710e220b58faa4"
+  spec        = jsondecode(file("\${path.module}/../../agentcore.json"))
+  target_name = var.target_name
+  account_id  = var.account_id
+  region      = var.region
+  artifacts   = jsondecode(file("\${path.module}/artifacts.json"))
+}
+`,
+  "providers.tf": `terraform {
+  required_version = ">= 1.12.0, < 2.0.0"
+  required_providers {
+    awscc = {
+      source  = "hashicorp/awscc"
+      version = "= 1.106.0"
+    }
+    aws = {
+      source  = "hashicorp/aws"
+      version = "= 6.69.0"
+    }
+  }
+}
+
+provider "aws" {
+  region              = var.region
+  allowed_account_ids = [var.account_id]
+}
+
+provider "awscc" {
+  region = var.region
+}
+
+# Ensures the account guard also runs for projects containing only AWSCC resources.
+data "aws_caller_identity" "current" {}
+`,
+  "variables.tf": `variable "target_name" {
+  type        = string
+  description = "Logical deployment target name."
+  default     = "default"
+  validation {
+    condition     = can(regex("^[a-zA-Z][a-zA-Z0-9-]{0,63}$", var.target_name))
+    error_message = "target_name must be a valid AgentCore deployment target name."
+  }
+}
+
+variable "account_id" {
+  type        = string
+  description = "Expected AWS account ID."
+  validation {
+    condition     = can(regex("^[0-9]{12}$", var.account_id))
+    error_message = "account_id must contain exactly 12 digits."
+  }
+}
+
+variable "region" {
+  type        = string
+  description = "AWS region for this deployment."
+  default     = "us-west-2"
+}
+`,
+  "outputs.tf": `output "project_resources" {
+  value = module.application.project_resources
+  precondition {
+    condition     = data.aws_caller_identity.current.account_id == var.account_id
+    error_message = "AWS credentials do not match the configured deployment account."
+  }
+}
+
+output "runtimes" {
+  value = module.application.runtimes
+}
+
+output "memories" {
+  value = module.application.memories
+}
+
+output "gateways" {
+  value = module.application.gateways
+}
+
+output "policy_engines" {
+  value = module.application.policy_engines
+}
+
+output "online_evaluations" {
+  value = module.application.online_evaluations
+}
+
+# Lets CLI commands verify state created through Terraform directly.
+output "deployment_target" {
+  value = {
+    name    = var.target_name
+    account = var.account_id
+    region  = var.region
+  }
+}
+`,
+};
+
+/** Scaffolds an editable root around the pinned HCL module; never translates resources in TypeScript. */
+export class TerraformProjectWriter {
+  /** Create usable, editable Terraform source without Terraform or AWS credentials. */
+  async scaffold(directory: string, region?: string): Promise<void> {
+    await this.assertCompatible(directory);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    // wx is intentional: customer changes to the root survive every subsequent build/deploy.
+    for (const [filename, source] of Object.entries(ROOT_FILES)) {
+      const contents =
+        filename === "variables.tf" && region
+          ? source.replace('default     = "us-west-2"', `default     = ${JSON.stringify(region)}`)
+          : source;
+      await this.writeIfMissing(join(directory, filename), contents);
+    }
+    await this.writeIfMissing(
+      join(directory, "artifacts.json"),
+      `${JSON.stringify({ runtimes: {}, gatewayTargets: {} }, null, 2)}\n`,
+    );
+  }
+
+  /** A new named target starts from the customer's default root, without copying its state. */
+  async inheritRoot(directory: string, defaultDirectory: string): Promise<void> {
+    if (directory === defaultDirectory || existsSync(join(directory, "main.tf"))) return;
+    if (!existsSync(join(defaultDirectory, "main.tf"))) await this.scaffold(defaultDirectory);
+    await this.assertCompatible(defaultDirectory);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    // Only customer-authored modules live here; downloaded modules stay in .terraform.
+    const localModules = join(defaultDirectory, "modules");
+    if (existsSync(localModules) && !existsSync(join(directory, "modules"))) {
+      await cp(localModules, join(directory, "modules"), {
+        recursive: true,
+        filter: async (path) => {
+          const parts = relative(defaultDirectory, path).split(/[\\/]/);
+          if (
+            parts.some(
+              (part) =>
+                part === ".terraform" ||
+                part === ".git" ||
+                /\.tfstate(?:\.|$)/.test(part) ||
+                part.endsWith(".tfplan"),
+            )
+          )
+            return false;
+          if ((await lstat(path)).isSymbolicLink()) {
+            throw new ProjectStateError(
+              "Cannot inherit a symlinked local Terraform module. Copy its source into the new target manually.",
+            );
+          }
+          return true;
+        },
+      });
+    }
+    for (const entry of await readdir(defaultDirectory, { withFileTypes: true })) {
+      if (
+        entry.isFile() &&
+        (entry.name.endsWith(".tf") ||
+          entry.name.endsWith(".tf.json") ||
+          entry.name === ".terraform.lock.hcl")
+      ) {
+        await this.writeIfMissing(
+          join(directory, entry.name),
+          await readFile(join(defaultDirectory, entry.name), "utf8"),
+        );
+      }
+    }
+  }
+
+  async assertCompatible(directory: string): Promise<void> {
+    if (existsSync(join(directory, "main.tf.json"))) {
+      throw new ProjectStateError(
+        `The earlier Terraform PoC configuration exists at ${join(directory, "main.tf.json")}. ` +
+          "Automatic migration to module.application is not supported. Preserve any state and use a new deployment directory.",
+      );
+    }
+    // Existing HCL roots may contain customer resources alongside module.application.
+    // Account and region identity are checked by TerraformState before CLI deployment.
+    if (existsSync(join(directory, "main.tf"))) return;
+    for (const filename of ["terraform.tfstate", "terraform.tfstate.backup"]) {
+      const text = await this.readOptional(join(directory, filename));
+      if (text === undefined) continue;
+      const state = JSON.parse(text) as {
+        resources?: { mode?: string; module?: string }[];
+      };
+      if (
+        state.resources?.some(
+          (resource) =>
+            resource.mode === "managed" &&
+            resource.module !== "module.application" &&
+            !resource.module?.startsWith("module.application."),
+        )
+      ) {
+        throw new ProjectStateError(
+          `The Terraform state in ${directory} contains resources outside module.application. ` +
+            "Automatic state migration is not supported; preserve the state and use a new deployment directory.",
+        );
+      }
+    }
+  }
+
+  async write(
+    directory: string,
+    target: AwsDeploymentTarget | undefined,
+    assets: TerraformAssets,
+  ): Promise<void> {
+    await this.assertCompatible(directory);
+    const portableAssets: TerraformAssets = { runtimes: {}, gatewayTargets: {} };
+    for (const kind of ["runtimes", "gatewayTargets"] as const) {
+      for (const [name, artifact] of Object.entries(assets[kind])) {
+        const path = relative(directory, artifact.path).replaceAll("\\", "/");
+        this.checkRelativePath(path);
+        portableAssets[kind][name] = { path, hash: artifact.hash };
+      }
+    }
+    await this.scaffold(directory);
+    await atomicWrite(
+      join(directory, "artifacts.json"),
+      `${JSON.stringify(portableAssets, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+    if (target) {
+      await atomicWrite(
+        join(directory, "deployment.auto.tfvars.json"),
+        `${JSON.stringify({ target_name: target.name, account_id: target.account, region: target.region }, null, 2)}\n`,
+        { mode: 0o600 },
+      );
+    }
+  }
+
+  private checkRelativePath(path: string): void {
+    if (!path || isAbsolute(path) || path.split(/[\\/]/).includes("..")) {
+      throw new ProjectStateError(`Invalid Terraform artifact path: ${path}`);
+    }
+  }
+
+  private async readOptional(path: string): Promise<string | undefined> {
+    try {
+      return await readFile(path, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    }
+  }
+
+  private async writeIfMissing(path: string, contents: string): Promise<void> {
+    try {
+      await writeFile(path, contents, { flag: "wx", mode: 0o600 });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+}
diff --git a/src/core/project/backends/terraform/state.test.ts b/src/core/project/backends/terraform/state.test.ts
new file mode 100644
index 0000000000..4c99aa3a3b
--- /dev/null
+++ b/src/core/project/backends/terraform/state.test.ts
@@ -0,0 +1,125 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import type { Project } from "../../../../handlers/project/types";
+import { ProjectSpecSchema } from "../../../../projectSchemas/project";
+import { TerraformState } from "./state";
+
+const target = { name: "default", account: "111122223333", region: "us-east-1" } as const;
+const roots: string[] = [];
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+async function fixture() {
+  const rootPath = await mkdtemp(join(tmpdir(), "terraform-state-"));
+  roots.push(rootPath);
+  const project: Project = {
+    rootPath,
+    name: "Example",
+    spec: ProjectSpecSchema.parse({ name: "Example", version: 2, managedBy: "Terraform" }),
+  };
+  const state = new TerraformState(project);
+  await mkdir(state.directory, { recursive: true });
+  return { project, state };
+}
+const resource = { mode: "managed", module: "module.application" };
+const serialize = (identity?: unknown) =>
+  JSON.stringify({
+    resources: [resource],
+    outputs: identity ? { deployment_target: { value: identity } } : {},
+  });
+
+test.each([
+  { ...target, account: "999900001111" },
+  { ...target, region: "us-west-2" },
+  { ...target, name: "production" },
+] as const)("rejects replacing an established target identity: %j", async (replacement) => {
+  const { state } = await fixture();
+  await state.bind(target);
+  await expect(state.assertTarget(replacement)).rejects.toThrow("different target");
+  expect(
+    JSON.parse(await readFile(join(state.directory, ".agentcore-target.json"), "utf8")),
+  ).toEqual(target);
+});
+
+test("adopts matching standalone Terraform state through its deployment_target output", async () => {
+  const { state } = await fixture();
+  const text = serialize(target);
+  await writeFile(join(state.directory, "terraform.tfstate"), text);
+  await state.bind(target);
+  expect(await readFile(join(state.directory, "terraform.tfstate"), "utf8")).toBe(text);
+  await expect(state.assertTarget({ ...target, region: "us-west-2" })).rejects.toThrow(
+    "different target",
+  );
+});
+
+test("refuses partial standalone state without an identity", async () => {
+  const { state } = await fixture();
+  await writeFile(join(state.directory, "terraform.tfstate"), serialize());
+  await expect(state.bind(target)).rejects.toThrow("no deployment target identity");
+});
+
+test("refuses to start fresh when managed backup state exists but current state is missing", async () => {
+  const { state } = await fixture();
+  await writeFile(join(state.directory, "terraform.tfstate.backup"), serialize(target));
+  await expect(state.bind(target)).rejects.toThrow("current Terraform state is missing");
+});
+
+test.each(["build", "default-111122223333-us-east-1", "."])(
+  "refuses managed state in the earlier %s directory",
+  async (legacyName) => {
+    const { state } = await fixture();
+    const legacy = join(dirname(state.directory), legacyName);
+    await mkdir(legacy, { recursive: true });
+    await writeFile(join(legacy, "terraform.tfstate"), serialize());
+    await expect(state.assertTarget(target)).rejects.toThrow("earlier state directory");
+  },
+);
+
+test.each(["build", "test-111122223333-us-east-1"])(
+  "recognizes a new-layout named target called %s",
+  async (name) => {
+    const { project, state } = await fixture();
+    const other = new TerraformState(project, name);
+    await mkdir(other.directory, { recursive: true });
+    await writeFile(join(other.directory, "terraform.tfstate"), serialize({ ...target, name }));
+    await state.assertTarget(target);
+  },
+);
+
+test.each([
+  { type: "s3" },
+  { type: "cloud" },
+  { type: "local", config: { path: "../other.tfstate" } },
+  { type: "local", config: { workspace_dir: "../other-workspace" } },
+])("rejects unsupported initialized backend %j", async (backend) => {
+  const { state } = await fixture();
+  await mkdir(join(state.directory, ".terraform"));
+  await writeFile(
+    join(state.directory, ".terraform", "terraform.tfstate"),
+    JSON.stringify({ backend }),
+  );
+  await expect(state.assertTarget(target)).rejects.toThrow("require local state");
+});
+
+test("accepts the default local state path", async () => {
+  const { state } = await fixture();
+  await mkdir(join(state.directory, ".terraform"));
+  await writeFile(
+    join(state.directory, ".terraform", "terraform.tfstate"),
+    JSON.stringify({
+      backend: { type: "local", config: { path: join(state.directory, "terraform.tfstate") } },
+    }),
+  );
+  await state.assertTarget(target);
+});
+
+test("application teardown ignores customer resources outside the module", async () => {
+  const { state } = await fixture();
+  await writeFile(
+    join(state.directory, "terraform.tfstate"),
+    JSON.stringify({ resources: [{ mode: "managed", type: "aws_s3_bucket", name: "customer" }] }),
+  );
+  expect(await state.hasApplicationResources()).toBe(false);
+});
diff --git a/src/core/project/backends/terraform/state.ts b/src/core/project/backends/terraform/state.ts
index 6cc390d1ff..c81b135b6b 100644
--- a/src/core/project/backends/terraform/state.ts
+++ b/src/core/project/backends/terraform/state.ts
@@ -1,9 +1,15 @@
-import { mkdir, open, readFile, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { mkdir, open, readFile, readdir, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { z } from "zod";
 import { ProjectStateError } from "../../../../errors";
 import type { Project } from "../../../../handlers/project/types";
-import type { AwsDeploymentTarget } from "../../../../projectSchemas/aws-targets";
+import {
+  AwsDeploymentTargetSchema,
+  DEFAULT_TARGET_NAME,
+  type AwsDeploymentTarget,
+} from "../../../../projectSchemas/aws-targets";
+import { atomicWrite } from "../../../../io";
 
 const resourceSchema = z.object({
   resourceType: z.enum([
@@ -38,14 +44,139 @@ const stateSchema = z.object({
 export class TerraformState {
   readonly directory: string;
 
-  constructor(project: Project, target: AwsDeploymentTarget | "build") {
-    const key = target === "build" ? "build" : `${target.name}-${target.account}-${target.region}`;
+  constructor(project: Project, target: AwsDeploymentTarget | string = DEFAULT_TARGET_NAME) {
+    const key = typeof target === "string" ? target : target.name;
     if (!/^[a-zA-Z0-9_-]+$/.test(key)) {
       throw new ProjectStateError("Invalid Terraform target directory");
     }
     this.directory = join(project.rootPath, "agentcore", "terraform", key);
   }
 
+  /** Never silently start a second state beside the earlier PoC directory layout. */
+  async assertNoLegacyState(): Promise<void> {
+    const root = dirname(this.directory);
+    if (!existsSync(root)) return;
+    const legacy = [
+      root,
+      ...(await readdir(root, { withFileTypes: true }))
+        .filter(
+          (entry) =>
+            entry.isDirectory() && (entry.name === "build" || /-\d{12}-[a-z]+-/.test(entry.name)),
+        )
+        .map((entry) => join(root, entry.name)),
+    ];
+    directories: for (const path of legacy) {
+      if (path === this.directory) continue;
+      const binding = await this.readOptional(join(path, ".agentcore-target.json"));
+      const parsedBinding =
+        binding === undefined
+          ? undefined
+          : AwsDeploymentTargetSchema.safeParse(JSON.parse(binding));
+      if (
+        path !== root &&
+        parsedBinding?.success &&
+        parsedBinding.data.name === basename(path) &&
+        existsSync(join(path, "main.tf"))
+      ) {
+        continue;
+      }
+      for (const name of ["terraform.tfstate", "terraform.tfstate.backup"]) {
+        const text = await this.readOptional(join(path, name));
+        if (text === undefined) continue;
+        const parsed = stateSchema.parse(JSON.parse(text));
+        const identity = AwsDeploymentTargetSchema.safeParse(
+          parsed.outputs.deployment_target?.value,
+        );
+        if (path !== root && identity.success && identity.data.name === basename(path))
+          continue directories;
+        if (parsed.resources.some(({ mode }) => mode === "managed")) {
+          throw new ProjectStateError(
+            `Existing Terraform resources use the earlier state directory ${path}. ` +
+              "Automatic state migration is not supported; preserve that state and manage it from its existing directory.",
+          );
+        }
+      }
+    }
+  }
+
+  /** Verify local state before using or replacing the target's deployment inputs. */
+  async assertTarget(target: AwsDeploymentTarget): Promise<void> {
+    await this.assertNoLegacyState();
+    await this.assertLocalBackend();
+    const binding = await this.readOptional(join(this.directory, ".agentcore-target.json"));
+    const state = await this.read();
+    if (state === undefined) {
+      const backup = await this.readOptional(join(this.directory, "terraform.tfstate.backup"));
+      if (
+        backup &&
+        stateSchema.parse(JSON.parse(backup)).resources.some(({ mode }) => mode === "managed")
+      ) {
+        throw new ProjectStateError(
+          `The current Terraform state is missing from ${this.directory}, but its backup contains resources. ` +
+            "Restore or repair the current state before deploying; the CLI will not start another deployment.",
+        );
+      }
+    }
+    const stateTarget = state?.outputs.deployment_target?.value;
+    for (const value of [binding === undefined ? undefined : JSON.parse(binding), stateTarget]) {
+      if (value === undefined) continue;
+      const parsed = AwsDeploymentTargetSchema.safeParse(value);
+      if (
+        !parsed.success ||
+        parsed.data.name !== target.name ||
+        parsed.data.account !== target.account ||
+        parsed.data.region !== target.region
+      ) {
+        throw new ProjectStateError(
+          `Terraform state in ${this.directory} is bound to a different target, account, or region. ` +
+            "Use its original deployment target or a new named target; existing state will not be reassigned.",
+        );
+      }
+    }
+    if (
+      binding === undefined &&
+      stateTarget === undefined &&
+      state?.resources.some(({ mode }) => mode === "managed")
+    ) {
+      throw new ProjectStateError(
+        `Terraform resources in ${this.directory} have no deployment target identity. ` +
+          "Preserve the state and use Terraform directly to repair the deployment_target output before using the CLI.",
+      );
+    }
+  }
+
+  async bind(target: AwsDeploymentTarget): Promise<void> {
+    await this.assertTarget(target);
+    await atomicWrite(
+      join(this.directory, ".agentcore-target.json"),
+      `${JSON.stringify({ name: target.name, account: target.account, region: target.region }, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+  }
+
+  async assertLocalBackend(): Promise<void> {
+    const text = await this.readOptional(join(this.directory, ".terraform", "terraform.tfstate"));
+    if (text === undefined) return;
+    const metadata = JSON.parse(text) as {
+      backend?: { type?: string; config?: { path?: string; workspace_dir?: string } };
+    };
+    const backend = metadata.backend;
+    if (
+      (backend?.type && backend.type !== "local") ||
+      (backend?.config?.path &&
+        resolve(this.directory, backend.config.path) !==
+          join(this.directory, "terraform.tfstate")) ||
+      (backend?.config?.workspace_dir &&
+        resolve(this.directory, backend.config.workspace_dir) !==
+          join(this.directory, "terraform.tfstate.d"))
+    ) {
+      throw new ProjectStateError(
+        "CLI Terraform operations require local state at this target's terraform.tfstate. " +
+          "Use Terraform directly with a remote backend or a custom state path.",
+      );
+    }
+  }
+
   async lock(): Promise<() => Promise<void>> {
     await mkdir(this.directory, { recursive: true, mode: 0o700 });
     const path = join(this.directory, ".agentcore-operation.lock");
@@ -84,8 +215,15 @@ export class TerraformState {
     return parsed.data;
   }
 
-  async hasManagedResources(): Promise<boolean> {
-    return (await this.read())?.resources.some(({ mode }) => mode === "managed") ?? false;
+  async hasApplicationResources(): Promise<boolean> {
+    return (
+      (await this.read())?.resources.some(
+        ({ mode, module }) =>
+          mode === "managed" &&
+          typeof module === "string" &&
+          (module === "module.application" || module.startsWith("module.application.")),
+      ) ?? false
+    );
   }
 
   async outputs(): Promise<Record<string, unknown>> {
@@ -108,4 +246,13 @@ export class TerraformState {
     }
     return parsed.data;
   }
+
+  private async readOptional(path: string): Promise<string | undefined> {
+    try {
+      return await readFile(path, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    }
+  }
 }
diff --git a/src/core/project/backends/terraform/types.ts b/src/core/project/backends/terraform/types.ts
new file mode 100644
index 0000000000..d390b88635
--- /dev/null
+++ b/src/core/project/backends/terraform/types.ts
@@ -0,0 +1,13 @@
+import type { DeployableResource } from "../../../../handlers/project/types";
+
+export type TerraformArtifact = { path: string; hash: string };
+export type TerraformAssets = {
+  runtimes: Record<string, TerraformArtifact>;
+  /** Keys are gateway-name/target-name. */
+  gatewayTargets: Record<string, TerraformArtifact>;
+};
+export type TerraformResourceDescriptor = {
+  resourceType: DeployableResource;
+  name: string;
+  parentName?: string;
+};
diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts
index 67492bcd45..174bb7eccd 100644
--- a/src/core/project/manager.test.ts
+++ b/src/core/project/manager.test.ts
@@ -164,8 +164,22 @@ describe("FsProjectManager.create", () => {
     expect(commands).toEqual([]);
     expect(checkedTools).toEqual([]);
     const gitignore = await readFile(join(project.rootPath, ".gitignore"), "utf8");
-    expect(gitignore).toContain("agentcore/terraform/");
+    expect(gitignore).not.toContain("\nagentcore/terraform/\n");
     expect(gitignore).toContain("*.tfstate");
+    expect(gitignore).toContain("agentcore/terraform/**/.agentcore-target.json");
+    const terraformRoot = join(project.rootPath, "agentcore", "terraform", "default");
+    expect(await readFile(join(terraformRoot, "main.tf"), "utf8")).toContain(
+      'jsondecode(file("${path.module}/../../agentcore.json"))',
+    );
+    expect(await readFile(join(terraformRoot, "main.tf"), "utf8")).toContain(
+      "agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=",
+    );
+    expect(existsSync(join(terraformRoot, "modules"))).toBe(false);
+    expect(existsSync(join(terraformRoot, "deployment.auto.tfvars.json"))).toBe(false);
+    expect(JSON.parse(await readFile(join(terraformRoot, "artifacts.json"), "utf8"))).toEqual({
+      runtimes: {},
+      gatewayTargets: {},
+    });
     expect((await subject.resolve({ filePath: project.rootPath }))?.spec.managedBy).toBe(
       "Terraform",
     );
diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx
index 13935336c0..18da497279 100644
--- a/src/core/project/manager.tsx
+++ b/src/core/project/manager.tsx
@@ -89,6 +89,7 @@ import { isChinaRegion } from "../partition";
 import z from "zod";
 import { CdkBackend, type TransactionSearchEnabler } from "./backends/cdk";
 import { TerraformBackend } from "./backends/terraform";
+import { TerraformProjectWriter } from "./backends/terraform/project";
 import { resolveAwsAccount } from "./backends/cdk/environment";
 import type { ProjectBackend } from "./backends/types";
 import {
@@ -535,6 +536,13 @@ export class FsProjectManager implements ProjectManager {
 
     yield { type: "step", message: "Creating project tree" };
     await projectTree.write(destination);
+    if (input.managedBy === "Terraform") {
+      yield { type: "step", message: "Scaffolding Terraform application module" };
+      await new TerraformProjectWriter().scaffold(
+        join(destination, "agentcore", "terraform", DEFAULT_TARGET_NAME),
+        input.region,
+      );
+    }
 
     if (envEntries.length > 0) {
       yield { type: "step", message: "Writing model provider API key to agentcore/.env.local" };
diff --git a/src/core/project/templates/project.ts b/src/core/project/templates/project.ts
index 607faeb7b9..56b6ce82bd 100644
--- a/src/core/project/templates/project.ts
+++ b/src/core/project/templates/project.ts
@@ -44,7 +44,7 @@ export async function createProjectTree(
     FsTreeNode.createFile(".gitignore", async () => {
       const shared = await config.assetSource.read("templates/shared/gitignore.template");
       return managedBy === "Terraform"
-        ? `${shared}\n# Terraform generated configuration, assets, and local state\nagentcore/terraform/\n.terraform/\n*.tfstate\n*.tfstate.*\n*.tfplan\ncrash.log\n`
+        ? `${shared}\n# Terraform local packages, working files, and state (commit the .tf source)\nagentcore/terraform/**/assets/\nagentcore/terraform/**/artifacts.json\nagentcore/terraform/**/deployment.auto.tfvars.json\nagentcore/terraform/**/.agentcore-target.json\n.agentcore-operation.lock\n.terraform/\n*.tfstate\n*.tfstate.*\n*.tfplan\ncrash.log\n`
         : shared;
     }),
     FsTreeNode.createDirectory("agentcore", [
diff --git a/src/handlers/project/create/index.ts b/src/handlers/project/create/index.ts
index 7fa97bccaa..1f54af8645 100644
--- a/src/handlers/project/create/index.ts
+++ b/src/handlers/project/create/index.ts
@@ -116,9 +116,16 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
     flags: [
       flag("name", "name of the project to create", ProjectNameSchema),
       flag(
-        "managed-by",
-        "infrastructure backend (Terraform is an experimental AWSCC PoC)",
-        ManagedBySchema,
+        "iac",
+        "infrastructure backend: CDK or Terraform (experimental AWSCC PoC)",
+        z
+          .preprocess((value) => {
+            if (typeof value !== "string") return value;
+            if (value.toLowerCase() === "cdk") return "CDK";
+            if (value.toLowerCase() === "terraform") return "Terraform";
+            return value;
+          }, ManagedBySchema)
+          .default("CDK"),
       ),
       flag(
         "template",
@@ -135,7 +142,7 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
     ],
     handle: async (ctx, flags) => {
       const name = flags["name"];
-      if (!flags["skip-install"] && flags["managed-by"] === "CDK") {
+      if (!flags["skip-install"] && flags.iac === "CDK") {
         assertProjectPathFits(name, ctx.require(PlatformKey), {
           alternative: "pass --skip-install and install the CDK dependencies yourself",
         });
@@ -144,7 +151,8 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
       const template = flags["template"];
       const base = {
         name,
-        managedBy: flags["managed-by"],
+        managedBy: flags.iac,
+        region: ctx.require(RegionKey),
         skipInstall: flags["skip-install"],
         skipGit: flags["skip-git"],
       };
@@ -197,7 +205,7 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
         () => {
           if (template === EMPTY_TEMPLATE_NAME) {
             config.io.stderr.write(
-              emptyProjectCreatedMessage(name, isChinaRegion(region), flags["managed-by"]),
+              emptyProjectCreatedMessage(name, isChinaRegion(region), flags.iac),
             );
             return;
           }
diff --git a/src/handlers/project/project.test.ts b/src/handlers/project/project.test.ts
index b3ace74324..498190f287 100644
--- a/src/handlers/project/project.test.ts
+++ b/src/handlers/project/project.test.ts
@@ -47,26 +47,38 @@ test("project dev requires an AgentCore project", async () => {
 });
 
 describe("project create", () => {
-  test("creates a Terraform project through --managed-by without CDK installation", async () => {
-    const { path: directory, cleanup } = await inTempDirectory();
-    cleanups.push(cleanup);
-    const { io, core } = await run([
-      "create",
-      "--name",
-      "TerraformProject",
-      "--managed-by",
-      "Terraform",
-      "--skip-git",
-    ]);
+  test.each(["terraform", "Terraform", "TERRAFORM"])(
+    "creates through --iac %s without CDK installation",
+    async (iac) => {
+      const { path: directory, cleanup } = await inTempDirectory();
+      cleanups.push(cleanup);
+      const { io, core } = await run([
+        "create",
+        "--name",
+        "TerraformProject",
+        "--iac",
+        iac,
+        "--skip-git",
+      ]);
 
-    const projectRoot = join(directory, "TerraformProject");
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    expect(spec.managedBy).toBe("Terraform");
-    expect(existsSync(join(projectRoot, "agentcore", "cdk"))).toBe(false);
-    expect(core.projectCommands).toEqual([]);
-    expect(io.stderr()).toContain("agentcore add runtime");
-    expect(io.stderr()).not.toContain("agentcore add harness");
-  });
+      const projectRoot = join(directory, "TerraformProject");
+      const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
+      expect(spec.managedBy).toBe("Terraform");
+      expect(existsSync(join(projectRoot, "agentcore", "cdk"))).toBe(false);
+      expect(existsSync(join(projectRoot, "agentcore", "terraform", "default", "main.tf"))).toBe(
+        true,
+      );
+      const terraformRoot = join(projectRoot, "agentcore", "terraform", "default");
+      expect(await Bun.file(join(terraformRoot, "main.tf")).text()).toContain(
+        "agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=",
+      );
+      expect(existsSync(join(terraformRoot, "modules"))).toBe(false);
+      expect(existsSync(join(terraformRoot, ".terraform"))).toBe(false);
+      expect(core.projectCommands).toEqual([]);
+      expect(io.stderr()).toContain("agentcore add runtime");
+      expect(io.stderr()).not.toContain("agentcore add harness");
+    },
+  );
 
   test("does not apply the CDK node_modules Windows path limit to Terraform creation", async () => {
     const { path, cleanup } = await inTempDirectory();
@@ -75,13 +87,30 @@ describe("project create", () => {
     await mkdir(deep);
     process.chdir(deep);
 
-    await run(["create", "--name", "Deep", "--managed-by", "Terraform", "--skip-git"], {
+    await run(["create", "--name", "Deep", "--iac", "terraform", "--skip-git"], {
       platform: "win32",
     });
 
     expect(await readdir(deep)).toEqual(["Deep"]);
   });
 
+  test.each([undefined, "cdk", "CDK"])("keeps CDK as the default backend (%s)", async (iac) => {
+    const { path: directory, cleanup } = await inTempDirectory();
+    cleanups.push(cleanup);
+    await run([
+      "create",
+      "--name",
+      "DefaultProject",
+      "--skip-install",
+      "--skip-git",
+      ...(iac ? ["--iac", iac] : []),
+    ]);
+    const root = join(directory, "DefaultProject", "agentcore");
+    expect(existsSync(join(root, "cdk", "cdk.json"))).toBe(true);
+    expect(existsSync(join(root, "terraform"))).toBe(false);
+    expect((await Bun.file(join(root, "agentcore.json")).json()).managedBy).toBe("CDK");
+  });
+
   test("--json returns the created project without human success text", async () => {
     const { path: directory, cleanup } = await inTempDirectory();
     cleanups.push(cleanup);
diff --git a/src/handlers/project/types.ts b/src/handlers/project/types.ts
index 0ab639a555..803123aab0 100644
--- a/src/handlers/project/types.ts
+++ b/src/handlers/project/types.ts
@@ -24,6 +24,8 @@ type CreateProjectInputBase = {
   name: string;
   /** Infrastructure backend for the new project. Defaults to CDK. */
   managedBy?: ManagedBy;
+  /** Resolved AWS region used to initialize infrastructure configuration defaults. */
+  region?: string;
   /** Skip installing dependencies (npm install, uv sync). */
   skipInstall?: boolean;
   /** Skip initializing a git repository. */

From e9b99285eab1e634a0f5fa74fa946c792cb42247 Mon Sep 17 00:00:00 2001
From: jariy17 <tjariy+jariy17@users.noreply.github.com>
Date: Thu, 15 Oct 2026 21:53:02 +0000
Subject: [PATCH 3/5] refactor(terraform): share editable root across
 deployment targets

---
 README.md                                     |   7 +
 examples/terraform-poc/.gitignore             |   1 -
 examples/terraform-poc/README.md              |  33 ++--
 .../{ => agentcore}/terraform/.gitignore      |   2 +-
 .../{ => agentcore}/terraform/main.tf         |   2 +-
 .../{ => agentcore}/terraform/outputs.tf      |   0
 .../{ => agentcore}/terraform/providers.tf    |   4 +
 .../{ => agentcore}/terraform/variables.tf    |   0
 src/core/project/backends/terraform.test.ts   | 100 ++++++++++---
 src/core/project/backends/terraform.ts        |  27 ++--
 .../backends/terraform/project.test.ts        |  85 +++++------
 .../project/backends/terraform/project.ts     |  58 +------
 .../project/backends/terraform/state.test.ts  | 131 +++++++++++++---
 src/core/project/backends/terraform/state.ts  | 141 ++++++++++--------
 src/core/project/manager.test.ts              |   9 +-
 src/core/project/manager.tsx                  |   2 +-
 src/core/project/templates/project.ts         |   2 +-
 src/handlers/project/project.test.ts          |  14 +-
 18 files changed, 382 insertions(+), 236 deletions(-)
 rename examples/terraform-poc/{ => agentcore}/terraform/.gitignore (82%)
 rename examples/terraform-poc/{ => agentcore}/terraform/main.tf (83%)
 rename examples/terraform-poc/{ => agentcore}/terraform/outputs.tf (100%)
 rename examples/terraform-poc/{ => agentcore}/terraform/providers.tf (85%)
 rename examples/terraform-poc/{ => agentcore}/terraform/variables.tf (100%)

diff --git a/README.md b/README.md
index 893362b685..731cae5bd1 100644
--- a/README.md
+++ b/README.md
@@ -81,6 +81,13 @@ resources, and `agentcore/cdk/`, the AWS CDK app that deploys them. Deployment t
 and region each — live in `agentcore/aws-targets.json`. Project commands find the project by walking
 up from the current directory.
 
+This branch also includes an experimental Terraform backend, selected with
+`agentcore create --iac terraform`. CDK remains the default. Terraform projects have one editable
+root in `agentcore/terraform/`, shared by every deployment target. The root passes the project
+spec to an application module in the L3 constructs repository; target-specific inputs and local
+state live under `.targets/<target>/`. See the [Terraform PoC example](examples/terraform-poc/)
+for supported resources, direct Terraform commands, and current limitations.
+
 `agentcore dev` runs runtimes locally or deploys harnesses and prints invoke guidance.
 Use `--mode browser` for Agent Inspector, `--skip-deploy` to reuse deployed harnesses,
 and `--agent <name>` to choose an agent in mixed projects.
diff --git a/examples/terraform-poc/.gitignore b/examples/terraform-poc/.gitignore
index 7903bd9b7b..2444ccbe29 100644
--- a/examples/terraform-poc/.gitignore
+++ b/examples/terraform-poc/.gitignore
@@ -1,4 +1,3 @@
-agentcore/terraform/
 agentcore/.cli/
 agentcore/aws-targets.json
 .venv/
diff --git a/examples/terraform-poc/README.md b/examples/terraform-poc/README.md
index a387d33f64..8649e07ca7 100644
--- a/examples/terraform-poc/README.md
+++ b/examples/terraform-poc/README.md
@@ -39,7 +39,7 @@ node "$CLI" create --name MyTerraformProject --template empty --iac terraform
 ```text
 agentcore/
   agentcore.json
-  terraform/default/
+  terraform/
     main.tf
     providers.tf
     variables.tf
@@ -66,27 +66,38 @@ node "$CLI" deploy --region "$AWS_REGION" --json
 node "$CLI" status --region "$AWS_REGION" --json
 ```
 
-Build packages the runtime and Lambda and prepares `agentcore/terraform/default/`. Deploy uses that same directory and writes the account, region, and target variables. The default deployment target is recorded in `agentcore/aws-targets.json`.
+Build packages the runtime and Lambda and prepares `agentcore/terraform/`. Every deployment target uses the same editable root HCL and shared artifact manifest. Deploy writes generated inputs, state, plans, and Terraform initialization data under `agentcore/terraform/.targets/<target>/`. The default deployment target is recorded in `agentcore/aws-targets.json`.
 
-Root HCL and the provider lock file can be version-controlled. Generated ZIPs, artifact manifests, deployment variables, plans, and local state are ignored. Preserve state until teardown completes: it can contain sensitive configuration values and is needed to manage resources. This CLI PoC supports default local state for one operator; remote backends, custom state paths, and CDK-to-Terraform migration are outside its scope.
+Root HCL and the provider lock file can be version-controlled. Generated ZIPs, artifact manifests, deployment variables, plans, and local state are ignored. Preserve state until teardown completes: it can contain sensitive configuration values and is needed to manage resources. This CLI PoC supports local state for one operator; remote backends, custom state paths, and CDK-to-Terraform migration are outside its scope.
 
-Named targets have separate `agentcore/terraform/<target>/` directories. On first use they inherit the default root's HCL; subsequent builds preserve their own edits. A directory containing managed state is bound to its account, region, and target, so changing those values requires a separate target or an explicit migration.
+Named targets share the root `.tf` files, so edits apply to whichever target is planned next. Each target has a separate `.targets/<target>/` directory for deployment inputs and state. State is bound to its account, region, and target; changing those values requires a separate target or an explicit migration. Terraform workspaces remain set to `default`; target isolation comes from the backend state path and `TF_DATA_DIR`.
 
 Deploy also follows the existing CLI setting for enabling CloudWatch Transaction Search. That setup is an account-level telemetry prerequisite, runs outside Terraform, and is not reverted when this example is destroyed. A setup warning must be resolved before treating online evaluation as verified.
 
 ## Change configuration with Terraform directly
 
-After building code artifacts, the generated root works without the CLI:
+After building code artifacts, the shared root works without the CLI. Select a target and configure its local backend explicitly:
 
 ```sh
-cd agentcore/terraform/default
-terraform init
-terraform plan -var="account_id=123456789012" -var="region=us-west-2"
+cd agentcore/terraform
+export TF_WORKSPACE=default
+export TF_DATA_DIR="$PWD/.targets/default/.terraform"
+mkdir -p .targets/default
+terraform init -reconfigure -backend-config="path=$PWD/.targets/default/terraform.tfstate"
+terraform plan -var="account_id=123456789012" -var="region=us-west-2" -var="target_name=default"
 ```
 
-Edit a supported value such as memory retention in `agentcore.json`, then run `terraform plan` again. The module receives the updated object immediately. After reviewing the plan, apply it with Terraform. If CLI deploy has already created deployment variables, the `-var` arguments are unnecessary. Changes to application source still require rebuilding the ZIPs and updating their artifact hashes.
+Replace the example account ID with your AWS account. For a named target, replace `default` in both paths and `target_name` with that target's name. Keep each target's account, region, state path, and initialization directory together. The root's backend defaults to `.targets/default/terraform.tfstate` for a direct default-target initialization.
 
-The checked-in [`terraform/`](terraform/) directory is also a standalone root example. It references the same pinned module from the L3 constructs repository. Supply `artifacts.json` with the ZIP paths and hashes described in the [module README](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/d3ce7229610ce0bb56d581c55f710e220b58faa4/terraform/modules/agentcore-application/README.md).
+After CLI deploy has generated the target's inputs, use its explicit variables file instead:
+
+```sh
+terraform plan -var-file=.targets/default/deployment.tfvars.json
+```
+
+Edit a supported value such as memory retention in `agentcore.json`, then run the same `terraform plan` command again. The module receives the updated object immediately. After reviewing the plan, apply it with the same target inputs. Changes to application source still require rebuilding the ZIPs and updating their artifact hashes.
+
+The checked-in [`agentcore/terraform/`](agentcore/terraform/) directory is the shared root example. It references the same pinned module from the L3 constructs repository. `agentcore build` writes the artifact manifest; callers supplying their own ZIPs can use the manifest contract described in the [module README](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/d3ce7229610ce0bb56d581c55f710e220b58faa4/terraform/modules/agentcore-application/README.md).
 
 The root can pass inline HCL instead of JSON. This allows values from customer resources to enter the `spec` directly, for example `envVars = [{ name = "ORDERS_TABLE", value = aws_dynamodb_table.orders.name }]`. Outputs such as `module.application.runtimes["Agent"].role_name` allow a separate IAM policy to grant that runtime access to the table. Terraform follows these references to order changes.
 
@@ -121,4 +132,4 @@ node "$CLI" deploy --yes --region "$AWS_REGION" --json
 
 Keep the generated directory after a failed apply or teardown so the operation can be retried. Do not edit `managedBy` on an existing CDK deployment to attempt a migration.
 
-The earlier flat-resource Terraform PoC used different resource addresses and directories. This implementation refuses that state rather than silently deploying a second copy; migrating it requires an explicit state migration.
+Earlier Terraform PoCs used flat resources or separate editable roots under `terraform/<target>/`. This implementation refuses those layouts instead of moving state or customer edits automatically. Existing deployments require an explicit migration before using the shared root.
diff --git a/examples/terraform-poc/terraform/.gitignore b/examples/terraform-poc/agentcore/terraform/.gitignore
similarity index 82%
rename from examples/terraform-poc/terraform/.gitignore
rename to examples/terraform-poc/agentcore/terraform/.gitignore
index fbc6763f53..c2d61c8ac3 100644
--- a/examples/terraform-poc/terraform/.gitignore
+++ b/examples/terraform-poc/agentcore/terraform/.gitignore
@@ -1,5 +1,4 @@
 .terraform/
-.terraform.lock.hcl
 *.tfstate
 *.tfstate.*
 *.tfplan
@@ -7,3 +6,4 @@
 artifacts.json
 assets/
 crash.log
+.targets/
diff --git a/examples/terraform-poc/terraform/main.tf b/examples/terraform-poc/agentcore/terraform/main.tf
similarity index 83%
rename from examples/terraform-poc/terraform/main.tf
rename to examples/terraform-poc/agentcore/terraform/main.tf
index 767e3a7e36..18ce1a3a72 100644
--- a/examples/terraform-poc/terraform/main.tf
+++ b/examples/terraform-poc/agentcore/terraform/main.tf
@@ -2,7 +2,7 @@
 module "application" {
   source = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=d3ce7229610ce0bb56d581c55f710e220b58faa4"
 
-  spec        = jsondecode(file("${path.module}/../agentcore/agentcore.json"))
+  spec        = jsondecode(file("${path.module}/../agentcore.json"))
   target_name = var.target_name
   account_id  = var.account_id
   region      = var.region
diff --git a/examples/terraform-poc/terraform/outputs.tf b/examples/terraform-poc/agentcore/terraform/outputs.tf
similarity index 100%
rename from examples/terraform-poc/terraform/outputs.tf
rename to examples/terraform-poc/agentcore/terraform/outputs.tf
diff --git a/examples/terraform-poc/terraform/providers.tf b/examples/terraform-poc/agentcore/terraform/providers.tf
similarity index 85%
rename from examples/terraform-poc/terraform/providers.tf
rename to examples/terraform-poc/agentcore/terraform/providers.tf
index ecbdf1b154..2f7d9655a5 100644
--- a/examples/terraform-poc/terraform/providers.tf
+++ b/examples/terraform-poc/agentcore/terraform/providers.tf
@@ -1,4 +1,8 @@
 terraform {
+  backend "local" {
+    path = ".targets/default/terraform.tfstate"
+  }
+
   required_version = ">= 1.12.0, < 2.0.0"
   required_providers {
     awscc = {
diff --git a/examples/terraform-poc/terraform/variables.tf b/examples/terraform-poc/agentcore/terraform/variables.tf
similarity index 100%
rename from examples/terraform-poc/terraform/variables.tf
rename to examples/terraform-poc/agentcore/terraform/variables.tf
diff --git a/src/core/project/backends/terraform.test.ts b/src/core/project/backends/terraform.test.ts
index 040a9e65e9..fb74baed29 100644
--- a/src/core/project/backends/terraform.test.ts
+++ b/src/core/project/backends/terraform.test.ts
@@ -74,7 +74,7 @@ describe("Terraform lifecycle", () => {
     expect(commands.map((command) => command[1])).toEqual(["init", "validate"]);
     expect(commands[0]).toContain("-backend=false");
     const root = new TerraformState(p).directory;
-    expect(root).toBe(join(p.rootPath, "agentcore", "terraform", "default"));
+    expect(root).toBe(join(p.rootPath, "agentcore", "terraform"));
     expect(existsSync(join(root, "main.tf"))).toBe(true);
     expect(existsSync(join(root, "deployment.auto.tfvars.json"))).toBe(false);
     expect(await readFile(join(root, "variables.tf"), "utf8")).not.toContain("000000000000");
@@ -87,7 +87,7 @@ describe("Terraform lifecycle", () => {
       calls.push({ command, options });
       if (command[1] === "apply") {
         await writeFile(
-          join(options.cwd, "terraform.tfstate"),
+          new TerraformState(p, TARGET).statePath,
           JSON.stringify({
             resources: [{ mode: "managed", module: "module.application" }],
             outputs: {
@@ -105,9 +105,16 @@ describe("Terraform lifecycle", () => {
     const b = backend({ runner });
     const result = await drain(b.deploy(p, input));
     expect(calls.map(({ command }) => command[1])).toEqual(["init", "validate", "plan", "apply"]);
-    expect(calls.at(-1)!.command.at(-1)).toBe("deployment.tfplan");
-    expect(calls[2]!.command).toContain("-out=deployment.tfplan");
-    expect(calls[2]!.command).toContain("-var-file=deployment.auto.tfvars.json");
+    const state = new TerraformState(p, TARGET);
+    expect(calls.at(-1)!.command.at(-1)).toBe(state.planPath);
+    expect(calls[2]!.command).toContain(`-out=${state.planPath}`);
+    expect(calls[2]!.command).toContain(`-var-file=${state.variablesPath}`);
+    expect(calls[0]!.command).toContain("-reconfigure");
+    expect(calls[0]!.command).toContain(`-backend-config=path=${state.statePath}`);
+    expect(calls.every(({ options }) => options.env?.TF_DATA_DIR === state.dataDirectory)).toBe(
+      true,
+    );
+    expect(calls.every(({ options }) => options.env?.TF_WORKSPACE === "default")).toBe(true);
     expect(calls.every(({ options }) => options.env?.AWS_SESSION_TOKEN === "test-session")).toBe(
       true,
     );
@@ -138,12 +145,12 @@ describe("Terraform lifecycle", () => {
     async (failure) => {
       const p = await project();
       const state = new TerraformState(p, TARGET);
-      await mkdir(state.directory, { recursive: true });
+      await mkdir(state.targetDirectory, { recursive: true });
       const stateText = JSON.stringify({
         resources: [{ mode: "managed", module: "module.application" }],
         outputs: { deployment_target: { value: TARGET } },
       });
-      await writeFile(join(state.directory, "terraform.tfstate"), stateText);
+      await writeFile(state.statePath, stateText);
       const calls: string[] = [];
       const b = backend({
         runner: async (command) => {
@@ -152,7 +159,7 @@ describe("Terraform lifecycle", () => {
         },
       });
       await expect(drain(b.deploy(p, input))).rejects.toThrow("simulated failure");
-      expect(await readFile(join(state.directory, "terraform.tfstate"), "utf8")).toBe(stateText);
+      expect(await readFile(state.statePath, "utf8")).toBe(stateText);
       expect(existsSync(join(state.directory, ".agentcore-operation.lock"))).toBe(false);
       expect(calls.at(-1)).toBe(failure);
     },
@@ -162,10 +169,10 @@ describe("Terraform lifecycle", () => {
     const p = await project();
     p.spec.memories = [];
     const state = new TerraformState(p, TARGET);
-    await mkdir(state.directory, { recursive: true });
+    await mkdir(state.targetDirectory, { recursive: true });
     await state.bind(TARGET);
     await writeFile(
-      join(state.directory, "terraform.tfstate"),
+      state.statePath,
       JSON.stringify({
         resources: [{ mode: "managed", module: "module.application" }],
         outputs: {},
@@ -208,9 +215,9 @@ describe("Terraform lifecycle", () => {
   test("refuses to reuse target state in another region and excludes removed declarations", async () => {
     const p = await project();
     const state = new TerraformState(p, TARGET);
-    await mkdir(state.directory, { recursive: true });
+    await mkdir(state.targetDirectory, { recursive: true });
     await writeFile(
-      join(state.directory, "terraform.tfstate"),
+      state.statePath,
       JSON.stringify({
         outputs: {
           deployment_target: { value: TARGET },
@@ -226,7 +233,7 @@ describe("Terraform lifecycle", () => {
     expect(await b.resolveProjectResources(p, input)).toEqual([]);
   });
 
-  test("build and deploy share the editable default root without resetting target inputs", async () => {
+  test("build and deploy share the editable root without resetting target inputs", async () => {
     const p = await project();
     const directories: string[] = [];
     const b = backend({
@@ -238,22 +245,77 @@ describe("Terraform lifecycle", () => {
     const root = new TerraformState(p).directory;
     await writeFile(join(root, "custom.tf"), "# customer resources\n");
     await drain(b.deploy(p, input));
-    const targetInputs = await readFile(join(root, "deployment.auto.tfvars.json"), "utf8");
+    const targetInputs = await readFile(new TerraformState(p, TARGET).variablesPath, "utf8");
     await drain(b.build(p));
     expect(new Set(directories)).toEqual(new Set([root]));
-    expect(await readFile(join(root, "deployment.auto.tfvars.json"), "utf8")).toBe(targetInputs);
+    expect(await readFile(new TerraformState(p, TARGET).variablesPath, "utf8")).toBe(targetInputs);
     expect(await readFile(join(root, "custom.tf"), "utf8")).toBe("# customer resources\n");
   });
 
+  test("deploying different targets reads the latest shared root and keeps both states separate", async () => {
+    const p = await project();
+    const calls: { command: string[]; options: RunProcessOptions; source: string }[] = [];
+    const production = { ...TARGET, name: "production", region: "us-west-2" } as const;
+    const b = backend({
+      runner: async (command, options) => {
+        calls.push({
+          command,
+          options,
+          source: await readFile(join(options.cwd, "custom.tf"), "utf8"),
+        });
+        if (command[1] === "apply") {
+          const name = options.env!.TF_DATA_DIR!.includes("production") ? "production" : "default";
+          const target = name === "production" ? production : TARGET;
+          await writeFile(
+            new TerraformState(p, target).statePath,
+            JSON.stringify({
+              resources: [{ mode: "managed", module: "module.application" }],
+              outputs: {
+                deployment_target: { value: target },
+                project_resources: {
+                  value: [{ resourceType: "memory", name: "memory", id: `${name}-memory` }],
+                },
+              },
+            }),
+          );
+        }
+      },
+    });
+    const root = new TerraformState(p).directory;
+    await mkdir(root, { recursive: true });
+    await writeFile(join(root, "custom.tf"), "# first shared edit\n");
+    await drain(b.deploy(p, input));
+    const defaultState = await readFile(new TerraformState(p, TARGET).statePath, "utf8");
+    await writeFile(join(root, "custom.tf"), "# latest shared edit\n");
+    await drain(b.deploy(p, { ...input, target: production }));
+    expect(new Set(calls.map(({ options }) => options.cwd))).toEqual(new Set([root]));
+    expect(calls.slice(4).every(({ source }) => source === "# latest shared edit\n")).toBe(true);
+    expect(await readFile(new TerraformState(p, TARGET).statePath, "utf8")).toBe(defaultState);
+    expect((await b.resolveProjectResources(p, input))[0]).toMatchObject({ id: "default-memory" });
+    expect((await b.resolveProjectResources(p, { ...input, target: production }))[0]).toMatchObject(
+      { id: "production-memory" },
+    );
+    for (const target of [TARGET, production]) {
+      const state = new TerraformState(p, target);
+      expect(
+        calls.some(({ command }) => command.includes(`-var-file=${state.variablesPath}`)),
+      ).toBe(true);
+      expect(
+        calls.some(({ command }) => command.includes(`-backend-config=path=${state.statePath}`)),
+      ).toBe(true);
+      expect(existsSync(join(state.targetDirectory, "main.tf"))).toBe(false);
+    }
+  });
+
   test("rejects a remote backend after init before planning or applying", async () => {
     const p = await project();
     const calls: string[] = [];
     const b = backend({
       runner: async (command, options) => {
         calls.push(command[1]!);
-        await mkdir(join(options.cwd, ".terraform"), { recursive: true });
+        await mkdir(options.env!.TF_DATA_DIR!, { recursive: true });
         await writeFile(
-          join(options.cwd, ".terraform", "terraform.tfstate"),
+          join(options.env!.TF_DATA_DIR!, "terraform.tfstate"),
           JSON.stringify({ backend: { type: "s3" } }),
         );
       },
@@ -267,7 +329,9 @@ describe("Terraform lifecycle", () => {
     const state = new TerraformState(p, TARGET);
     const unlock = await state.lock();
     try {
-      await expect(drain(backend().deploy(p, input))).rejects.toThrow("Another operation owns");
+      await expect(
+        drain(backend().deploy(p, { ...input, target: { ...TARGET, name: "production" } })),
+      ).rejects.toThrow("Another operation owns");
     } finally {
       await unlock();
     }
diff --git a/src/core/project/backends/terraform.ts b/src/core/project/backends/terraform.ts
index 1956c140ad..f9b975bab3 100644
--- a/src/core/project/backends/terraform.ts
+++ b/src/core/project/backends/terraform.ts
@@ -1,5 +1,4 @@
 import { rm } from "node:fs/promises";
-import { join } from "node:path";
 import { ProjectStateError } from "../../../errors";
 import type {
   DeployResult,
@@ -17,7 +16,7 @@ import {
   type ReadWriteJson,
 } from "../../../io";
 import type { Logger } from "../../../logging";
-import { DEFAULT_TARGET_NAME, type AwsDeploymentTarget } from "../../../projectSchemas/aws-targets";
+import type { AwsDeploymentTarget } from "../../../projectSchemas/aws-targets";
 import { withOutputEvents } from "../events";
 import type { TransactionSearchEnabler } from "./cdk";
 import { readDeployedState, stackReferenceOf } from "./cdk/deployedState";
@@ -116,10 +115,6 @@ export class TerraformBackend implements ProjectBackend {
     try {
       await state.assertTarget(target);
       await this.writer.assertCompatible(state.directory);
-      await this.writer.inheritRoot(
-        state.directory,
-        new TerraformState(project, DEFAULT_TARGET_NAME).directory,
-      );
       const tearingDown =
         declaredResources(project).length === 0 && (await state.hasApplicationResources());
       if (tearingDown) {
@@ -141,20 +136,30 @@ export class TerraformBackend implements ProjectBackend {
       await state.bind(target);
       const env = this.environment(state, target, await credentials());
       yield { type: "step", message: "Initializing and validating Terraform" };
-      yield* this.execute(["init", "-input=false", "-no-color"], state, env);
+      yield* this.execute(
+        [
+          "init",
+          "-reconfigure",
+          `-backend-config=path=${state.statePath}`,
+          "-input=false",
+          "-no-color",
+        ],
+        state,
+        env,
+      );
       await state.assertLocalBackend();
       yield* this.execute(["validate", "-no-color"], state, env);
       yield { type: "step", message: "Planning Terraform deployment" };
       // Never reuse a plan from a prior operation, particularly after a failed apply.
-      const plan = "deployment.tfplan";
-      await rm(join(state.directory, plan), { force: true });
+      const plan = state.planPath;
+      await rm(plan, { force: true });
       yield* this.execute(
         [
           "plan",
           "-input=false",
           "-no-color",
           "-lock-timeout=60s",
-          "-var-file=deployment.auto.tfvars.json",
+          `-var-file=${state.variablesPath}`,
           `-out=${plan}`,
         ],
         state,
@@ -344,7 +349,7 @@ export class TerraformBackend implements ProjectBackend {
       ...env,
       TF_IN_AUTOMATION: "1",
       TF_INPUT: "0",
-      TF_DATA_DIR: join(state.directory, ".terraform"),
+      TF_DATA_DIR: state.dataDirectory,
       TF_WORKSPACE: "default",
     };
   }
diff --git a/src/core/project/backends/terraform/project.test.ts b/src/core/project/backends/terraform/project.test.ts
index ef27e5b7ac..911daccc9c 100644
--- a/src/core/project/backends/terraform/project.test.ts
+++ b/src/core/project/backends/terraform/project.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, expect, test } from "bun:test";
 import { existsSync } from "node:fs";
-import { mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { TerraformProjectWriter } from "./project";
@@ -18,9 +18,6 @@ async function directory() {
   return path;
 }
 const emptyAssets = { runtimes: {}, gatewayTargets: {} };
-const modulePath = (root: string, name = "main.tf") =>
-  join(root, "modules", "agentcore-application", name);
-
 test("scaffolds immediately with a required account and no placeholder deployment inputs", async () => {
   const root = await directory();
   await new TerraformProjectWriter().scaffold(root, "eu-west-1");
@@ -35,24 +32,26 @@ test("scaffolds immediately with a required account and no placeholder deploymen
   );
 });
 
-test("a named target inherits customer Terraform source without copying state or target inputs", async () => {
-  const parent = await directory();
-  const original = join(parent, "default");
-  const named = join(parent, "production");
+test("all targets use the same customer source and keep independent explicit inputs", async () => {
+  const root = await directory();
   const writer = new TerraformProjectWriter();
-  await writer.scaffold(original);
-  await writeFile(join(original, "custom.tf"), "# custom resource\n");
-  await writeFile(join(original, "custom.tf.json"), '{"resource":{}}\n');
-  await writeFile(join(original, "terraform.tfstate"), '{"resources":[]}\n');
-  await writeFile(join(original, "deployment.auto.tfvars.json"), '{"account_id":"111122223333"}\n');
-  await writer.inheritRoot(named, original);
-  await writer.write(named, { ...target, name: "production" }, emptyAssets);
-  expect(await readFile(join(named, "custom.tf"), "utf8")).toBe("# custom resource\n");
-  expect(await readFile(join(named, "custom.tf.json"), "utf8")).toBe('{"resource":{}}\n');
-  expect(existsSync(join(named, "terraform.tfstate"))).toBe(false);
-  expect(
-    JSON.parse(await readFile(join(named, "deployment.auto.tfvars.json"), "utf8")).target_name,
-  ).toBe("production");
+  await writer.write(root, target, emptyAssets);
+  await writeFile(join(root, "main.tf"), "# shared application edit\n");
+  await writeFile(join(root, "custom.tf"), "# shared customer resource\n");
+  const production = { ...target, name: "production", region: "us-west-2" } as const;
+  await writer.write(root, production, emptyAssets);
+  expect(await readFile(join(root, "main.tf"), "utf8")).toBe("# shared application edit\n");
+  expect(await readFile(join(root, "custom.tf"), "utf8")).toBe("# shared customer resource\n");
+  for (const selected of [target, production]) {
+    const directory = join(root, ".targets", selected.name);
+    expect(JSON.parse(await readFile(join(directory, "deployment.tfvars.json"), "utf8"))).toEqual({
+      target_name: selected.name,
+      account_id: selected.account,
+      region: selected.region,
+    });
+    expect(existsSync(join(directory, "main.tf"))).toBe(false);
+  }
+  expect(existsSync(join(root, "deployment.auto.tfvars.json"))).toBe(false);
 });
 
 test("scaffolds native HCL with a direct project file reference and portable artifact manifest", async () => {
@@ -67,7 +66,7 @@ test("scaffolds native HCL with a direct project file reference and portable art
   );
   expect(existsSync(join(root, "modules"))).toBe(false);
   expect(existsSync(join(root, ".terraform"))).toBe(false);
-  expect(main).toContain('jsondecode(file("${path.module}/../../agentcore.json"))');
+  expect(main).toContain('jsondecode(file("${path.module}/../agentcore.json"))');
   expect(main).toContain('jsondecode(file("${path.module}/artifacts.json"))');
   expect(existsSync(join(root, "main.tf.json"))).toBe(false);
   expect(JSON.parse(await readFile(join(root, "artifacts.json"), "utf8")).runtimes.Agent.path).toBe(
@@ -80,8 +79,10 @@ test("scaffolds native HCL with a direct project file reference and portable art
     "module.application.project_resources",
   );
   expect((await readdir(root, { recursive: true })).sort()).toEqual([
+    ".targets",
+    ".targets/test",
+    ".targets/test/deployment.tfvars.json",
     "artifacts.json",
-    "deployment.auto.tfvars.json",
     "main.tf",
     "outputs.tf",
     "providers.tf",
@@ -117,8 +118,8 @@ test("preserves customer root configuration and Terraform state, plans, and prov
     "outputs.tf": "# custom outputs\n",
     "custom.tf": "# custom extra resources\n",
     ".terraform.lock.hcl": "# selected provider hashes\n",
-    "deployment.tfplan": "saved plan",
-    "terraform.tfstate": JSON.stringify({
+    ".targets/test/deployment.tfplan": "saved plan",
+    ".targets/test/terraform.tfstate": JSON.stringify({
       resources: [{ mode: "managed", type: "aws_s3_bucket", name: "customer" }],
     }),
   };
@@ -129,31 +130,19 @@ test("preserves customer root configuration and Terraform state, plans, and prov
   }
 });
 
-test("inherits local customer modules without copying Terraform working files", async () => {
-  const parent = await directory();
-  const original = join(parent, "default");
-  const named = join(parent, "production");
-  const writer = new TerraformProjectWriter();
-  await writer.scaffold(original);
-  await mkdir(modulePath(original, ".terraform"), { recursive: true });
-  await writeFile(modulePath(original), "# customer module\n");
-  await writeFile(modulePath(original, ".terraform/provider"), "binary");
-  await writeFile(modulePath(original, "terraform.tfstate"), "{}");
-  await writer.inheritRoot(named, original);
-  expect(await readdir(modulePath(named, ""))).toEqual(["main.tf"]);
-  expect(await readFile(modulePath(named), "utf8")).toBe("# customer module\n");
-});
-
-test("refuses to follow local module symlinks during target inheritance", async () => {
-  const parent = await directory();
-  const outside = await directory();
-  const original = join(parent, "default");
+test("local customer modules remain shared without copying source into targets", async () => {
+  const root = await directory();
   const writer = new TerraformProjectWriter();
-  await writer.scaffold(original);
-  await symlink(outside, join(original, "modules"));
-  await expect(writer.inheritRoot(join(parent, "production"), original)).rejects.toThrow(
-    "symlinked",
+  await writer.scaffold(root);
+  await mkdir(join(root, "modules", "custom"), { recursive: true });
+  await writeFile(join(root, "modules", "custom", "main.tf"), "# custom module\n");
+  await writer.write(root, target, emptyAssets);
+  await writer.write(root, { ...target, name: "production" }, emptyAssets);
+  expect(await readFile(join(root, "modules", "custom", "main.tf"), "utf8")).toBe(
+    "# custom module\n",
   );
+  expect(existsSync(join(root, ".targets", target.name, "modules"))).toBe(false);
+  expect(existsSync(join(root, ".targets", "production", "modules"))).toBe(false);
 });
 
 test.each(["main.tf.json", "terraform.tfstate", "terraform.tfstate.backup"])(
diff --git a/src/core/project/backends/terraform/project.ts b/src/core/project/backends/terraform/project.ts
index 02e75942d1..49634f7a8f 100644
--- a/src/core/project/backends/terraform/project.ts
+++ b/src/core/project/backends/terraform/project.ts
@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { cp, lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, join, relative } from "node:path";
 import { ProjectStateError } from "../../../../errors";
 import { atomicWrite } from "../../../../io";
@@ -10,7 +10,7 @@ const ROOT_FILES: Record<string, string> = {
   "main.tf": `# This root is yours to edit. The CLI refreshes artifacts.json and target inputs.
 module "application" {
   source      = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=d3ce7229610ce0bb56d581c55f710e220b58faa4"
-  spec        = jsondecode(file("\${path.module}/../../agentcore.json"))
+  spec        = jsondecode(file("\${path.module}/../agentcore.json"))
   target_name = var.target_name
   account_id  = var.account_id
   region      = var.region
@@ -19,6 +19,9 @@ module "application" {
 `,
   "providers.tf": `terraform {
   required_version = ">= 1.12.0, < 2.0.0"
+  backend "local" {
+    path = ".targets/default/terraform.tfstate"
+  }
   required_providers {
     awscc = {
       source  = "hashicorp/awscc"
@@ -127,53 +130,6 @@ export class TerraformProjectWriter {
     );
   }
 
-  /** A new named target starts from the customer's default root, without copying its state. */
-  async inheritRoot(directory: string, defaultDirectory: string): Promise<void> {
-    if (directory === defaultDirectory || existsSync(join(directory, "main.tf"))) return;
-    if (!existsSync(join(defaultDirectory, "main.tf"))) await this.scaffold(defaultDirectory);
-    await this.assertCompatible(defaultDirectory);
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    // Only customer-authored modules live here; downloaded modules stay in .terraform.
-    const localModules = join(defaultDirectory, "modules");
-    if (existsSync(localModules) && !existsSync(join(directory, "modules"))) {
-      await cp(localModules, join(directory, "modules"), {
-        recursive: true,
-        filter: async (path) => {
-          const parts = relative(defaultDirectory, path).split(/[\\/]/);
-          if (
-            parts.some(
-              (part) =>
-                part === ".terraform" ||
-                part === ".git" ||
-                /\.tfstate(?:\.|$)/.test(part) ||
-                part.endsWith(".tfplan"),
-            )
-          )
-            return false;
-          if ((await lstat(path)).isSymbolicLink()) {
-            throw new ProjectStateError(
-              "Cannot inherit a symlinked local Terraform module. Copy its source into the new target manually.",
-            );
-          }
-          return true;
-        },
-      });
-    }
-    for (const entry of await readdir(defaultDirectory, { withFileTypes: true })) {
-      if (
-        entry.isFile() &&
-        (entry.name.endsWith(".tf") ||
-          entry.name.endsWith(".tf.json") ||
-          entry.name === ".terraform.lock.hcl")
-      ) {
-        await this.writeIfMissing(
-          join(directory, entry.name),
-          await readFile(join(defaultDirectory, entry.name), "utf8"),
-        );
-      }
-    }
-  }
-
   async assertCompatible(directory: string): Promise<void> {
     if (existsSync(join(directory, "main.tf.json"))) {
       throw new ProjectStateError(
@@ -227,8 +183,10 @@ export class TerraformProjectWriter {
       { mode: 0o600 },
     );
     if (target) {
+      const targetDirectory = join(directory, ".targets", target.name);
+      await mkdir(targetDirectory, { recursive: true, mode: 0o700 });
       await atomicWrite(
-        join(directory, "deployment.auto.tfvars.json"),
+        join(targetDirectory, "deployment.tfvars.json"),
         `${JSON.stringify({ target_name: target.name, account_id: target.account, region: target.region }, null, 2)}\n`,
         { mode: 0o600 },
       );
diff --git a/src/core/project/backends/terraform/state.test.ts b/src/core/project/backends/terraform/state.test.ts
index 4c99aa3a3b..bf615e1359 100644
--- a/src/core/project/backends/terraform/state.test.ts
+++ b/src/core/project/backends/terraform/state.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, expect, test } from "bun:test";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import type { Project } from "../../../../handlers/project/types";
 import { ProjectSpecSchema } from "../../../../projectSchemas/project";
 import { TerraformState } from "./state";
@@ -20,7 +20,7 @@ async function fixture() {
     spec: ProjectSpecSchema.parse({ name: "Example", version: 2, managedBy: "Terraform" }),
   };
   const state = new TerraformState(project);
-  await mkdir(state.directory, { recursive: true });
+  await mkdir(state.targetDirectory, { recursive: true });
   return { project, state };
 }
 const resource = { mode: "managed", module: "module.application" };
@@ -39,16 +39,16 @@ test.each([
   await state.bind(target);
   await expect(state.assertTarget(replacement)).rejects.toThrow("different target");
   expect(
-    JSON.parse(await readFile(join(state.directory, ".agentcore-target.json"), "utf8")),
+    JSON.parse(await readFile(join(state.targetDirectory, ".agentcore-target.json"), "utf8")),
   ).toEqual(target);
 });
 
 test("adopts matching standalone Terraform state through its deployment_target output", async () => {
   const { state } = await fixture();
   const text = serialize(target);
-  await writeFile(join(state.directory, "terraform.tfstate"), text);
+  await writeFile(state.statePath, text);
   await state.bind(target);
-  expect(await readFile(join(state.directory, "terraform.tfstate"), "utf8")).toBe(text);
+  expect(await readFile(state.statePath, "utf8")).toBe(text);
   await expect(state.assertTarget({ ...target, region: "us-west-2" })).rejects.toThrow(
     "different target",
   );
@@ -56,13 +56,13 @@ test("adopts matching standalone Terraform state through its deployment_target o
 
 test("refuses partial standalone state without an identity", async () => {
   const { state } = await fixture();
-  await writeFile(join(state.directory, "terraform.tfstate"), serialize());
+  await writeFile(state.statePath, serialize());
   await expect(state.bind(target)).rejects.toThrow("no deployment target identity");
 });
 
 test("refuses to start fresh when managed backup state exists but current state is missing", async () => {
   const { state } = await fixture();
-  await writeFile(join(state.directory, "terraform.tfstate.backup"), serialize(target));
+  await writeFile(`${state.statePath}.backup`, serialize(target));
   await expect(state.bind(target)).rejects.toThrow("current Terraform state is missing");
 });
 
@@ -70,7 +70,7 @@ test.each(["build", "default-111122223333-us-east-1", "."])(
   "refuses managed state in the earlier %s directory",
   async (legacyName) => {
     const { state } = await fixture();
-    const legacy = join(dirname(state.directory), legacyName);
+    const legacy = join(state.directory, legacyName);
     await mkdir(legacy, { recursive: true });
     await writeFile(join(legacy, "terraform.tfstate"), serialize());
     await expect(state.assertTarget(target)).rejects.toThrow("earlier state directory");
@@ -82,8 +82,8 @@ test.each(["build", "test-111122223333-us-east-1"])(
   async (name) => {
     const { project, state } = await fixture();
     const other = new TerraformState(project, name);
-    await mkdir(other.directory, { recursive: true });
-    await writeFile(join(other.directory, "terraform.tfstate"), serialize({ ...target, name }));
+    await mkdir(other.targetDirectory, { recursive: true });
+    await writeFile(other.statePath, serialize({ ...target, name }));
     await state.assertTarget(target);
   },
 );
@@ -95,21 +95,18 @@ test.each([
   { type: "local", config: { workspace_dir: "../other-workspace" } },
 ])("rejects unsupported initialized backend %j", async (backend) => {
   const { state } = await fixture();
-  await mkdir(join(state.directory, ".terraform"));
-  await writeFile(
-    join(state.directory, ".terraform", "terraform.tfstate"),
-    JSON.stringify({ backend }),
-  );
+  await mkdir(state.dataDirectory, { recursive: true });
+  await writeFile(join(state.dataDirectory, "terraform.tfstate"), JSON.stringify({ backend }));
   await expect(state.assertTarget(target)).rejects.toThrow("require local state");
 });
 
-test("accepts the default local state path", async () => {
+test("accepts the selected target local state path", async () => {
   const { state } = await fixture();
-  await mkdir(join(state.directory, ".terraform"));
+  await mkdir(state.dataDirectory, { recursive: true });
   await writeFile(
-    join(state.directory, ".terraform", "terraform.tfstate"),
+    join(state.dataDirectory, "terraform.tfstate"),
     JSON.stringify({
-      backend: { type: "local", config: { path: join(state.directory, "terraform.tfstate") } },
+      backend: { type: "local", config: { path: state.statePath } },
     }),
   );
   await state.assertTarget(target);
@@ -118,8 +115,102 @@ test("accepts the default local state path", async () => {
 test("application teardown ignores customer resources outside the module", async () => {
   const { state } = await fixture();
   await writeFile(
-    join(state.directory, "terraform.tfstate"),
+    state.statePath,
     JSON.stringify({ resources: [{ mode: "managed", type: "aws_s3_bucket", name: "customer" }] }),
   );
   expect(await state.hasApplicationResources()).toBe(false);
 });
+
+test("named targets share source but isolate state, variables, plans, and provider data", async () => {
+  const { project, state } = await fixture();
+  const production = new TerraformState(project, "production");
+  expect(state.directory).toBe(join(project.rootPath, "agentcore", "terraform"));
+  expect(production.directory).toBe(state.directory);
+  for (const key of [
+    "targetDirectory",
+    "statePath",
+    "variablesPath",
+    "planPath",
+    "dataDirectory",
+  ] as const) {
+    expect(production[key]).not.toBe(state[key]);
+  }
+  await state.bind(target);
+  await mkdir(production.targetDirectory, { recursive: true });
+  await production.bind({ ...target, name: "production", region: "us-west-2" });
+  await state.assertTarget(target);
+  await production.assertTarget({ ...target, name: "production", region: "us-west-2" });
+});
+
+test("one source operation lock excludes every target", async () => {
+  const { project, state } = await fixture();
+  const production = new TerraformState(project, "production");
+  const unlock = await state.lock();
+  try {
+    await expect(production.lock()).rejects.toThrow("Another operation owns");
+  } finally {
+    await unlock();
+  }
+  const unlockProduction = await production.lock();
+  await unlockProduction();
+});
+
+test.each(["default", "production", "modules", "assets"])(
+  "refuses an earlier editable root at %s even without state",
+  async (name) => {
+    const { state } = await fixture();
+    const legacy = join(state.directory, name);
+    await mkdir(legacy, { recursive: true });
+    const customerSource = "# customer changes must survive migration\n";
+    await writeFile(join(legacy, "main.tf"), customerSource);
+    await writeFile(
+      join(legacy, "artifacts.json"),
+      JSON.stringify({ runtimes: {}, gatewayTargets: {} }),
+    );
+    await expect(state.assertTarget(target)).rejects.toThrow("migration");
+    expect(await readFile(join(legacy, "main.tf"), "utf8")).toBe(customerSource);
+  },
+);
+
+test("allows ordinary customer module directories alongside the shared root", async () => {
+  const { state } = await fixture();
+  const module = join(state.directory, "custom-module");
+  await mkdir(module);
+  await writeFile(join(module, "main.tf"), "# custom resource module\n");
+  await state.assertTarget(target);
+  expect(await readFile(join(module, "main.tf"), "utf8")).toBe("# custom resource module\n");
+});
+
+test.each([
+  { type: "s3" },
+  { type: "cloud" },
+  { type: "local", config: { path: "custom.tfstate" } },
+  { type: "local", config: { path: "../outside.tfstate" } },
+  { type: "local", config: { path: ".targets/default/nested/terraform.tfstate" } },
+  {
+    type: "local",
+    config: { path: ".targets/default/terraform.tfstate", workspace_dir: "../workspaces" },
+  },
+])("refuses unsupported backend metadata from plain Terraform init: %j", async (backend) => {
+  const { state } = await fixture();
+  const dataDirectory = join(state.directory, ".terraform");
+  await mkdir(dataDirectory);
+  await writeFile(join(dataDirectory, "terraform.tfstate"), JSON.stringify({ backend }));
+  await expect(state.assertTarget(target)).rejects.toThrow("require local state");
+});
+
+test.each(["default", "production", "modules", "assets"])(
+  "accepts canonical %s state metadata from plain Terraform init",
+  async (name) => {
+    const { state } = await fixture();
+    const dataDirectory = join(state.directory, ".terraform");
+    await mkdir(dataDirectory);
+    await writeFile(
+      join(dataDirectory, "terraform.tfstate"),
+      JSON.stringify({
+        backend: { type: "local", config: { path: `.targets/${name}/terraform.tfstate` } },
+      }),
+    );
+    await state.assertTarget(target);
+  },
+);
diff --git a/src/core/project/backends/terraform/state.ts b/src/core/project/backends/terraform/state.ts
index c81b135b6b..c4d1f3aa77 100644
--- a/src/core/project/backends/terraform/state.ts
+++ b/src/core/project/backends/terraform/state.ts
@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { mkdir, open, readFile, readdir, rm } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { z } from "zod";
 import { ProjectStateError } from "../../../../errors";
 import type { Project } from "../../../../handlers/project/types";
@@ -43,53 +43,53 @@ const stateSchema = z.object({
 /** A local Terraform state belongs to exactly one project, target, account, and region. */
 export class TerraformState {
   readonly directory: string;
+  readonly targetDirectory: string;
+  readonly dataDirectory: string;
+  readonly statePath: string;
+  readonly variablesPath: string;
+  readonly planPath: string;
 
   constructor(project: Project, target: AwsDeploymentTarget | string = DEFAULT_TARGET_NAME) {
     const key = typeof target === "string" ? target : target.name;
     if (!/^[a-zA-Z0-9_-]+$/.test(key)) {
       throw new ProjectStateError("Invalid Terraform target directory");
     }
-    this.directory = join(project.rootPath, "agentcore", "terraform", key);
+    this.directory = join(project.rootPath, "agentcore", "terraform");
+    this.targetDirectory = join(this.directory, ".targets", key);
+    this.dataDirectory = join(this.targetDirectory, ".terraform");
+    this.statePath = join(this.targetDirectory, "terraform.tfstate");
+    this.variablesPath = join(this.targetDirectory, "deployment.tfvars.json");
+    this.planPath = join(this.targetDirectory, "deployment.tfplan");
   }
 
-  /** Never silently start a second state beside the earlier PoC directory layout. */
+  /** Preserve earlier target roots and state instead of silently creating another deployment. */
   async assertNoLegacyState(): Promise<void> {
-    const root = dirname(this.directory);
-    if (!existsSync(root)) return;
-    const legacy = [
-      root,
-      ...(await readdir(root, { withFileTypes: true }))
-        .filter(
-          (entry) =>
-            entry.isDirectory() && (entry.name === "build" || /-\d{12}-[a-z]+-/.test(entry.name)),
-        )
-        .map((entry) => join(root, entry.name)),
-    ];
-    directories: for (const path of legacy) {
-      if (path === this.directory) continue;
-      const binding = await this.readOptional(join(path, ".agentcore-target.json"));
-      const parsedBinding =
-        binding === undefined
-          ? undefined
-          : AwsDeploymentTargetSchema.safeParse(JSON.parse(binding));
-      if (
-        path !== root &&
-        parsedBinding?.success &&
-        parsedBinding.data.name === basename(path) &&
-        existsSync(join(path, "main.tf"))
-      ) {
-        continue;
-      }
-      for (const name of ["terraform.tfstate", "terraform.tfstate.backup"]) {
-        const text = await this.readOptional(join(path, name));
-        if (text === undefined) continue;
-        const parsed = stateSchema.parse(JSON.parse(text));
-        const identity = AwsDeploymentTargetSchema.safeParse(
-          parsed.outputs.deployment_target?.value,
+    if (!existsSync(this.directory)) return;
+    const children = (await readdir(this.directory, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory() && ![".targets", ".terraform"].includes(entry.name))
+      .map((entry) => join(this.directory, entry.name));
+    for (const path of [this.directory, ...children]) {
+      const files = path === this.directory ? [] : await readdir(path);
+      const legacyRoot =
+        files.some((name) => name.endsWith(".tf") || name.endsWith(".tf.json")) &&
+        (files.some((name) =>
+          ["artifacts.json", "deployment.auto.tfvars.json", ".agentcore-target.json"].includes(
+            name,
+          ),
+        ) ||
+          (await this.readOptional(join(path, "main.tf")))?.includes("/../../agentcore.json"));
+      if (legacyRoot) {
+        throw new ProjectStateError(
+          `An earlier Terraform target root exists at ${path}. ` +
+            "Automatic migration is not supported; preserve its configuration and state before moving to the shared root.",
         );
-        if (path !== root && identity.success && identity.data.name === basename(path))
-          continue directories;
-        if (parsed.resources.some(({ mode }) => mode === "managed")) {
+      }
+      for (const filename of ["terraform.tfstate", "terraform.tfstate.backup"]) {
+        const text = await this.readOptional(join(path, filename));
+        if (
+          text !== undefined &&
+          stateSchema.parse(JSON.parse(text)).resources.some(({ mode }) => mode === "managed")
+        ) {
           throw new ProjectStateError(
             `Existing Terraform resources use the earlier state directory ${path}. ` +
               "Automatic state migration is not supported; preserve that state and manage it from its existing directory.",
@@ -103,16 +103,16 @@ export class TerraformState {
   async assertTarget(target: AwsDeploymentTarget): Promise<void> {
     await this.assertNoLegacyState();
     await this.assertLocalBackend();
-    const binding = await this.readOptional(join(this.directory, ".agentcore-target.json"));
+    const binding = await this.readOptional(join(this.targetDirectory, ".agentcore-target.json"));
     const state = await this.read();
     if (state === undefined) {
-      const backup = await this.readOptional(join(this.directory, "terraform.tfstate.backup"));
+      const backup = await this.readOptional(`${this.statePath}.backup`);
       if (
         backup &&
         stateSchema.parse(JSON.parse(backup)).resources.some(({ mode }) => mode === "managed")
       ) {
         throw new ProjectStateError(
-          `The current Terraform state is missing from ${this.directory}, but its backup contains resources. ` +
+          `The current Terraform state is missing from ${this.targetDirectory}, but its backup contains resources. ` +
             "Restore or repair the current state before deploying; the CLI will not start another deployment.",
         );
       }
@@ -128,7 +128,7 @@ export class TerraformState {
         parsed.data.region !== target.region
       ) {
         throw new ProjectStateError(
-          `Terraform state in ${this.directory} is bound to a different target, account, or region. ` +
+          `Terraform state in ${this.targetDirectory} is bound to a different target, account, or region. ` +
             "Use its original deployment target or a new named target; existing state will not be reassigned.",
         );
       }
@@ -139,7 +139,7 @@ export class TerraformState {
       state?.resources.some(({ mode }) => mode === "managed")
     ) {
       throw new ProjectStateError(
-        `Terraform resources in ${this.directory} have no deployment target identity. ` +
+        `Terraform resources in ${this.targetDirectory} have no deployment target identity. ` +
           "Preserve the state and use Terraform directly to repair the deployment_target output before using the CLI.",
       );
     }
@@ -147,33 +147,44 @@ export class TerraformState {
 
   async bind(target: AwsDeploymentTarget): Promise<void> {
     await this.assertTarget(target);
+    await mkdir(this.targetDirectory, { recursive: true, mode: 0o700 });
     await atomicWrite(
-      join(this.directory, ".agentcore-target.json"),
+      join(this.targetDirectory, ".agentcore-target.json"),
       `${JSON.stringify({ name: target.name, account: target.account, region: target.region }, null, 2)}\n`,
       { mode: 0o600 },
     );
   }
 
   async assertLocalBackend(): Promise<void> {
-    const text = await this.readOptional(join(this.directory, ".terraform", "terraform.tfstate"));
-    if (text === undefined) return;
-    const metadata = JSON.parse(text) as {
-      backend?: { type?: string; config?: { path?: string; workspace_dir?: string } };
-    };
-    const backend = metadata.backend;
-    if (
-      (backend?.type && backend.type !== "local") ||
-      (backend?.config?.path &&
-        resolve(this.directory, backend.config.path) !==
-          join(this.directory, "terraform.tfstate")) ||
-      (backend?.config?.workspace_dir &&
-        resolve(this.directory, backend.config.workspace_dir) !==
-          join(this.directory, "terraform.tfstate.d"))
-    ) {
-      throw new ProjectStateError(
-        "CLI Terraform operations require local state at this target's terraform.tfstate. " +
-          "Use Terraform directly with a remote backend or a custom state path.",
+    // Plain Terraform uses root/.terraform unless the caller sets TF_DATA_DIR.
+    // Check that metadata too before initializing an independent target directory.
+    for (const dataDirectory of [this.dataDirectory, join(this.directory, ".terraform")]) {
+      const text = await this.readOptional(join(dataDirectory, "terraform.tfstate"));
+      if (text === undefined) continue;
+      const metadata = JSON.parse(text) as {
+        backend?: { type?: string; config?: { path?: string; workspace_dir?: string } };
+      };
+      const backend = metadata.backend;
+      if (!backend) continue;
+      const statePath = resolve(this.directory, backend.config?.path || "terraform.tfstate");
+      const canonicalRootPath = /^\.targets\/[a-zA-Z0-9_-]+\/terraform\.tfstate$/.test(
+        relative(this.directory, statePath).replaceAll("\\", "/"),
       );
+      if (
+        backend.type !== "local" ||
+        (dataDirectory === this.dataDirectory
+          ? statePath !== this.statePath
+          : !canonicalRootPath) ||
+        (backend.config?.workspace_dir &&
+          resolve(this.directory, backend.config.workspace_dir) !==
+            join(this.directory, "terraform.tfstate.d"))
+      ) {
+        throw new ProjectStateError(
+          `CLI Terraform operations require local state under .targets/<target>/terraform.tfstate. ` +
+            `The initialized backend in ${dataDirectory} uses a different location or backend. ` +
+            "Use Terraform directly with a remote backend or a custom state path.",
+        );
+      }
     }
   }
 
@@ -201,7 +212,7 @@ export class TerraformState {
   private async read() {
     let text: string;
     try {
-      text = await readFile(join(this.directory, "terraform.tfstate"), "utf8");
+      text = await readFile(this.statePath, "utf8");
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
       throw error;
@@ -209,7 +220,7 @@ export class TerraformState {
     const parsed = stateSchema.safeParse(JSON.parse(text));
     if (!parsed.success) {
       throw new ProjectStateError(
-        `Cannot read Terraform state in ${this.directory}. Preserve the state file and repair it before retrying.`,
+        `Cannot read Terraform state in ${this.targetDirectory}. Preserve the state file and repair it before retrying.`,
       );
     }
     return parsed.data;
@@ -241,7 +252,7 @@ export class TerraformState {
     const parsed = z.array(resourceSchema).safeParse(outputs.project_resources);
     if (!parsed.success) {
       throw new ProjectStateError(
-        `Terraform project_resources output in ${this.directory} is not a recognized resource list.`,
+        `Terraform project_resources output in ${this.targetDirectory} is not a recognized resource list.`,
       );
     }
     return parsed.data;
diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts
index 174bb7eccd..745450f187 100644
--- a/src/core/project/manager.test.ts
+++ b/src/core/project/manager.test.ts
@@ -166,16 +166,17 @@ describe("FsProjectManager.create", () => {
     const gitignore = await readFile(join(project.rootPath, ".gitignore"), "utf8");
     expect(gitignore).not.toContain("\nagentcore/terraform/\n");
     expect(gitignore).toContain("*.tfstate");
-    expect(gitignore).toContain("agentcore/terraform/**/.agentcore-target.json");
-    const terraformRoot = join(project.rootPath, "agentcore", "terraform", "default");
+    expect(gitignore).toContain("agentcore/terraform/.targets/");
+    const terraformRoot = join(project.rootPath, "agentcore", "terraform");
     expect(await readFile(join(terraformRoot, "main.tf"), "utf8")).toContain(
-      'jsondecode(file("${path.module}/../../agentcore.json"))',
+      'jsondecode(file("${path.module}/../agentcore.json"))',
     );
     expect(await readFile(join(terraformRoot, "main.tf"), "utf8")).toContain(
       "agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=",
     );
     expect(existsSync(join(terraformRoot, "modules"))).toBe(false);
-    expect(existsSync(join(terraformRoot, "deployment.auto.tfvars.json"))).toBe(false);
+    expect(existsSync(join(terraformRoot, "default"))).toBe(false);
+    expect(existsSync(join(terraformRoot, ".targets"))).toBe(false);
     expect(JSON.parse(await readFile(join(terraformRoot, "artifacts.json"), "utf8"))).toEqual({
       runtimes: {},
       gatewayTargets: {},
diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx
index 18da497279..b84853d4f4 100644
--- a/src/core/project/manager.tsx
+++ b/src/core/project/manager.tsx
@@ -539,7 +539,7 @@ export class FsProjectManager implements ProjectManager {
     if (input.managedBy === "Terraform") {
       yield { type: "step", message: "Scaffolding Terraform application module" };
       await new TerraformProjectWriter().scaffold(
-        join(destination, "agentcore", "terraform", DEFAULT_TARGET_NAME),
+        join(destination, "agentcore", "terraform"),
         input.region,
       );
     }
diff --git a/src/core/project/templates/project.ts b/src/core/project/templates/project.ts
index 56b6ce82bd..10d43a264d 100644
--- a/src/core/project/templates/project.ts
+++ b/src/core/project/templates/project.ts
@@ -44,7 +44,7 @@ export async function createProjectTree(
     FsTreeNode.createFile(".gitignore", async () => {
       const shared = await config.assetSource.read("templates/shared/gitignore.template");
       return managedBy === "Terraform"
-        ? `${shared}\n# Terraform local packages, working files, and state (commit the .tf source)\nagentcore/terraform/**/assets/\nagentcore/terraform/**/artifacts.json\nagentcore/terraform/**/deployment.auto.tfvars.json\nagentcore/terraform/**/.agentcore-target.json\n.agentcore-operation.lock\n.terraform/\n*.tfstate\n*.tfstate.*\n*.tfplan\ncrash.log\n`
+        ? `${shared}\n# Terraform local packages, working files, and state (commit the .tf source)\nagentcore/terraform/**/assets/\nagentcore/terraform/**/artifacts.json\nagentcore/terraform/.targets/\nagentcore/terraform/**/deployment.auto.tfvars.json\nagentcore/terraform/**/.agentcore-target.json\n.agentcore-operation.lock\n.terraform/\n*.tfstate\n*.tfstate.*\n*.tfplan\ncrash.log\n`
         : shared;
     }),
     FsTreeNode.createDirectory("agentcore", [
diff --git a/src/handlers/project/project.test.ts b/src/handlers/project/project.test.ts
index 498190f287..c60e4a3e99 100644
--- a/src/handlers/project/project.test.ts
+++ b/src/handlers/project/project.test.ts
@@ -65,15 +65,21 @@ describe("project create", () => {
       const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
       expect(spec.managedBy).toBe("Terraform");
       expect(existsSync(join(projectRoot, "agentcore", "cdk"))).toBe(false);
-      expect(existsSync(join(projectRoot, "agentcore", "terraform", "default", "main.tf"))).toBe(
-        true,
-      );
-      const terraformRoot = join(projectRoot, "agentcore", "terraform", "default");
+      expect(existsSync(join(projectRoot, "agentcore", "terraform", "main.tf"))).toBe(true);
+      const terraformRoot = join(projectRoot, "agentcore", "terraform");
       expect(await Bun.file(join(terraformRoot, "main.tf")).text()).toContain(
         "agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=",
       );
       expect(existsSync(join(terraformRoot, "modules"))).toBe(false);
       expect(existsSync(join(terraformRoot, ".terraform"))).toBe(false);
+      expect(existsSync(join(terraformRoot, "default"))).toBe(false);
+      expect(existsSync(join(terraformRoot, ".targets"))).toBe(false);
+      expect(await Bun.file(join(terraformRoot, "main.tf")).text()).toContain(
+        'jsondecode(file("${path.module}/../agentcore.json"))',
+      );
+      expect(await Bun.file(join(projectRoot, ".gitignore")).text()).toContain(
+        "agentcore/terraform/.targets/",
+      );
       expect(core.projectCommands).toEqual([]);
       expect(io.stderr()).toContain("agentcore add runtime");
       expect(io.stderr()).not.toContain("agentcore add harness");

From 437295936551b95958b1b23995291afc8d113fc0 Mon Sep 17 00:00:00 2001
From: jariy17 <tjariy+jariy17@users.noreply.github.com>
Date: Thu, 15 Oct 2026 22:24:00 +0000
Subject: [PATCH 4/5] fix(terraform): pin parity-aligned module and match its
 preflight rules

- Pin the L3 Terraform module commit that aligns IAM, names, log group
  ownership and gateway discovery variables with the L3 construct.
- Preflight accepts Python entrypoints with a handler suffix and treats
  AGENTCORE_GATEWAY_<NAME>_AUTH_TYPE, not _ID, as a reserved variable.
- Scope the example Cedar policy to AgentCore::Gateway resources.
---
 examples/terraform-poc/README.md                |  8 ++++----
 examples/terraform-poc/agentcore/agentcore.json |  2 +-
 .../terraform-poc/agentcore/terraform/main.tf   |  2 +-
 .../backends/terraform/preflight.test.ts        | 17 +++++++++++++++--
 .../project/backends/terraform/preflight.ts     |  9 ++++++---
 src/core/project/backends/terraform/project.ts  |  2 +-
 6 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/examples/terraform-poc/README.md b/examples/terraform-poc/README.md
index 8649e07ca7..ecf94ba0f5 100644
--- a/examples/terraform-poc/README.md
+++ b/examples/terraform-poc/README.md
@@ -26,7 +26,7 @@ Set `CLI` to the absolute path of this branch's `dist/index.js`:
 export CLI=/absolute/path/to/agentcore-cli/dist/index.js
 ```
 
-This example creates billable resources and enables online evaluation at 100% sampling. Use it for a bounded experiment and tear it down afterward. The sample `permit(principal, action, resource);` policy permits all gateway actions to authenticated callers; replace it with your intended policy before using the configuration outside this example.
+This example creates billable resources and enables online evaluation at 100% sampling. Use it for a bounded experiment and tear it down afterward. The sample `permit(principal, action, resource is AgentCore::Gateway);` policy permits all gateway actions to authenticated callers; replace it with your intended policy before using the configuration outside this example.
 
 ## Create a project
 
@@ -97,11 +97,11 @@ terraform plan -var-file=.targets/default/deployment.tfvars.json
 
 Edit a supported value such as memory retention in `agentcore.json`, then run the same `terraform plan` command again. The module receives the updated object immediately. After reviewing the plan, apply it with the same target inputs. Changes to application source still require rebuilding the ZIPs and updating their artifact hashes.
 
-The checked-in [`agentcore/terraform/`](agentcore/terraform/) directory is the shared root example. It references the same pinned module from the L3 constructs repository. `agentcore build` writes the artifact manifest; callers supplying their own ZIPs can use the manifest contract described in the [module README](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/d3ce7229610ce0bb56d581c55f710e220b58faa4/terraform/modules/agentcore-application/README.md).
+The checked-in [`agentcore/terraform/`](agentcore/terraform/) directory is the shared root example. It references the same pinned module from the L3 constructs repository. `agentcore build` writes the artifact manifest; callers supplying their own ZIPs can use the manifest contract described in the [module README](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/ade47fb93664070aff6a23b714691ca7c10d6f7c/terraform/modules/agentcore-application/README.md).
 
 The root can pass inline HCL instead of JSON. This allows values from customer resources to enter the `spec` directly, for example `envVars = [{ name = "ORDERS_TABLE", value = aws_dynamodb_table.orders.name }]`. Outputs such as `module.application.runtimes["Agent"].role_name` allow a separate IAM policy to grant that runtime access to the table. Terraform follows these references to order changes.
 
-References between the project's resources are resolved inside the module: policy engine to gateway, Lambda and gateway to target, memories/gateways to runtime, and runtime logs to online evaluation. Circular references are rejected by Terraform. See the [module's inputs and outputs](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/d3ce7229610ce0bb56d581c55f710e220b58faa4/terraform/modules/agentcore-application/README.md) for the contract and limits.
+References between the project's resources are resolved inside the module: policy engine to gateway, Lambda and gateway to target, memories/gateways to runtime, and runtime logs to online evaluation. Circular references are rejected by Terraform. See the [module's inputs and outputs](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/ade47fb93664070aff6a23b714691ca7c10d6f7c/terraform/modules/agentcore-application/README.md) for the contract and limits.
 
 ## Exercise the deployed resources
 
@@ -115,7 +115,7 @@ node "$CLI" invoke --runtime Agent --payload '{"prompt":"How can I keep a cup of
 
 The memory operation writes an event and lists session events. Semantic extraction is asynchronous. The gateway operations use the runtime's IAM credentials to discover and invoke the Lambda tool. The final operation invokes a Strands agent and produces model telemetry for online evaluation; an active evaluation configuration alone does not establish that evaluation results are being produced.
 
-To examine enforcement, change the sample policy to `forbid(principal, action, resource);`, redeploy, and check that calling the tool is denied. Set the policy's `enforcementMode` to `LOG_ONLY`, redeploy, and check its observed behavior before restoring the original policy. The gateway's policy-engine mode remains `ENFORCE`; it is a separate setting.
+To examine enforcement, change the sample policy to `forbid(principal, action, resource is AgentCore::Gateway);`, redeploy, and check that calling the tool is denied. Set the policy's `enforcementMode` to `LOG_ONLY`, redeploy, and check its observed behavior before restoring the original policy. The gateway's policy-engine mode remains `ENFORCE`; it is a separate setting.
 
 The module maps the statement through AWSCC's `definition.policy.statement` input. A valid Dogwood statement can be supplied there, but schema support and a successful deployment of a particular Dogwood policy are separate checks.
 
diff --git a/examples/terraform-poc/agentcore/agentcore.json b/examples/terraform-poc/agentcore/agentcore.json
index e2bc247086..9b3b653d47 100644
--- a/examples/terraform-poc/agentcore/agentcore.json
+++ b/examples/terraform-poc/agentcore/agentcore.json
@@ -31,7 +31,7 @@
       "policies": [
         {
           "name": "AllowEcho",
-          "statement": "permit(principal, action, resource);",
+          "statement": "permit(principal, action, resource is AgentCore::Gateway);",
           "validationMode": "IGNORE_ALL_FINDINGS",
           "enforcementMode": "ACTIVE"
         }
diff --git a/examples/terraform-poc/agentcore/terraform/main.tf b/examples/terraform-poc/agentcore/terraform/main.tf
index 18ce1a3a72..78932ea4b0 100644
--- a/examples/terraform-poc/agentcore/terraform/main.tf
+++ b/examples/terraform-poc/agentcore/terraform/main.tf
@@ -1,6 +1,6 @@
 # Module implementation is owned by the companion L3 constructs PoC.
 module "application" {
-  source = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=d3ce7229610ce0bb56d581c55f710e220b58faa4"
+  source = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=ade47fb93664070aff6a23b714691ca7c10d6f7c"
 
   spec        = jsondecode(file("${path.module}/../agentcore.json"))
   target_name = var.target_name
diff --git a/src/core/project/backends/terraform/preflight.test.ts b/src/core/project/backends/terraform/preflight.test.ts
index 869079cbf2..edac2c32f1 100644
--- a/src/core/project/backends/terraform/preflight.test.ts
+++ b/src/core/project/backends/terraform/preflight.test.ts
@@ -27,7 +27,7 @@ function project(): Project {
           policies: [
             {
               name: "Allow",
-              statement: "permit(principal, action, resource);",
+              statement: "permit(principal, action, resource is AgentCore::Gateway);",
               enforcementMode: "LOG_ONLY",
             },
           ],
@@ -73,6 +73,11 @@ describe("Terraform project preflight", () => {
     expect(() => new TerraformProjectValidator().validate(project())).not.toThrow();
     expect(declaredResources(project())).toHaveLength(7);
   });
+  test("accepts a Python entrypoint with a handler suffix", () => {
+    const p = project();
+    p.spec.runtimes[0]!.entrypoint = "main.py:app";
+    expect(() => new TerraformProjectValidator().validate(p)).not.toThrow();
+  });
   test.each([
     [
       "migratedFrom",
@@ -107,7 +112,15 @@ describe("Terraform project preflight", () => {
     [
       "runtimes[Agent].entrypoint",
       (p: Project) => {
-        p.spec.runtimes[0]!.entrypoint = "main.py:app";
+        p.spec.runtimes[0]!.entrypoint = "main.js:app";
+      },
+    ],
+    [
+      "envVars.AGENTCORE_GATEWAY_TOOLS_AUTH_TYPE",
+      (p: Project) => {
+        p.spec.runtimes[0]!.envVars = [
+          { name: "AGENTCORE_GATEWAY_TOOLS_AUTH_TYPE", value: "NONE" },
+        ];
       },
     ],
     [
diff --git a/src/core/project/backends/terraform/preflight.ts b/src/core/project/backends/terraform/preflight.ts
index 53d073ced4..7137d928bf 100644
--- a/src/core/project/backends/terraform/preflight.ts
+++ b/src/core/project/backends/terraform/preflight.ts
@@ -91,8 +91,11 @@ export class TerraformProjectValidator {
         reject(`${path}.networkMode`, "must be PUBLIC for this PoC");
       if (runtime.authorizerType && runtime.authorizerType !== "AWS_IAM")
         reject(`${path}.authorizerType`, "must be AWS_IAM for this PoC");
-      if (!runtime.entrypoint.endsWith(".py"))
-        reject(`${path}.entrypoint`, "must be a Python script without a handler suffix");
+      if (!runtime.entrypoint.split(":")[0]!.endsWith(".py"))
+        reject(
+          `${path}.entrypoint`,
+          "must be a Python script, optionally followed by a handler suffix",
+        );
       const environment = new Set<string>();
       for (const env of runtime.envVars ?? []) {
         if (environment.has(env.name))
@@ -106,7 +109,7 @@ export class TerraformProjectValidator {
             ].includes(env.name),
           ) ||
           project.spec.agentCoreGateways.some((gateway) =>
-            ["URL", "ARN", "ID"]
+            ["URL", "ARN", "AUTH_TYPE"]
               .map((suffix) => `${this.gatewayPrefix(gateway.name)}_${suffix}`)
               .includes(env.name),
           );
diff --git a/src/core/project/backends/terraform/project.ts b/src/core/project/backends/terraform/project.ts
index 49634f7a8f..0f9fa38158 100644
--- a/src/core/project/backends/terraform/project.ts
+++ b/src/core/project/backends/terraform/project.ts
@@ -9,7 +9,7 @@ import type { TerraformAssets } from "./types";
 const ROOT_FILES: Record<string, string> = {
   "main.tf": `# This root is yours to edit. The CLI refreshes artifacts.json and target inputs.
 module "application" {
-  source      = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=d3ce7229610ce0bb56d581c55f710e220b58faa4"
+  source      = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=ade47fb93664070aff6a23b714691ca7c10d6f7c"
   spec        = jsondecode(file("\${path.module}/../agentcore.json"))
   target_name = var.target_name
   account_id  = var.account_id

From 9983b1449c2a29574de192a920464bc8461e6852 Mon Sep 17 00:00:00 2001
From: jariy17 <tjariy+jariy17@users.noreply.github.com>
Date: Thu, 15 Oct 2026 23:03:08 +0000
Subject: [PATCH 5/5] fix(terraform): pin module with L2 gateway trust and IAM
 waits

- Pin the L3 module commit that reproduces the CDK L2 gateway trust and
  waits for IAM propagation before creating AgentCore resources.
- Record live results in the example and document the LOG_ONLY
  default-deny behavior, evaluation result location, and per-account
  policy name uniqueness.
---
 examples/terraform-poc/README.md                   | 14 +++++++-------
 examples/terraform-poc/agentcore/terraform/main.tf |  2 +-
 src/core/project/backends/terraform/project.ts     |  2 +-
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/examples/terraform-poc/README.md b/examples/terraform-poc/README.md
index ecf94ba0f5..6ae3bf8998 100644
--- a/examples/terraform-poc/README.md
+++ b/examples/terraform-poc/README.md
@@ -9,9 +9,9 @@ This example exercises an experimental Terraform deployment backend for a small
 
 The backend scaffolds HCL root files and references the reusable `agentcore-application` module maintained in the AgentCore L3 constructs repository. The root reads `agentcore/agentcore.json` and passes a typed `spec` object into the module. Terraform reads the JSON on every plan, so changing a supported setting does not require CLI regeneration.
 
-AgentCore resources use AWSCC 1.106.0, except for gateway targets: that release does not expose a gateway target resource, so the example uses AWS provider 6.69.0 for its Lambda target. The AWS provider also manages IAM, S3, Lambda, and logs. Resource creation is owned by Terraform.
+AgentCore resources use AWSCC 1.106.0, except for gateway targets: that release does not expose a gateway target resource, so the example uses AWS provider 6.69.0 for its Lambda target. The AWS provider also manages IAM, S3, and Lambda. As with the CDK constructs, the services create their own log groups.
 
-The example has been packaged reproducibly, validated against both pinned providers, and planned with Terraform 1.16.6 (25 resources). Live deployment, invocation, policy enforcement, evaluation results, updates, and teardown remain unverified. The steps below describe the experiment to run.
+This example has been deployed live with Terraform 1.16.6, both from an empty account state and incrementally. Every step below was exercised: invocation, memory events and semantic extraction, gateway tool discovery and calls, policy permit/forbid/`LOG_ONLY` behavior, online evaluation scores, code updates, a no-change repeat plan, and teardown. These were manual runs in one test account, not automated end-to-end tests.
 
 ## Prerequisites
 
@@ -53,7 +53,7 @@ The customer owns the root `.tf` files. Build and deploy preserve those edits. T
 
 ## Deploy the connected example
 
-Copy this directory outside the repository before using it so configuration changes and deployment state remain separate from the checked-in fixture. Set `CLI` to the absolute path of this branch's `dist/index.js`.
+Copy this directory outside the repository before using it so configuration changes and deployment state remain separate from the checked-in fixture. Policy names are unique per account and Region, so a second copy in the same account needs a different project name and policy name. Set `CLI` to the absolute path of this branch's `dist/index.js`.
 
 ```sh
 export CLI=/absolute/path/to/agentcore-cli/dist/index.js
@@ -97,11 +97,11 @@ terraform plan -var-file=.targets/default/deployment.tfvars.json
 
 Edit a supported value such as memory retention in `agentcore.json`, then run the same `terraform plan` command again. The module receives the updated object immediately. After reviewing the plan, apply it with the same target inputs. Changes to application source still require rebuilding the ZIPs and updating their artifact hashes.
 
-The checked-in [`agentcore/terraform/`](agentcore/terraform/) directory is the shared root example. It references the same pinned module from the L3 constructs repository. `agentcore build` writes the artifact manifest; callers supplying their own ZIPs can use the manifest contract described in the [module README](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/ade47fb93664070aff6a23b714691ca7c10d6f7c/terraform/modules/agentcore-application/README.md).
+The checked-in [`agentcore/terraform/`](agentcore/terraform/) directory is the shared root example. It references the same pinned module from the L3 constructs repository. `agentcore build` writes the artifact manifest; callers supplying their own ZIPs can use the manifest contract described in the [module README](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/39b824c1cdbc4926bea745616610e516344537f4/terraform/modules/agentcore-application/README.md).
 
 The root can pass inline HCL instead of JSON. This allows values from customer resources to enter the `spec` directly, for example `envVars = [{ name = "ORDERS_TABLE", value = aws_dynamodb_table.orders.name }]`. Outputs such as `module.application.runtimes["Agent"].role_name` allow a separate IAM policy to grant that runtime access to the table. Terraform follows these references to order changes.
 
-References between the project's resources are resolved inside the module: policy engine to gateway, Lambda and gateway to target, memories/gateways to runtime, and runtime logs to online evaluation. Circular references are rejected by Terraform. See the [module's inputs and outputs](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/ade47fb93664070aff6a23b714691ca7c10d6f7c/terraform/modules/agentcore-application/README.md) for the contract and limits.
+References between the project's resources are resolved inside the module: policy engine to gateway, Lambda and gateway to target, memories/gateways to runtime, and runtime logs to online evaluation. Circular references are rejected by Terraform. See the [module's inputs and outputs](https://github.com/jariy17/agentcore-l3-cdk-constructs/blob/39b824c1cdbc4926bea745616610e516344537f4/terraform/modules/agentcore-application/README.md) for the contract and limits.
 
 ## Exercise the deployed resources
 
@@ -113,9 +113,9 @@ node "$CLI" invoke --runtime Agent --payload '{"operation":"echo","message":"Hel
 node "$CLI" invoke --runtime Agent --payload '{"prompt":"How can I keep a cup of tea warm?"}'
 ```
 
-The memory operation writes an event and lists session events. Semantic extraction is asynchronous. The gateway operations use the runtime's IAM credentials to discover and invoke the Lambda tool. The final operation invokes a Strands agent and produces model telemetry for online evaluation; an active evaluation configuration alone does not establish that evaluation results are being produced.
+The memory operation writes an event and lists session events. Semantic extraction is asynchronous. The gateway operations use the runtime's IAM credentials to discover and invoke the Lambda tool. The final operation invokes a Strands agent and produces model telemetry for online evaluation; results appear in `/aws/bedrock-agentcore/evaluations/results/<config id>` a few minutes after the session goes idle. Sessions without model spans, such as the probe operations, are recorded as evaluation errors.
 
-To examine enforcement, change the sample policy to `forbid(principal, action, resource is AgentCore::Gateway);`, redeploy, and check that calling the tool is denied. Set the policy's `enforcementMode` to `LOG_ONLY`, redeploy, and check its observed behavior before restoring the original policy. The gateway's policy-engine mode remains `ENFORCE`; it is a separate setting.
+To examine enforcement, change the sample policy to `forbid(principal, action, resource is AgentCore::Gateway);`, redeploy, and check that calling the tool is denied. Set the policy's `enforcementMode` to `LOG_ONLY`, redeploy, and check its observed behavior before restoring the original policy: with the only policy in `LOG_ONLY`, no enforced policy permits the call, so the gateway still denies it by default. The gateway's policy-engine mode remains `ENFORCE`; it is a separate setting.
 
 The module maps the statement through AWSCC's `definition.policy.statement` input. A valid Dogwood statement can be supplied there, but schema support and a successful deployment of a particular Dogwood policy are separate checks.
 
diff --git a/examples/terraform-poc/agentcore/terraform/main.tf b/examples/terraform-poc/agentcore/terraform/main.tf
index 78932ea4b0..c66af77812 100644
--- a/examples/terraform-poc/agentcore/terraform/main.tf
+++ b/examples/terraform-poc/agentcore/terraform/main.tf
@@ -1,6 +1,6 @@
 # Module implementation is owned by the companion L3 constructs PoC.
 module "application" {
-  source = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=ade47fb93664070aff6a23b714691ca7c10d6f7c"
+  source = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=39b824c1cdbc4926bea745616610e516344537f4"
 
   spec        = jsondecode(file("${path.module}/../agentcore.json"))
   target_name = var.target_name
diff --git a/src/core/project/backends/terraform/project.ts b/src/core/project/backends/terraform/project.ts
index 0f9fa38158..abed5755bd 100644
--- a/src/core/project/backends/terraform/project.ts
+++ b/src/core/project/backends/terraform/project.ts
@@ -9,7 +9,7 @@ import type { TerraformAssets } from "./types";
 const ROOT_FILES: Record<string, string> = {
   "main.tf": `# This root is yours to edit. The CLI refreshes artifacts.json and target inputs.
 module "application" {
-  source      = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=ade47fb93664070aff6a23b714691ca7c10d6f7c"
+  source      = "git::https://github.com/jariy17/agentcore-l3-cdk-constructs.git//terraform/modules/agentcore-application?ref=39b824c1cdbc4926bea745616610e516344537f4"
   spec        = jsondecode(file("\${path.module}/../agentcore.json"))
   target_name = var.target_name
   account_id  = var.account_id