feat: document Foundry project ownership boundary

cli/azd/docs/environment-variables.md

@@ -145,17 +145,28 @@ specific version of the tool installed on the machine.
 > **Note**: These variables are defined and consumed by individual azd extensions. As the extension
 > ecosystem grows, extension-specific variables may move to each extension's own documentation.
 
-### azure.ai.agents
+### Microsoft Foundry extensions
+
+The `azure.ai.projects` extension is the owner of Foundry project identity
+values. The `azure.ai.agents` extension consumes those values when it creates
+agent services and keeps its own agent-specific values.
+
+When project identity changes, `azure.ai.projects` writes an empty string as a
+tombstone for stale project-owned keys. Consumers treat an empty value as not
+configured and resolve current project state instead.
 
 | Variable | Description |
 | --- | --- |
-| `AZURE_AI_PROJECT_ID` | The Microsoft Foundry project resource ID used by the `azure.ai.agents` extension. |
-| `FOUNDRY_PROJECT_ENDPOINT` | The Microsoft Foundry project endpoint used by the `azure.ai.agents` extension. Read first from the active azd environment and, if not present, from the host shell environment as an endpoint-resolution fallback. |
+| `AZURE_AI_PROJECT_ID` | The Microsoft Foundry project resource ID resolved and persisted by `azure.ai.projects`. |
+| `FOUNDRY_PROJECT_ENDPOINT` | The Microsoft Foundry project endpoint resolved and persisted by `azure.ai.projects`. `azure.ai.agents` reads it for agent workflows and endpoint-only compatibility. |
 | `AZURE_AI_PROJECT_PRINCIPAL_ID` | The principal ID associated with the Microsoft Foundry project identity. |
 | `AZURE_AI_ACCOUNT_NAME` | The Microsoft Foundry account name associated with the project. |
 | `AZURE_AI_PROJECT_NAME` | The Microsoft Foundry project name. |
+| `AZURE_AI_DEPLOYMENTS_LOCATION` | The location used to resolve and provision managed model deployments. |
 | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | The default model deployment name used for generated agent code and templates. |
-| `AZURE_AI_PROJECT_ACR_CONNECTION_NAME` | The Azure Container Registry connection name used by the extension for hosted agents. |
+| `AZURE_AI_PROJECT_CONNECTION_NAMES` | Comma-separated project connection names emitted by Foundry provisioning. |
+| `AZURE_AI_PROJECT_CONNECTIONS_PROJECT_ENDPOINT` | The project endpoint used by connection services. |
+| `AZURE_AI_PROJECT_ACR_CONNECTION_NAME` | The Azure Container Registry connection name used by hosted agents. |
 | `AI_PROJECT_DEPLOYMENTS` | JSON-encoded deployment metadata populated by the extension for agent workflows. |
 | `AI_PROJECT_DEPENDENT_RESOURCES` | JSON-encoded dependent resource metadata populated by the extension for agent workflows. |
 | `AZD_AGENT_SKIP_ACR` | If `true`, signals the Bicep template to skip Azure Container Registry creation during provisioning. Automatically set by `azd agent init` for code-deploy scenarios (where no container image is built). |

docs/README.md

@@ -46,6 +46,24 @@ System overviews, design context, and decision records.
 - [Telemetry Architecture](architecture/telemetry.md) — How azd collects and exports telemetry
 - [ADR Template](architecture/adr-template.md) — Template for lightweight architecture decision records
 
+## Microsoft Foundry project ownership
+
+The `azure.ai.projects` extension owns Foundry project identity and managed
+model deployments:
+
+```text
+azd ai project init
+azd ai project deployment add --model <model>
+```
+
+`azure.ai.agents` delegates project initialization and managed deployment
+selection to those commands. It continues to own agent services and external
+deployment references. Endpoint-only projects are valid for data-plane use,
+but operations that need ARM identity, such as infrastructure ejection or
+managed deployment creation, require a verified project resource ID.
+When project identity changes, stale project-owned environment keys are written
+as empty-string tombstones; consumers treat empty values as not configured.
+
 ---
 
 ## Where do new docs go?

docs/architecture/extension-framework.md

@@ -84,6 +84,12 @@ Extensions use two structured error types:
 
 Error precedence: ServiceError → LocalError → azcore.ResponseError → gRPC auth → fallback
 
+Delegated commands use the existing `WorkflowService.Run` completion contract:
+a successful call means the command completed, and failures are returned by the
+service. The parent extension writes an input-only, versioned `request.json`;
+after success, it rereads state through the `Project` and `Environment` APIs
+instead of consuming a result file or a second JSON stream.
+
 ## First-Party Extensions
 
 First-party extensions live in `cli/azd/extensions/` and are registered in `cli/azd/extensions/registry.json`.

docs/reference/environment-variables.md

@@ -59,6 +59,26 @@ Set by IDE hosts (VS Code, Visual Studio) when spawning azd as a subprocess. Use
 
 For details on the external authentication protocol, see [cli/azd/docs/external-authentication.md](../../cli/azd/docs/external-authentication.md).
 
+## Microsoft Foundry extensions
+
+The `azure.ai.projects` extension owns the project identity values below.
+`azure.ai.agents` consumes them for agent workflows.
+
+When project identity changes, `azure.ai.projects` writes an empty string as a
+tombstone for stale project-owned keys. Consumers treat an empty value as not
+configured and resolve current project state instead.
+
+| Variable | Description |
+|---|---|
+| `AZURE_AI_PROJECT_ID` | Microsoft Foundry project resource ID |
+| `FOUNDRY_PROJECT_ENDPOINT` | Microsoft Foundry project endpoint |
+| `AZURE_AI_ACCOUNT_NAME` | Microsoft Foundry account name |
+| `AZURE_AI_PROJECT_NAME` | Microsoft Foundry project name |
+| `AZURE_AI_DEPLOYMENTS_LOCATION` | Managed deployment location |
+| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Default managed model deployment name |
+| `AZURE_AI_PROJECT_CONNECTION_NAMES` | Comma-separated project connection names |
+| `AZURE_AI_PROJECT_CONNECTIONS_PROJECT_ENDPOINT` | Project endpoint used by connection services |
+
 ## See Also
 
 For the full reference with implementation details, see [cli/azd/docs/environment-variables.md](../../cli/azd/docs/environment-variables.md).

docs/reference/feature-status.md

@@ -15,6 +15,8 @@ Current maturity status of Azure Developer CLI features. See [Feature Stages](..
 | `help` | Stable |
 | `infra generate` | Beta |
 | `init` | Stable |
+| `ai project init` | Beta |
+| `ai project deployment add` | Beta |
 | `monitor` | Beta |
 | `package` | Beta |
 | `pipeline` | Beta |