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>

octopus-process-templates.md

@@ -190,13 +190,59 @@ packages "MyPackage" {
 - Keep major bumps for breaking changes (parameter renames, step removals)
 - Minor/patch for new optional parameters, script improvements, bug fixes
 
+## Dual-Image / Multi-Registry Channel Pattern
+
+When a project builds distinct images to separate registries per environment tier (e.g., non-prod vs prod), model each registry as its own **Feed** and create **one channel-scoped deployment step per feed**. Two channel-scoped steps are cleaner than a single step with version rules, because differing `PackageId` values (`org-nonprod/app` vs `org-prod/app`) cannot both be satisfied by a single step's package reference.
+
+```hcl
+step "deploy-nonprod" {
+    action {
+        channels = ["non-prod"]
+        packages "app" {
+            feed = "registry-nonprod"
+            package_id = "org-nonprod/app"
+        }
+    }
+}
+
+step "deploy-prod" {
+    action {
+        channels = ["prod"]
+        packages "app" {
+            feed = "registry-prod"
+            package_id = "org-prod/app"
+        }
+    }
+}
+```
+
+## Release Creation: CI-Driven vs Feed Triggers
+
+Octopus feed triggers silently ignore non-SemVer Docker tags (e.g., `sha-abc12345`) and poll on a ~3-minute interval. For SHA-tagged workflows or any non-SemVer scheme:
+
+- **Preferred:** have CI `POST /api/releases` directly after pushing the image. This is instant, avoids simultaneous-trigger race conditions on `UQ_ReleaseVersionUnique`, and works with any tag format.
+- **Alternative:** tag with SemVer plus a timestamp build number (`1.2.3+YYYYMMDDHHMM`) for guaranteed uniqueness without needing external state.
+
+Feed triggers remain fine for pure-SemVer tag schemes.
+
+## Channel Version Rules and Enforcement
+
+Channel version rules require **either a version range or a pre-release tag** — they cannot be empty. For non-SemVer tagging schemes, remove all rules (`Rules: []`) and rely on step channel-scoping (`action.channels`) for enforcement instead.
+
+The **default channel** on any project cannot be deleted; either leave it unused or promote another channel to default before removing it.
+
+## Auto-Promoting Lifecycles for Hands-Free Demos / PoCs
+
+To demonstrate a full CI-to-deployed flow, set lifecycle phases to auto-deploy by moving environments from `OptionalDeploymentTargets` to `AutomaticDeploymentTargets`. Pair a non-prod lifecycle (Dev → Staging) with a prod lifecycle (Staging → Production) so each channel's releases promote automatically once created.
+
 ## Gotchas
 
 1. **Step templates are space-scoped.** Process templates in Platform Hub cannot reference `ActionTemplates-*` IDs from other spaces. If you need reusable steps, use inline `action_type = "Octopus.Script"` in the process template OCL. Step templates are useful within a single space's projects, but not for cross-space process templates.
-2. **Process template names** cannot contain parentheses, slashes, or ampersands — only letters, numbers, periods, commas, dashes, underscores, and hashes.
+2. **Process template names** cannot contain parentheses, slashes, or ampersands — only letters, numbers, periods (`.`), commas (`,`), dashes (`-`), underscores (`_`), and hashes (`#`).
 3. **Heredoc for multi-line scripts** — use `<<-EOT` / `EOT` for PowerShell scripts that contain double quotes. The `-` prefix allows indented closing tags.
 4. **Every step needs a worker pool.** Process templates must have a `worker_pool` parameter (type `WorkerPool`), and every action must set `worker_pool_variable = "worker_pool"` referencing it. Without this, the template will fail to parse with "A step must specify a worker pool parameter".
 5. **Publishing and sharing is UI-only.** Process template sharing (which spaces can see/use a template) is stored in the Octopus database, not in Git/OCL. You must publish and share each template through the UI. There is no API or CLI for this currently.
+6. **Space creation via API requires a manager.** `POST /api/spaces` rejects an empty `SpaceManagersTeamMembers` with "select either teams and/or users as managers". Always include at least one user ID.
 
 ## Best Practices