docs: add container TLS, network ecosystem, and MCP diagnostics guidance

- Add CA cert mount pattern for scratch/distroless container images
- Document ecosystem identifiers vs custom domains (strict: false)
- Add npx/uvx package registry access requirements
- Add MCP gateway log diagnostics to debugging checklist
- Add entrypointArgs and mounts fields to MCP server schema
- Add critical rules #13-#16 for container TLS, strict mode, ecosystems, MCP logs

Author: zircote

skills/aw-author/SKILL.md

@@ -383,3 +383,7 @@ These rules apply across ALL modes:
 10. **`read-all` permission shorthand** expands to read on all permission scopes
 11. **`event.json` fallback** — when `${{ github.event }}` is unavailable, agents should check for `event.json` in the workspace
 12. **Container-based MCP servers from `ghcr.io` require a GHCR login step** — add a `steps:` block with `docker login ghcr.io` using `${{ github.token }}` before `safe-outputs:`, or container pulls fail silently
+13. **Minimal/scratch Docker images have no CA certificates** — if a container-based MCP server uses `FROM scratch` or a distroless base, mount host certs with `mounts: ["/etc/ssl/certs:/etc/ssl/certs:ro"]` and set `SSL_CERT_FILE: "/etc/ssl/certs/ca-certificates.crt"` in `env:`, or TLS calls fail with "certificate verify failed"
+14. **`strict: false` is also required for custom API domains** — ecosystem identifiers (`defaults`, `github`, `containers`, `node`, `python`) work in strict mode, but custom domains like `*.datadoghq.com` require `strict: false`
+15. **Add `node` and `python` ecosystems** when MCP servers use `npx` or `uvx` — these ecosystems allow package registry access (npm, PyPI) needed for process-based MCP servers
+16. **MCP gateway logs are the primary debug source** — when MCP tool calls return vague errors (e.g., "no data found"), download `agent-artifacts/mcp-logs/{server}.log` from the workflow run to see the real error (TLS failures, auth errors, timeouts)

skills/aw-author/references/frontmatter-schema.md

@@ -238,6 +238,32 @@ network:
 - Use `network: true` for unrestricted (discouraged)
 - Prefer explicit domain allowlists
 
+### Ecosystem Identifiers vs Custom Domains
+
+Ecosystem identifiers work in strict mode (`strict: true`, the default):
+- `defaults` — standard GitHub/Actions infrastructure
+- `github` — GitHub API and related domains
+- `containers` — Docker Hub, GHCR (`ghcr.io`), Quay
+- `node` — npm registries (needed for `npx`-based MCP servers)
+- `python` — PyPI (needed for `uvx`-based MCP servers)
+
+**Custom domains require `strict: false`.** Any domain not covered by an ecosystem identifier (e.g., `*.datadoghq.com`, `api.pagerduty.com`, `*.atlassian.net`) requires setting `strict: false` at the frontmatter root level, or the compiler rejects it.
+
+```yaml
+strict: false
+
+network:
+  firewall:
+    allowed:
+      - defaults
+      - github
+      - containers
+      - node
+      - python
+      - "*.datadoghq.com"
+      - "api.pagerduty.com"
+```
+
 ## Imports (`imports:`)
 
 ```yaml
@@ -263,6 +289,28 @@ mcp-servers:
     allowed: ["tool_name"]
 ```
 
+### Container-Based MCP Servers
+
+```yaml
+mcp-servers:
+  server-name:
+    container: "ghcr.io/org/image:tag"
+    entrypointArgs:
+      - "subcommand"
+    env:
+      API_KEY: "${{ secrets.VALUE }}"
+      SSL_CERT_FILE: "/etc/ssl/certs/ca-certificates.crt"
+    mounts:
+      - "/etc/ssl/certs:/etc/ssl/certs:ro"
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entrypointArgs` | list | Arguments passed to the container's ENTRYPOINT |
+| `mounts` | list | Volume mounts in `"host:container:mode"` format |
+
+**CA Certificate Warning:** Containers built from `FROM scratch` or distroless base images have no CA certificate bundle. Without CA certs, all TLS connections fail with "certificate verify failed". Mount the host's CA certs read-only and set `SSL_CERT_FILE` to point to them.
+
 ## Complete Example
 
 ```yaml

skills/aw-author/references/tools-reference.md

@@ -252,10 +252,12 @@ mcp-servers:
 | `command` | string | Executable path (process-based) |
 | `args` | list | Command arguments |
 | `container` | string | Docker image reference (alternative to command) |
+| `entrypointArgs` | list | Arguments passed to container ENTRYPOINT |
 | `url` | string | HTTP endpoint (alternative to command) |
 | `headers` | mapping | HTTP headers for url-based servers |
 | `registry` | string | MCP registry URI (informational only, does not affect execution) |
 | `env` | mapping | Environment variables |
+| `mounts` | list | Volume mounts in `"host:container:mode"` format |
 | `allowed` | list | Tool name restrictions |
 
 ### Execution Modes
@@ -296,6 +298,30 @@ steps:
 
 This applies to **all** container-based MCP servers pulling from `ghcr.io`, regardless of whether the image is public or private. The `github.token` is automatically available and has sufficient scope for package reads.
 
+### CA Certificates for Minimal Images
+
+Containers built from `FROM scratch` or distroless base images have **no CA certificate bundle**. Any TLS connection (HTTPS API calls) will fail with "certificate verify failed". The MCP tool may return a misleading error (e.g., "no data found") instead of the real TLS error — check `agent-artifacts/mcp-logs/{server}.log` for the actual failure.
+
+**Fix:** Mount the host runner's CA certs and set `SSL_CERT_FILE`:
+
+```yaml
+mcp-servers:
+  my-server:
+    container: ghcr.io/org/image:latest
+    env:
+      SSL_CERT_FILE: "/etc/ssl/certs/ca-certificates.crt"
+    mounts:
+      - "/etc/ssl/certs:/etc/ssl/certs:ro"
+```
+
+### Package Registry Access for Process-Based Servers
+
+Process-based MCP servers using `npx` or `uvx` need package registry access at runtime:
+- **`npx` servers** — add `node` to `network.firewall.allowed` (covers npm registries)
+- **`uvx` servers** — add `python` to `network.firewall.allowed` (covers PyPI)
+
+These ecosystem identifiers work in strict mode and do not require `strict: false`.
+
 ### Key Constraints
 
 - Tool declarations merge from imported components

skills/aw-author/references/validation.md

@@ -50,6 +50,10 @@ Occur during GitHub Actions execution.
 - **Network blocked:** External URL access when no `network` configuration
 - **MCP server connection failed:** Server not available, wrong args, missing env vars
 - **Container pull failed (silent):** Container-based MCP servers from `ghcr.io` fail silently if no GHCR login step is present. Add a `steps:` block with `docker login ghcr.io` using `${{ github.token }}`
+- **TLS certificate verify failed:** Container-based MCP servers built from `FROM scratch` or distroless images have no CA certificate bundle. Mount host certs: `mounts: ["/etc/ssl/certs:/etc/ssl/certs:ro"]` and set `SSL_CERT_FILE: "/etc/ssl/certs/ca-certificates.crt"` in `env:`
+- **MCP server registers no tools (`tools: None`):** Server started but returned empty tool list — usually caused by an init-time API call failure (check MCP gateway logs for auth errors or TLS failures)
+- **Misleading tool error messages:** MCP tool errors like "no data found" may mask underlying TLS, auth, or network failures — always check `agent-artifacts/mcp-logs/{server}.log` for the real error
+- **Firewall blocking MCP traffic:** If firewall logs show only `api.openai.com` with no other domains, the MCP containers' API calls are being blocked — add the required API domains to `network.firewall.allowed` with `strict: false`
 
 ### Permission Errors
 - **Token insufficient:** `GITHUB_TOKEN` lacks required scope
@@ -116,6 +120,9 @@ The workflow runs but produces incorrect or unexpected results.
 | Overlapping triggers | Double-processing | Use distinct event types |
 | `container:` with non-Docker value | Compilation error | Use valid Docker image reference |
 | `container: ghcr.io/…` without GHCR login step | Silent runtime failure | Add `steps:` with `docker login ghcr.io` |
+| `container:` from scratch/distroless without CA certs | TLS calls fail silently | Add `mounts` + `SSL_CERT_FILE` env |
+| Custom API domains without `strict: false` | Compiler rejects non-ecosystem domains | Set `strict: false` in frontmatter |
+| Missing `node`/`python` ecosystem for npx/uvx MCP servers | Package install fails at runtime | Add `node`/`python` to network allowed |
 
 ### Prose Anti-Patterns
 
@@ -167,8 +174,22 @@ When a workflow fails, check in this order:
 - [ ] Edge cases handled
 - [ ] Output format matches safe-output types
 
-### 6. Runtime
+### 6. Network & TLS
+- [ ] Custom API domains (e.g., `*.datadoghq.com`) present in `network.firewall.allowed`
+- [ ] `strict: false` set if custom domains are used (ecosystem identifiers like `defaults`, `github`, `containers`, `node`, `python` work in strict mode; custom domains do not)
+- [ ] `node` ecosystem included if MCP servers use `npx` (for npm registry access)
+- [ ] `python` ecosystem included if MCP servers use `uvx` (for PyPI access)
+- [ ] Container-based MCP servers from minimal/scratch images have CA cert mounts (`mounts: ["/etc/ssl/certs:/etc/ssl/certs:ro"]` + `SSL_CERT_FILE` env var)
+
+### 7. Runtime
 - [ ] Timeout sufficient for task complexity
 - [ ] Engine configured correctly (API key secret present)
 - [ ] No circular imports
 - [ ] No conflicting workflows on same trigger
+
+### 8. MCP Server Diagnostics
+- [ ] Download `agent-artifacts/mcp-logs/{server}.log` from workflow run to see real errors (tool error messages can be misleading)
+- [ ] Check firewall logs — if only `api.openai.com` appears with no other domains, MCP containers are not reaching external APIs
+- [ ] Look for `tools: None` in MCP capability announcements — indicates the server started but registered no tools (likely an auth or init failure)
+- [ ] Check for silent secret failures — missing or empty `COPILOT_MCP_` secrets cause MCP servers to start but fail on first API call
+- [ ] Verify `SSL_CERT_FILE` env var is set for containers that mount host CA certs