distill: best practices from 2026-04-19 cross-project run

Adds 3 new topic files (ai-parallel-agents, api-integration,
python-patterns) and extends 21 existing topic files with new gotchas
and patterns surfaced from memory across tracked projects. Index
updated accordingly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

secrets-management.md

@@ -26,12 +26,22 @@ Each Ansible project needs `vars_plugins_enabled = host_group_vars,community.sop
 
 ## Credential Handling
 
-- **Never pass secrets via command-line arguments** — visible in `ps` output
+- **Never pass secrets via command-line arguments** — visible in `ps` output to any process in the PID namespace, including other containers sharing the namespace
 - Use `@file` references, environment variables sourced at runtime, or stdin
 - For Ansible, use temp files with `trap rm` cleanup: `-e "@${tmpfile}"`
 - Read secrets at execution time and use them ephemerally — never cache or persist values
 - Reference the **existence** of a secret file in docs, never its contents
 
+### Container Entrypoints
+
+The `ps`-visibility problem is especially easy to hit in container entrypoints that wrap a CLI tool. Passing credentials as argv is visible to every process in the PID namespace. Pattern:
+
+1. Write the credential to a temp file inside the container
+2. Use the tool's file-based import flag (e.g. `workspace import <file>`, `--credentials-file`, `@file`)
+3. `rm -f` the temp file before exec-ing the main process
+
+Prefer stdin, env vars, or `@file` references over argv in every entrypoint script.
+
 ## Bootstrap Secrets
 
 Some secrets are chicken-and-egg (e.g., the age decryption key for ArgoCD's KSOPS). These must be created manually as a bootstrap step and documented clearly.
@@ -114,3 +124,27 @@ Shell `source` on .env files executes arbitrary commands — a crafted file with
 ## URL-Safe Password Generation
 
 Generated passwords that appear in connection strings (DATABASE_URL, AMQP URLs, etc.) must use URL-safe characters only: `A-Za-z0-9._-`. Characters like `^`, `@`, `:`, `/`, `+` break URL parsing in libraries like SQLAlchemy. Prevention via charset restriction is simpler and more reliable than URL-encoding passwords after generation.
+
+## Scope Secret Delivery Per-Workload
+
+When a harness or container environment makes secrets available (SSH keys, API tokens, credentials mounts), scope each secret to the specific workloads that need it. Global forwarding — mounting all credentials into every container or injecting all secrets into a shared env — leaks credentials to workloads that shouldn't have them.
+
+**Anti-pattern:** Inject the Gitea admin token, Anthropic API key, and SSH private key into every agent container regardless of task.
+
+**Pattern:** Use capability harness layers that compose per-task. A spec-planning task gets the planning context + SSH key. A code-review task gets the code-review context + API token. A read-only analysis task gets no write credentials at all.
+
+This also limits blast radius when an agent is compromised or misbehaves — it can only escalate within the credentials it was explicitly given.
+
+## Admin vs User API Tokens — Verify `is_admin` Before Assuming Scope
+
+Not every token labelled "admin" has the platform's `is_admin` flag. Gitea's `cluster-administrator` user is a cluster admin but not a site admin — its token returns 403 on admin-API endpoints.
+
+**When a token fails with 403 on admin endpoints:**
+
+1. Don't assume the token is wrong or expired
+2. Check `GET /users/<owner>` — look for `"is_admin": true` on the owning user
+3. If `is_admin: false`, the token's owner lacks the platform privilege; a different user's token is required
+
+**Gitea `Sudo` header quirk:** creating tokens on behalf of other users via the `Sudo` header returns 401 with a token. Use basic auth for that specific operation.
+
+The general lesson: "admin" is overloaded (org admin vs site admin vs cluster admin vs repo admin). Always confirm which scope a token actually carries before blaming the token.