feat(kind): skip unprovisioned vTeam tenants in fleet; self-contained vTeam catalog lab

- kind-up now provisions only the demo fleet (tenant-a, tenant-b): the
  fleet loop applies an overlay only when examples/overlays/<ns>/ exists
  and fails loudly if any tenant apply fails (no silent partial
  provisioning). Reduced OPENSHELL_TENANTS default accordingly.
- vTeam catalog lab is self-contained against a clean cluster: applying a
  catalog creates the Project and the control plane provisions the backing
  namespace + gateway from that record. Rewrote QUICKSTART/vteam-lab/READMEs
  accordingly, including correct provider-secret setup (vertex/github token
  key; jira url/email/token).

Author: jeremyeder

Makefile

@@ -114,7 +114,10 @@ GOOGLE_APPLICATION_CREDENTIALS ?= $(or $(shell echo $$GOOGLE_APPLICATION_CREDENT
 VERTEX_CRED ?= $(GOOGLE_APPLICATION_CREDENTIALS)
 
 # OpenShell Gateway Configuration (OPENSHELL_USE_GATEWAY=true by default)
-# Provisions tenant namespaces with an OpenShell gateway each.
+# Provisions the demo fleet tenant namespaces with an OpenShell gateway each.
+# Only tenants that have an examples/overlays/<ns>/ overlay are fully applied.
+# The vTeam catalog lab (examples/vteam-catalog/) is intentionally NOT provisioned
+# here — it is self-contained and applied by the user against a clean cluster.
 # Override with OPENSHELL_TENANTS="ns1 ns2" to change the set of tenant namespaces.
 # Skip acpctl apply for specific tenants: SKIP_TENANT_SETUP="tenant-c"
 OPENSHELL_USE_GATEWAY ?= true
@@ -1002,26 +1005,32 @@ kind-up: preflight-cluster build-cli ## Start kind cluster and deploy the platfo
 		sleep 2; \
 		TOKEN=$$(kubectl get secret test-user-token -n $(NAMESPACE) -o jsonpath='{.data.token}' 2>/dev/null | base64 -d 2>/dev/null); \
 		$$ACPCTL login --url "http://localhost:$${PF_PORT}" --token "$$TOKEN" >/dev/null 2>&1; \
+		FLEET_FAILED=""; \
 		for ns in $(OPENSHELL_TENANTS); do \
 			if echo " $(SKIP_TENANT_SETUP) " | grep -q " $$ns "; then \
 				echo "  $$ns: skipped (SKIP_TENANT_SETUP)"; \
 				continue; \
 			fi; \
+			[ -f "examples/overlays/$$ns/kustomization.yaml" ] || continue; \
 			if [ -f "$(VERTEX_CRED)" ]; then \
 				kubectl create secret generic vertex-sa-key \
 					--namespace="$$ns" \
 					"--from-literal=token=$$(cat '$(VERTEX_CRED)')" \
 					--dry-run=client -o yaml | kubectl apply -f - 2>/dev/null; \
 			fi; \
-			if [ -d "examples/overlays/$$ns" ]; then \
-				VERTEX_SA_KEY=$$(cat "$(VERTEX_CRED)" 2>/dev/null || echo "") \
-				$$ACPCTL apply -k "examples/overlays/$$ns/" --project "$$ns" && \
+			if VERTEX_SA_KEY=$$(cat "$(VERTEX_CRED)" 2>/dev/null || echo "") \
+				$$ACPCTL apply -k "examples/overlays/$$ns/" --project "$$ns"; then \
 				echo "  $$ns: applied"; \
 			else \
-				echo "  $$ns: no overlay directory — skipping fleet"; \
+				echo "$(COLOR_RED)✗$(COLOR_RESET) $$ns: apply failed"; \
+				FLEET_FAILED="$$FLEET_FAILED $$ns"; \
 			fi; \
 		done; \
 		kill $$PF_PID 2>/dev/null || true; \
+		if [ -n "$$FLEET_FAILED" ]; then \
+			echo "$(COLOR_RED)✗$(COLOR_RESET) Fleet provisioning failed for:$$FLEET_FAILED"; \
+			exit 1; \
+		fi; \
 	fi
 	@# Vertex AI setup if requested (non-gateway)
 	@if [ "$(OPENSHELL_USE_GATEWAY)" != "true" ]; then \

docs/src/content/docs/guides/vteam-lab.md

@@ -24,9 +24,12 @@ ACP ships two catalog examples:
 The manifests live in
 [examples/vteam-catalog](https://github.com/openshift-online/agent-control-plane/tree/main/examples/vteam-catalog).
 
-For local Kind clusters, `make kind-up` includes `vteam-product-swarm` and
-`codebase-maintainers` in the default `OPENSHELL_TENANTS` list, so those
-namespaces are ready for the lab.
+The lab is self-contained and runs against a clean cluster: applying a catalog
+creates the `Project` record, and the control plane provisions the backing
+namespace and gateway from it (see [Gateway and namespace
+behavior](#gateway-and-namespace-behavior)). On a local Kind cluster, `make
+kind-up` only provisions the demo fleet (`tenant-a`, `tenant-b`); it does not
+pre-create the vTeam tenants — the apply step below does.
 
 ## Apply a catalog team
 
@@ -71,8 +74,10 @@ server_dns_names:
   - openshell-gateway.vteam-product-swarm.svc.cluster.local
 ```
 
-The control plane resolves the project namespace as `vteam-product-swarm` and
-creates the gateway Kubernetes resources there.
+When the `Project` record is applied, the control plane creates the namespace
+`vteam-product-swarm` (no `kubectl create namespace` needed) and then, on a
+subsequent reconcile pass, deploys the gateway Kubernetes resources there. Both
+are eventually consistent — they appear a few seconds after the apply.
 
 ## Verify
 
@@ -90,14 +95,20 @@ acpctl agent list --project codebase-maintainers
 acpctl provider list --project codebase-maintainers
 ```
 
-On a local Kind cluster, also check the project namespaces:
+On a local Kind cluster, also check the project namespaces. These are created by
+the control plane reconciler after the apply, so wait for them rather than
+expecting them immediately:
 
 ```bash
-kubectl get namespace vteam-product-swarm
-kubectl get statefulset openshell-gateway -n vteam-product-swarm
-
-kubectl get namespace codebase-maintainers
-kubectl get statefulset openshell-gateway -n codebase-maintainers
+kubectl wait --for=jsonpath='{.status.phase}'=Active \
+  namespace/vteam-product-swarm --timeout=60s
+kubectl rollout status statefulset/openshell-gateway \
+  -n vteam-product-swarm --timeout=120s
+
+kubectl wait --for=jsonpath='{.status.phase}'=Active \
+  namespace/codebase-maintainers --timeout=60s
+kubectl rollout status statefulset/openshell-gateway \
+  -n codebase-maintainers --timeout=120s
 ```
 
 For a hand-run local reload flow, use the

examples/README.md

@@ -331,7 +331,7 @@ vteam-catalog/
 └── codebase-maintainers/    # Internal codebase maintenance team
 ```
 
-The `vteam-product-swarm` and `codebase-maintainers` namespaces are provisioned automatically during `make kind-up` (included in the default `OPENSHELL_TENANTS`). See the [vTeam Catalog README](vteam-catalog/README.md) for architecture details and the [QUICKSTART](vteam-catalog/QUICKSTART.md) for a step-by-step walkthrough.
+The vTeam lab is self-contained: applying a catalog creates the `Project`, and the control plane provisions its namespace and gateway from that record — so `make kind-up` does not pre-create these tenants (only the `tenant-a`/`tenant-b` demo fleet). See the [vTeam Catalog README](vteam-catalog/README.md) for architecture details and the [QUICKSTART](vteam-catalog/QUICKSTART.md) for a step-by-step walkthrough.
 
 ### Applying
 

examples/vteam-catalog/QUICKSTART.md

@@ -1,7 +1,10 @@
 # vTeam Catalog Manual Reload Quickstart
 
-Use this when you want to recreate the current vTeam Catalog lab environment
-from the manifests by hand.
+Use this to stand up the vTeam Catalog lab environment from the manifests by hand.
+The lab is **self-contained**: it runs against a clean/empty cluster and creates
+everything it needs (project, namespace, gateway, agents, providers) itself via
+`acpctl apply`. `make kind-up` only brings up the cluster and platform — it does
+**not** pre-create the `vteam-product-swarm` tenant.
 
 ## 0. Start From The Feature Worktree
 
@@ -34,6 +37,10 @@ Then create the cluster:
 make kind-up OPENSHELL_USE_GATEWAY=true
 ```
 
+This provisions the cluster, the platform, and the OpenShell gateway
+infrastructure. It does **not** create the `vteam-product-swarm` project or
+namespace — you create those in step 4 by applying the catalog.
+
 After it finishes, check the assigned ports:
 
 ```bash
@@ -85,7 +92,6 @@ In the first terminal, log in with the Makefile helper:
 
 ```bash
 make kind-acpctl-login
-export AMBIENT_PROJECT=vteam-product-swarm
 ```
 
 If you need to do the same steps manually, derive the backend port from
@@ -109,53 +115,19 @@ TOKEN=$(kubectl get secret test-user-token -n ambient-code \
   --token "$TOKEN"
 ```
 
-Quick check:
+Quick check that login works. The vTeam project does **not** exist yet — you
+create it in the next step:
 
 ```bash
-export AMBIENT_PROJECT=vteam-product-swarm
 "$ACPCTL" get projects
 ```
 
-## 4. Optional Runtime Secrets
-
-Applying the catalog does not require provider secrets. Starting real sessions
-needs the provider backing secrets in namespace `vteam-product-swarm`:
-
-- `vertex-sa-key`
-- `github-creds`
-- `jira`
-
-If you want Vertex credentials from the repo workflow, run:
-
-```bash
-make kind-setup-vertex
-```
-
-For the other providers, add your own credentials as `kind: Credential`
-resources and apply them with `acpctl`. For example, to give the GitHub-backed
-agents (Amber, Parker, …) a token, create a file like
-[`examples/overlays/tenant-a/credential-github.yaml`](../overlays/tenant-a/credential-github.yaml):
+## 4. Apply The vTeam Catalog Manifests
 
-```yaml
-kind: Credential
-name: github-cred
-provider: github
-token: $GITHUB_PAT   # a GitHub Personal Access Token
-```
-
-```bash
-export AMBIENT_PROJECT=vteam-product-swarm
-"$ACPCTL" apply -f credential-github.yaml --project vteam-product-swarm
-```
-
-The control plane materializes the `github-creds` secret in the project
-namespace from this record. See the
-[Credentials concept guide](https://openshift-online.github.io/agent-control-plane/concepts/credentials/)
-for how credentials, role bindings, and runtime wiring fit together. Without a
-credential for a provider an agent declares, its sessions fail to start with
-`reading secret <provider>-creds ... not found`.
-
-## 5. Apply The Current vTeam Catalog Manifests
+This is the core lab step. Applying the catalog creates the `vteam-product-swarm`
+**project** record; the control plane then provisions the backing Kubernetes
+namespace and the OpenShell gateway from that record — no `kubectl create
+namespace` needed.
 
 ```bash
 export AMBIENT_PROJECT=vteam-product-swarm
@@ -164,31 +136,85 @@ export AMBIENT_PROJECT=vteam-product-swarm
   --project vteam-product-swarm
 ```
 
-Verify ACP records:
+Verify the ACP records (available immediately after apply):
 
 ```bash
-export AMBIENT_PROJECT=vteam-product-swarm
 "$ACPCTL" get project vteam-product-swarm
 "$ACPCTL" agent list --project vteam-product-swarm
 "$ACPCTL" provider list --project vteam-product-swarm
 ```
 
-Verify Kubernetes-side objects:
+Verify the Kubernetes-side objects. The namespace and gateway are created by the
+control plane reconciler, so they appear a few seconds after the apply — wait for
+them rather than expecting them immediately:
 
 ```bash
-kubectl get namespace vteam-product-swarm
+kubectl wait --for=jsonpath='{.status.phase}'=Active \
+  namespace/vteam-product-swarm --timeout=60s
 kubectl get all,configmap,secret,pvc,serviceaccount,role,rolebinding \
   -n vteam-product-swarm
+# The gateway StatefulSet is deployed on the next reconcile pass:
+kubectl rollout status statefulset/openshell-gateway \
+  -n vteam-product-swarm --timeout=120s
 ```
 
+## 5. Optional Runtime Secrets
+
+Applying the catalog does not require provider secrets. But starting real
+sessions does: at gateway setup the control plane reads each provider's backing
+Kubernetes Secret directly from the project namespace, so those Secrets must
+exist there. The catalog's providers declare these secret names:
+
+- `vertex-sa-key`
+- `github-creds`
+- `jira`
+
+Do **not** rely on `make kind-setup-vertex` — that target is scoped to the demo
+fleet tenants in `OPENSHELL_TENANTS`, not the catalog project.
+
+Vertex and GitHub each use a secret with a single `token` key, created directly
+in the `vteam-product-swarm` namespace (created in step 4):
+
+```bash
+# Vertex — token is the full contents of a GCP service-account JSON key
+kubectl create secret generic vertex-sa-key \
+  --namespace vteam-product-swarm \
+  --from-literal=token="$(cat /path/to/gcp-sa-key.json)"
+
+# GitHub — token is a Personal Access Token
+kubectl create secret generic github-creds \
+  --namespace vteam-product-swarm \
+  --from-literal=token="$GITHUB_PAT"
+```
+
+Jira (used only by Parker) needs more than a token — the `jira` provider passes
+its Secret keys straight through as environment variables, so the Secret must
+carry the base URL, account, and API token that the Atlassian MCP expects
+(`JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN`), matching the tenant example in
+[examples/README.md](../README.md):
+
+```bash
+kubectl create secret generic jira \
+  --namespace vteam-product-swarm \
+  --from-literal=JIRA_URL=https://your-org.atlassian.net \
+  --from-literal=JIRA_USERNAME="you@example.com" \
+  --from-literal=JIRA_API_TOKEN="$(cat ~/jira-token.txt)"
+```
+
+Only set up the providers whose agents you actually run. See the
+[Credentials concept guide](https://openshift-online.github.io/agent-control-plane/concepts/credentials/)
+for how provider secrets, credentials, and runtime wiring fit together. Without
+the backing secret/credential for a provider an agent declares, its sessions fail
+to start with `reading secret <provider>-creds ... not found`.
+
 ## 6. Troubleshooting
 
 Common causes when ACP commands do not show the vTeam records:
 
 - `make kind-port-forward` is not running.
 - `acpctl` is logged into the wrong backend port.
 - The lab worktree cluster is not running.
-- The vTeam manifests have not been applied yet.
+- The vTeam manifests have not been applied yet (step 4).
 
 Useful reset commands:
 
@@ -203,12 +229,11 @@ current backend port from `make kind-status`.
 
 ## 7. Optional: Start A Work Packet Session
 
-Starting real sessions needs provider secrets and an OpenShell gateway for the
-`vteam-product-swarm` namespace. The default `OPENSHELL_TENANTS` includes
-`vteam-product-swarm`, so the namespace and gateway are provisioned
-automatically during `make kind-up`.
+Starting real sessions needs the provider secrets from step 5 and the OpenShell
+gateway. Both come from the catalog apply (step 4) plus your credentials — the
+gateway StatefulSet is deployed by the control plane once the namespace exists.
 
-After those runtime prerequisites are available, start Stella with the demo work
+Once those runtime prerequisites are available, start Stella with the demo work
 packet:
 
 ```bash

examples/vteam-catalog/README.md

@@ -70,9 +70,9 @@ The provider declarations reference these Kubernetes Secret names:
 - `github-creds`
 - `jira`
 
-Create those secrets in the project namespace before starting sessions that need
-the providers. Applying the catalog creates the ACP records; missing provider
-secrets become runtime issues when an agent session starts.
+Applying the catalog creates the project and its namespace; create these secrets
+in that namespace before starting sessions that need the providers. Missing
+provider secrets become runtime issues when an agent session starts.
 
 ## Codebase Maintainers
 
@@ -110,6 +110,6 @@ The provider declarations reference these Kubernetes Secret names:
 - `github-creds`
 - `runtime-kubeconfig`
 
-Create those secrets in the project namespace before starting sessions that need
-the providers. Applying the catalog creates the ACP records; missing provider
-secrets become runtime issues when an agent session starts.
+Applying the catalog creates the project and its namespace; create these secrets
+in that namespace before starting sessions that need the providers. Missing
+provider secrets become runtime issues when an agent session starts.

scripts/setup-kind-openshell.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Install OpenShell gateway prerequisites into a Kind cluster (dual-tenant mode).
+# Install OpenShell gateway prerequisites into a Kind cluster (multi-tenant mode).
 # Called by `make kind-up OPENSHELL_USE_GATEWAY=true`.
 #
 # Provisions for each tenant in OPENSHELL_TENANTS (default: tenant-a tenant-b):
@@ -19,7 +19,7 @@ set -euo pipefail
 NAMESPACE="${NAMESPACE:-ambient-code}"
 AGENT_SANDBOX_VERSION="${AGENT_SANDBOX_VERSION:-v0.5.1}"
 # Space-separated list of tenant namespaces to provision
-IFS=' ' read -ra TENANTS <<< "${OPENSHELL_TENANTS:-tenant-a tenant-b vteam-product-swarm codebase-maintainers}"
+IFS=' ' read -ra TENANTS <<< "${OPENSHELL_TENANTS:-tenant-a tenant-b}"
 
 echo "Setting up OpenShell gateway prerequisites (tenants: ${TENANTS[*]})..."
 
@@ -192,8 +192,11 @@ else
 fi
 echo "  Note: ambient-ui gateway mode is baked in at build time via --build-arg OPENSHELL_USE_GATEWAY=true"
 
-# Vertex credentials and tenant overlays (examples/overlays/<tenant>/) are
-# applied by `make kind-up` after this script finishes — see the
-# setup-vertex-provider.sh calls in the Makefile.
+# After this script finishes, `make kind-up` applies the fleet overlay for any
+# tenant that has one at examples/overlays/<tenant>/ (currently tenant-a, tenant-b).
+# The vTeam catalog lab (examples/vteam-catalog/) is NOT provisioned here — it is
+# self-contained: the user's `acpctl apply -k examples/vteam-catalog/...` creates the
+# project, and the control plane reconciler provisions the namespace + gateway from
+# that record. See examples/vteam-catalog/QUICKSTART.md.
 
 echo "OpenShell gateway setup complete (${TENANTS[*]})."