@codiac.io/codiac-cli 1.3.244 → 1.3.246

package/skill/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: codiac
+description: >-
+  Operate the Codiac platform through the `cod` CLI (and, secondarily, the NATS relay API).
+  Use this whenever a task touches Codiac at all: deploying or managing assets/workloads,
+  editing scoped configuration or secrets, working with enterprises, environments, cabinets,
+  clusters, image registries, CSP/cloud profiles, hosts/ingress, or agents — or any time you
+  are about to type a `cod ...` command or reason about how Codiac deploys things. Reach for it
+  even when the user doesn't say "Codiac" but names a Codiac concept (asset, cabinet, scoped
+  setting, enterprise, environment, cluster, CSP profile, EVC). Its whole job is to stop you
+  guessing cod commands, subcommands, args, and flags — the CLI is self-documenting, and this
+  skill gives you the concept model plus the one habit that prevents almost every mistake:
+  read `cod <topic> <verb> --help` before you call a command you are not certain of.
+---
+
+# Codiac
+
+You are operating **Codiac** — a platform that deploys and manages workloads on Kubernetes
+clusters. Your tool is the **`cod` CLI**. Data operations also flow over a **NATS relay API**,
+but the CLI is the primary, safe surface and you should prefer it.
+
+## The one thing that matters most
+
+**`cod` is self-documenting, and guessing is the failure mode.** Every command carries a
+description, every flag has its own description, and commands ship titled, copy-pasteable
+examples. So the fast path is never to recall a command from memory — it is:
+
+> **Before you run any `cod` command you are not 100% certain of, run `cod <topic> <verb> --help` and read it.**
+
+This is faster, not slower, than guessing. A guessed flag fails (or worse, silently does the
+wrong thing against a real cluster), costs a round-trip, and erodes trust. Reading `--help`
+costs one cheap call and makes the very next command correct.
+
+Why this is non-negotiable and not just good manners: **Codiac's flag characters collide across
+commands.** `-e` means *enterprise* in `cod asset list` and `cod config view`, but *environment*
+in `cod cabinet create`, `cod config add`, and `cod config settings get` (where enterprise is
+`-n`). Asset version is `-u`, not `-v`. On `cod asset deploy`, `-n` is a cloud username and `-t`
+is a cabinet tag. Several primary inputs (tenant code, cluster, provider, cabinet name) are
+**positional args, not flags**. There is no convention you can lean on — only `--help` is truth.
+See `references/cli-reference.md` for the collision map, but treat even that as orientation:
+`--help` on the specific command is the authority.
+
+## When you're working in this skill
+
+Most tasks are one of:
+- **Deploy / manage a workload** — `cod asset deploy`, `asset list`, `asset view`, `asset undeploy`, `asset recycle`.
+- **Read or change configuration / secrets** — `cod config view` (preview the resolved doc), `config add` (set a value), `config settings get` (inspect raw settings), scoped-setting work.
+- **Work with the topology** — enterprises, environments, cabinets, clusters, hosts/ingress.
+- **Cloud/registry auth** — `cod csp login` for a provider (Azure/AWS/DockerHub).
+- **Install an agent** — `cod ai agent install`.
+
+If you don't know which command a task maps to, skim the command tree in
+`references/cli-reference.md`, then `--help` the candidate.
+
+## Hold the concept model before you touch a command
+
+Codiac's mental model is small but easy to conflate. Get it wrong and you'll pass the wrong
+flag values even with perfect flag names. The essentials:
+
+- **tenant → enterprise → environment → cabinet → cluster.** A **tenant** is the account. An
+  **enterprise** is a workspace inside it (two *types* exist: normal/`sdlc` and `infrx` for
+  infrastructure — some commands enforce the type). An **environment** is a stage (dev/prod/…)
+  that **maps to a cluster** (the mapping is data-driven in the DB). A **cabinet** is a concrete
+  deployment target that lives **in an environment** — so it inherits that environment's cluster.
+- **Therefore `cod cabinet create` takes `--environment`, never `--cluster`.** Cabinets and
+  clusters are ephemeral over an underlying namespace; the env→cluster link is the source of truth.
+- **Asset** = a deployable workload (a `helm` chart or a `service`/container). Registered once,
+  versioned (AssetVersionConfig), then deployed into a cabinet.
+- **Scoped settings / config** are values attached at a **scope** — `enterprise`, `environment`,
+  or `cabinet` — where **cabinet overrides environment overrides enterprise**. Shareable config
+  belongs at the *highest* scope that makes sense (set once, inherited), with narrower scopes as
+  optional overrides. Cabinet-scoping something that should be shared is an anti-pattern.
+- The **EVC** (EnterpriseVersionConfig) is the versioned snapshot the platform actually reads;
+  deploys write it. Config can be a **literal value** or a **sourced** reference into a vault.
+
+That's enough to choose the right command and fill it correctly. For depth — targetFile types
+(`[helm]`/`[env]`/`[label]`/…), dotted-key/escaped-period behavior, `@{...}` templates, CSP
+profiles, the NATS API, and the full hierarchy — read `references/concepts.md`.
+
+## Running a `cod` command safely
+
+1. **Establish context.** Enterprise-scoped commands need a tenant (and often an enterprise).
+   `cod tenant switch <code>` sets the tenant; many commands take `--enterprise`. A deployed agent
+   usually already runs inside its tenant's context.
+2. **`--help` the exact command** unless you have literally just read it. Read the flag
+   descriptions and the examples — copy an example and adapt it rather than composing from scratch.
+3. **In automation / non-interactive shells, pass `--silent` and every required arg.** `--silent`
+   (and piped stdin, which auto-switches to silent) has **no prompt fallback** — a missing or
+   invalid required value throws instead of asking. Secrets that would normally be prompted are
+   fed via stdin (e.g. `cod csp login` password, `cod config add --value-stdin`).
+4. **Preview only in a real terminal — never headless.** `--echo`/`--to-script` render the
+   equivalent `--silent` command, but they run the *interactive* build first, so in a non-TTY they
+   **prompt and hang**. Headless, `--silent` is your safe mode: it validates and **throws** on a
+   missing/invalid arg (fast, never hangs) instead of prompting. To preview a command without
+   running it headless, build it from `--help` and simply don't execute — don't reach for
+   `--to-script`.
+5. **Reading a list?** List commands take `--output/-o` (`tree` default; `json`/`yaml`/… for
+   machines) and usually `--query/-q` (JMESPath). `-q` implies JSON; `tree`/`text` reject `-q`.
+
+## Operating a running workload (logs, status, events, exec, config)
+
+Almost everything about a live workload comes from **`cod asset view`** (and `cod cabinet contents`
+/ `cod asset list`) — reach for these first; read-only `kubectl` is only a fallback. `cod asset
+view` flags: `-e` enterprise, `-a` asset, `-n` environment, `-c` cabinet, `-r` replica (`any` =
+first, no prompt), `-t` content type.
+
+- **What's deployed** (returns + exits, headless-safe): `cod cabinet contents -e <ent> -c <cab>` and `cod asset list -e <ent> -o json`.
+- **Logs** (headless-safe): `cod asset view -t logs -e <ent> -a <asset> -n <env> -c <cab> -r any -l 50 --silent` — pass `-l N` for N lines (or `-l -1` for all); **omit `-f`** (follow streams forever).
+- **Exec / env / config**: `cod asset view -t exec|env|config …` (config also takes `-T <helm|env|label|annotation|…>`).
+- **Live status + events**: `cod asset view -t status` (aka `asset mon`) is an **interactive
+  streaming monitor** — great in a real terminal, but it does **not** return in a non-TTY/`--silent`
+  shell, so don't use it in automation. For a headless status snapshot, use `cabinet contents` /
+  `asset list` above. (For headless one-shot *events*, use `cod asset view -t events` — a
+  returns-and-exits events dump; `-l N` for count.)
+
+## Hard rules (each earns its place)
+
+- **Never invent a command, subcommand, or flag.** If it's not confirmed by `--help` or
+  `references/cli-reference.md`, verify before running. The grammar is strictly **noun-then-verb**
+  (`cod asset deploy`, `cod config settings get`) — never verb-first, never reordered.
+- **`cod` first — don't lead with `kubectl`.** Almost everything about a running workload is
+  available through `cod asset view` (logs, exec, env, config, live status+events) and
+  `cod cabinet contents` / `cod asset list` (what's deployed) — reach for those before the cluster.
+  Read-only `kubectl get`/`describe`/`logs` is a fine fallback for diagnosis (and the user may
+  explicitly okay it); the point is to rely on Codiac's own calls first, not to ban `kubectl`. The
+  one firm line: **never make a *write* through raw `kubectl`/`helm`** against a Codiac-managed
+  asset — that corrupts Codiac's tracked view (stale rootmap/UI); make changes through `cod`.
+- **Set `CODIAC_SESSION_ID` for a multi-step sequence** so every `cod` call shares one session
+  (otherwise steps can land in different sessions and lose context).
+- **Treat prod as prod.** Deploys, undeploys, and config changes act on real clusters. In doubt,
+  **read first** — `cod config view`, `cod cabinet contents`, `cod asset view` — before you write.
+
+## When something's missing
+
+If a task seems to have no `cod` command, the first instinct to resist is **hallucinating a flag**.
+Instead:
+1. Re-check `--help` on the most relevant command (especially `cod asset view --help` — logs,
+   exec, env, config, live status, and events all live there under `-t`).
+2. Check the command tree in `references/cli-reference.md` for a topic you haven't considered.
+3. If it's genuinely absent, **name the gap** so it can be added to `cod` — that's the durable fix.
+   A **read-only** `kubectl get`/`describe` check is an acceptable stopgap in the meantime (and the
+   user may okay it outright); just never a raw `kubectl`/`helm` *write* against a Codiac-managed
+   asset, and prefer getting the capability into `cod` over a standing `kubectl` habit.
+
+## Reference files
+
+- `references/cli-reference.md` — the command tree (every topic → verbs), the flag-character
+  collision map, the list/output (`-o`/`-q`) pattern, positional-arg gotchas, and the `--silent`
+  rules. Orientation only; `--help` on the specific command is authoritative.
+- `references/concepts.md` — the full Codiac mental model: the hierarchy and enterprise types,
+  assets and versioning, scoped configuration (scope/inheritance, targetFile types, sourced vs
+  literal, dotted keys and escaped periods, `@{...}` templates), the EVC/deploy model, CSP/cloud
+  auth, and the NATS relay API surface. Read it whenever a task goes past a single obvious command.

package/skill/references/cli-reference.md

@@ -0,0 +1,167 @@
+# `cod` CLI Reference (orientation)
+
+**This is orientation, not the source of truth.** `cod <topic> <verb> --help` is authoritative —
+it carries the exact current flags, their descriptions, and copy-pasteable examples. Use this file
+to (a) confirm a command *exists* and its noun-then-verb shape, and (b) stay alert to the traps
+below. Then `--help` the specific command and adapt one of its examples.
+
+## Command grammar
+
+- **Noun-then-verb, always.** `cod asset deploy`, `cod cluster stack install`,
+  `cod config settings get`. Never verb-first (`cod deploy asset` ✗), never reordered.
+- Directory-to-command mapping: `<topic>/<verb>` → `cod <topic> <verb>`; deeper nesting works too
+  (`asset probe list`).
+- A few real **camelCase** topics/verbs exist despite the single-word convention:
+  `imageRegistry`, `secretStore`, `pullSecret`, and `auth ... allow onEnvironments`/`onCabinets`.
+
+## Command tree (what actually exists — don't invent beyond this)
+
+Top-level: `branch`, `build`, `cli`, `commit`, `deploy`, `dep`, `identity`, `init`, `login`,
+`logout`, `merge`, `portal`, `publish`, `pull`, `push`, `relay-version`, `run`, `stage`, `stash`,
+`status`, `stop`, `switch`, `sync`, `unstage`, `whereami`, `whoami`.
+
+- **ai**: `ai agent install`
+- **asset**: `create`, `deploy`, `edit`, `list`, `obliterate`, `recycle`, `undeploy`, `view`, `where`; `entrypoint set/delete`; `probe create/delete/list`; `volume create/delete/list`
+- **auth**: `register`; `cabinet allow/allowed`; `enterprise allow/allowed/allow onEnvironments`; `environment allow/allowed/allow onCabinets`; `role create/delete/list/assign/unassign/allowed`; `user invite/list`
+- **cabinet**: `create`, `list`, `define`, `contents`, `destroy`, `detach`, `forget`, `obliterate`, `restore`; `cluster attach`
+- **cluster**: `connect`, `install`, `bootstrap`, `start`, `stop`; `agent configure/install/uninstall`; `scaling update`; `stack capture/install`
+- **config**: `add`, `delete`, `deploy`, `import`, `view`; `settings get`
+- **csp**: `login`, `logout`, `setup`, `creds list`
+- **enterprise**: `create`, `list`
+- **environment**: `create`, `delete`, `list`; `cluster attach/detach`
+- **env**: `add`  *(separate topic from `environment`)*
+- **filestore**: `capture`, `forget`, `list`
+- **host**: `map`, `list`, `view`, `delete`
+- **identity**: `list`, `delete`
+- **imageRegistry**: `capture`, `forget`, `list`; `pullSecret set/unset`
+- **images**: `add`, `list`, `patch`, `remove`, `version`, `version bump`
+- **import**: `cluster`
+- **kit**: `create`
+- **noc**: `noc cluster create/list/init/deinit/capture/restore/destroy/define/forget/grant/journal/credentials-set`
+- **pkg**: `add`, `list`, `patch`, `remove`
+- **pvc**: `create`, `get`, `list`, `delete`
+- **secretStore**: `capture`, `forget`, `list`
+- **snapshot**: `deploy`, `list`, `tag`, `tags`, `untag`
+- **tenant**: `create`, `switch`
+
+If a task seems to need a command not on this list, you're probably guessing — re-check the tree
+or `--help` the parent topic (`cod asset --help`, `cod config --help`) to see its verbs.
+
+## Interaction-mode flags (on nearly every command)
+
+| Flag | Meaning |
+|---|---|
+| `--silent` | Non-interactive. Runs with zero prompts and **throws on any missing/invalid required arg** — there is no prompt fallback. Pass every required value. |
+| `--echo` | Prints the equivalent `--silent` command string, then runs it. **Runs the interactive build first → prompts and HANGS in a non-TTY.** Interactive terminals only. |
+| `--to-script` | Prints the equivalent `--silent` command string without running it. Same trap: it does the interactive build first, so it **prompts and HANGS headless.** Not a headless dry-run — use it only in a real terminal. Headless, use `--silent` (throws on missing args, never hangs) and build the command from `--help`. |
+| `-h` / `--help` | Help + examples. (A couple of commands don't define it — see traps.) |
+| `--take-defaults` | Auto-accept default/context values without confirmation. |
+
+- The mode flags have **no char shortcut**; spell them exactly (`--silent`).
+- **Piped stdin auto-switches to silent** ("Piped input detected…"), so a piped command needs all
+  args too. Some commands read secrets from stdin in silent mode (`csp login` password,
+  `config add --value-stdin`).
+
+## The flag-character collision map (why you must `--help`)
+
+The same char means different things per command. **Never assume.**
+
+| Char | `asset deploy` | `asset view` | `config add` / `settings get` | `config view` | `csp login` | `cabinet create` | `ai agent install` |
+|---|---|---|---|---|---|---|---|
+| `-e` | enterpriseCode | enterprise | **enviro (environment)** | enterprise | — | **environment** | enterpriseCode |
+| `-n` | **provider username** | **environment** | **enterprise** | — | — | — | **workload name** |
+| `-u` | **version** | — | — | — | user | — | — |
+| `-t` | cabinet **tag** | **type** (content) | config **type** | config type | **tenantId** | — | agent **type** |
+| `-s` | applySnapshotTag | — | **enterprise-scope** (bool) | — | subscriptionId | — | — |
+| `-c` | cabinetName | cabinet | cabinet | cabinet | — | **cluster** | cabinet |
+| `-a` | asset | asset | asset | asset | — | — | — |
+| `-g` | applyAssetTag | — | — | — | — | — | ingress (`--no-ingress`) |
+
+Highlights that bite most often:
+- **`-e` is enterprise in some commands, environment in others.** In `config add` /
+  `config settings get`, enterprise is **`-n`** and `-e` is **`--enviro`**. `config view` uses
+  `-e` = enterprise. Verify per command every time.
+- **Asset version is `-u`, not `-v`.**
+- On `asset deploy`, `-n` = cloud username and `-t` = cabinet tag (not enterprise, not type).
+
+## Positional args (not flags)
+
+Several primary inputs are positional — passing them as `--flag` fails:
+
+| Command | Positional |
+|---|---|
+| `cod tenant switch <code>` | tenant code |
+| `cod cluster connect <cluster>` | cluster name |
+| `cod csp login <provider>` | provider (`aws`/`azure`/`docker`) |
+| `cod cabinet create <cabinet>` | cabinet name (env/cluster are flags: `--environment`, `--cluster`) |
+| `cod config view [setting]` | optional setting name |
+
+`csp login` and `cluster connect` don't even define `-h` — read their source/behavior, not `--help`.
+
+## List / read commands
+
+Commands that return a list support:
+- `--output` / `-o` — `tree` (default, human) · `json` · `yaml` · sometimes `text`/`tsv`/`csv`.
+- `--query` / `-q` — JMESPath, applied to the raw array. `-q` implies JSON; **`tree`/`text`
+  reject `-q`** (throws).
+
+Examples: `cod asset list -e main -q '[].name' -o json` · `cod cabinet list -e main -o yaml`.
+Exception: `cod config settings get` has **no `-q`** — filter with `--setting`/`--value` globs — and
+defaults to `json`. `cod config view` uses a different format enum (`pretty`/`json`/`yaml`/`auto`).
+
+## `cod asset view` — operating a running workload (no kubectl)
+
+Flags: `-e` enterprise · `-a` asset · `-n` **environment** · `-c` cabinet · `-r` replica (`any` =
+first, no prompt) · `-t` content type. The `-t` (`AssetContentType`) values are exactly:
+
+| `-t` | What it does | Headless-safe? |
+|---|---|---|
+| `logs` | container logs; `-l N` lines (`-l -1` = all); `-f` follows (streams forever — omit headless) | ✅ with `-l N`, no `-f` |
+| `env` | resolved env vars | ✅ |
+| `config` | resolved config (`-T <helm\|env\|label\|annotation\|…>` or `-F <file>`) | ✅ |
+| `exec` | run a command in a replica (positional cmd after `--`) | interactive |
+| `term` | shell into a replica | interactive only |
+| `events` | recent k8s events for the asset (returns + exits; `-l N` count, default 25) | ✅ **use this for headless events** |
+| `status` | **live streaming monitor** (aliases `asset:monitor`/`asset:mon`) — status + events, updating | ❌ **never returns in a non-TTY** (interactive only) |
+
+For events in a script use **`cod asset view -t events`** — it fetches once, prints, and exits
+(unlike `-t status`, which streams). It works even when pods aren't up (that's when events matter:
+ImagePullBackOff, FailedScheduling, CrashLoopBackOff), and works for `helm` assets too, not just
+`service`. Example: `cod asset view -t events -e main -a hello-web -n dev -c demo -l 20 --silent`.
+For a plain status snapshot, `cod cabinet contents` / `cod asset list` also return and exit. No
+`kubectl` needed.
+
+## A few verified recipes (adapt via `--help`)
+
+```bash
+# switch tenant (positional code)
+cod tenant switch ben --silent
+
+# preview the resolved config a cabinet will deploy with (best "what will happen?" check)
+cod config view -e main -a hermes-agent -c dev -o pretty --silent
+
+# set a helm value at enterprise scope (note: -n = enterprise, -e would be enviro here)
+cod config set -n main -a hermes-agent -t helm --setting model --value 'openai/gpt-4o-mini' -s --silent
+
+# inspect raw scoped settings (is it set, and where?)
+cod config settings get -n main -a hermes-agent -t helm -o json --silent
+
+# create a cabinet in an ENVIRONMENT (the target is --environment; --cluster is OPTIONAL and
+# defaults to the environment's first cluster — only pass it to disambiguate a multi-cluster env)
+cod cabinet create dev --enterprise main --environment dev --silent
+
+# what's deployed in a cabinet (headless-safe)
+cod cabinet contents -e main -c dev --silent
+
+# deploy an asset version into a cabinet (version is -u!)
+cod asset deploy -e main -a my-service -u 1.0.0 -c dev --silent
+
+# cloud/registry auth (provider positional; secret via stdin)
+cat pw.txt | cod csp login -u me@example.com --silent docker
+
+# connect kubectl to a Codiac cluster (positional name)
+cod cluster connect my-cluster --silent
+```
+
+Every one of these was read from source, but flags evolve — if a recipe errors, `--help` the
+command and re-derive it. That habit, not this file, is what keeps you correct.

package/skill/references/concepts.md

@@ -0,0 +1,244 @@
+# Codiac Concept Model
+
+The mental model an agent must hold to operate Codiac correctly. These concepts are compact but
+easy to conflate; getting them straight is what lets you pick the right command and fill its
+arguments with the right *values* (flag names you get from `--help`, but the *meaning* of the
+values comes from here).
+
+> Rule of thumb: if you catch yourself unsure what a term means (is a cabinet a cluster? does
+> config live on the asset or the cabinet?), stop and re-read the relevant section. A wrong
+> mental model produces confident, wrong commands.
+
+## Contents
+1. [The topology: tenant → enterprise → environment → cabinet → cluster](#1-the-topology)
+2. [Assets: the deployable unit](#2-assets)
+3. [Scoped configuration and secrets](#3-scoped-configuration-and-secrets)
+4. [Versioning and the deploy model](#4-versioning-and-the-deploy-model)
+5. [Cloud/registry auth (CSP)](#5-cloudregistry-auth-csp)
+6. [Hosts and ingress](#6-hosts-and-ingress)
+7. [The API surface (NATS, not HTTP)](#7-the-api-surface)
+8. [Agents on Codiac](#8-agents-on-codiac)
+
+---
+
+## 1. The topology
+
+Codiac nests five things. Keep them in this order:
+
+```
+tenant → enterprise → environment → cabinet → cluster
+```
+
+- **Tenant** — the account boundary (e.g. `ben`, `cod`). Everything you do happens inside one
+  tenant. A CLI session has a *current tenant*; set it with `cod tenant switch <code>`. A deployed
+  agent typically already runs inside its own tenant's context.
+- **Enterprise** — a workspace within a tenant (e.g. `main`). A tenant can have several. There are
+  **two enterprise *types***:
+  - normal / **`sdlc`** — where your application workloads live.
+  - **`infrx`** — infrastructure enterprise, holding cluster-scoped components (operators, agents,
+    platform stacks). Some commands are "infrx-only" or "sdlc-only" and will auto-switch or reject
+    based on type. If a command complains about enterprise type, you're likely in the wrong one.
+- **Environment** — a stage inside an enterprise (e.g. `dev`, `prod`). **An environment maps to a
+  cluster** (or clusters). The mapping is **data-driven in the DB**, not something you pass on the
+  command line — which is why you attach clusters to environments (`cod environment cluster attach`),
+  not to cabinets.
+- **Cabinet** — the concrete deployment target: a named slot inside an environment where assets get
+  deployed. Because a cabinet lives in an environment, it **inherits that environment's cluster**.
+  A cabinet corresponds to a Kubernetes namespace (typically `<tenant>-<cabinet>`, e.g. `ben-dev`).
+- **Cluster** — the actual Kubernetes cluster. Cabinets and clusters are *ephemeral over the
+  underlying namespace*; the durable link is environment → cluster.
+
+**The trap this prevents:** `cod cabinet create` takes **`--environment`**, never `--cluster`.
+You create a cabinet in an environment; the cluster comes along via the env mapping. Trying to
+pass a cluster to `cabinet create` is a classic mistake.
+
+Related commands: `cod enterprise list`, `cod environment list/create`,
+`cod environment cluster attach/detach`, `cod cabinet create/list/destroy`,
+`cod cluster connect/list`. (Always `--help` for exact flags — see the CLI reference.)
+
+---
+
+## 2. Assets
+
+An **asset** is a deployable workload. Two kinds matter:
+
+- **`helm`** — deployed from a Helm chart (chart identity lives on the asset's image ref:
+  chart name + registry + version).
+- **`service`** (container) — Codiac builds a Deployment for it from a container image.
+
+Lifecycle:
+1. **Register** the asset once (`cod asset create`) — this records its identity in the enterprise.
+2. **Version** it — a specific version is captured as an `AssetVersionConfig`.
+3. **Deploy** a version into a cabinet (`cod asset deploy`). Deploy is idempotent-ish
+   (`helm upgrade --install` under the hood for helm assets).
+4. Inspect/operate: `cod asset list`, `cod asset view` (logs/term/exec/env/config/status),
+   `cod asset undeploy`, `cod asset recycle`.
+
+**Image registries — policy:** never AWS ECR. Images live in **Docker Hub** or **Azure
+Container Registry (ACR)**. Registries are captured as first-class objects
+(`cod imageRegistry ...`, `cod secretStore ...` for pull secrets).
+
+The `type` of an asset (`helm` vs `service`) changes which config `targetFile`s apply (see §3):
+`[helm]` values for charts, `[env]`/`[footprint]`/etc. for services.
+
+---
+
+## 3. Scoped configuration and secrets
+
+This is the richest — and most misunderstood — part of Codiac. Configuration is **not** stored
+on the asset as one blob. It is a set of **scoped settings** that get *smash-merged* into a config
+document at deploy time.
+
+### Scope and inheritance
+Every setting has a **scope**, one of:
+
+- `enterprise`
+- `environment`
+- `cabinet`
+
+**Precedence: cabinet overrides environment overrides enterprise.** A cabinet-scoped value wins
+for that cabinet; otherwise the value is *inherited* from the environment, then the enterprise.
+
+**Design principle:** put shareable config at the **highest** scope that makes sense — set it
+*once* at the enterprise, let every cabinet inherit it, and add a narrower (cabinet/environment)
+override only when a specific target genuinely differs. Cabinet-scoping something that should be
+shared is an anti-pattern: it breaks reproducibility (every new cabinet would need it re-set) and
+a stray empty cabinet override silently shadows a good enterprise value.
+
+### targetFile — where a setting lands at runtime
+A setting's `targetFile` says *what artifact it becomes*:
+
+| targetFile | Becomes |
+|---|---|
+| `[helm]` | a Helm chart value (`.Values.<path>`) for a helm asset |
+| `[env]` | an OS environment variable on the container |
+| `[footprint]` | container resource footprint (cpu/mem requests/limits) |
+| `[label]` | a Kubernetes label |
+| `[annotation]` | a Kubernetes annotation |
+| `[filestore]` | a mounted file/volume value |
+| a file path (e.g. `app-config.json`) | a key inside that config file |
+
+Choosing the wrong `targetFile` is a common error — e.g. putting a helm chart value under `[env]`
+(where Codiac builds Deployments for *service* assets) instead of `[helm]`.
+
+### Literal value vs sourced reference
+A setting's value is either:
+- a **literal** `value` (stored directly), or
+- a **sourced** reference (`KvpReference`) that points into a **vault / KVP store** — the concrete
+  value is resolved at deploy time. This keeps secrets out of the config records. Sourcing requires
+  a vault store to exist for the tenant.
+
+### Dotted keys and the escaped-period trap
+A setting *key* can be a dotpath — e.g. `dashboard.password` — which **nests** into the config
+document (`{ dashboard: { password: ... } }`) via an object-flattener. Consequences you must
+respect:
+- The dot is a **hierarchy delimiter**. `ingress.host` sets `.Values.ingress.host` in a helm chart.
+- Internally, dotted keys are **stored with escaped periods (`\.`)**. An exact-string match on the
+  raw dotted key can silently miss — normalize `\.`→`.` when comparing, and don't assume a naive
+  query on a dotted name will match.
+- **Vault key names can't contain dots** (Azure Key Vault allows only `[0-9A-Za-z-]`). When a
+  dotted key is sourced into a vault, the vault key must be sanitized (dots→dashes) or it fails to
+  round-trip and resolves empty.
+
+### Templates (`@{...}`)
+Setting values can be **view-engine templates** resolved per target. Example ingress host:
+`@{asset.name}.@{cabinet.name}.@{environment.name}.example.com` — one enterprise-scope value that
+resolves to a different concrete host in each cabinet. Prefer a shareable template at enterprise
+scope over a concrete value re-computed per cabinet.
+
+### Commands
+- `cod config view` — **preview the resolved config doc** for a cabinet (all scopes merged,
+  sources resolved). Your best "what will actually deploy?" check.
+- `cod config add` (alias `config set`) — set a scoped setting (`--setting`, `--value` /
+  `--value-stdin`, scope via `--enterprise-scope`/`--enviro`/`--cabinet`, `--type` = targetFile).
+- `cod config settings get` — inspect the *raw* stored settings (filter by `--setting`/`--value`
+  globs). Good for "is this set, and at what scope?".
+
+> Flag caution: in `config add` and `config settings get`, **`-n` = enterprise and `-e` =
+> environment (`--enviro`)** — the reverse of the usual `-e = enterprise`. `config view` uses
+> `-e = enterprise`. Always `--help`.
+
+---
+
+## 4. Versioning and the deploy model
+
+- **AssetVersionConfig** — a specific captured version of an asset.
+- **EnterpriseVersionConfig (EVC)** — the **versioned snapshot of the enterprise's state** that the
+  platform reads (the rootmap the CLI shows is derived from it). A cabinet points at an EVC version.
+- **Deploy** (`cod asset deploy`, or the relay `invokeDeploymentSequence`) records the deployed
+  asset+version into the enterprise state. The relay writes EVCs through a `getsertVersion` call and
+  creates a **DeployAttempt** record for each deploy.
+- **Snapshots** (`cod snapshot ...`) tag enterprise states so they can be re-deployed/rolled.
+
+Why it matters: many downstream systems (status/UI, the asset→label mapping publisher) read the
+**EVC**, not the live cluster. If a freshly-deployed asset isn't reflected where you expect,
+suspect an EVC/snapshot timing issue rather than a cluster problem — re-check with `cod config
+view` / `cod asset list` (both EVC-derived).
+
+---
+
+## 5. Cloud/registry auth (CSP)
+
+CSP = Cloud Service Provider integration.
+
+- A tenant onboards providers via a **cspTenantProfile** (`cod csp setup`).
+- **`cod csp login <provider>`** authenticates the tenant's own creds for that provider; tokens are
+  cached **server-side per tenant**, so a later headless operation (deploy, agent install) can use
+  them without re-login.
+- You typically need **two** logins for a full deploy: the **cloud provider** that owns the cluster
+  (e.g. `azure`) *and* the **registry** hosting the chart/image (e.g. `docker` for Docker Hub).
+  A "no credentials found" / "DockerHub credentials not found" failure during deploy almost always
+  means one of these logins is missing.
+- Provider is a **positional arg** on `cod csp login` (`aws`/`azure`/`docker`), and secrets are fed
+  via **stdin** in `--silent` mode.
+
+Commands like `cod cluster connect <name> --silent` use the cached CSP creds to set up kubectl
+auth — prefer it over raw cloud CLIs for cluster access.
+
+---
+
+## 6. Hosts and ingress
+
+- A workload with an ingress needs a **host**. Codiac resolves hosts from a **host-naming strategy**
+  attached to a scope (`ScopedHostNameConfig`) — e.g. `svc_dot_cab_dot_domain`
+  (`<service>.<cabinet>.<domain>`) or `shared_ingress_ip`.
+- You can set the ingress host directly as a `[helm]` scoped setting (`ingress.host`), ideally as a
+  shareable enterprise-scope **template** (`@{asset.name}.@{cabinet.name}.….<domain>`) so it
+  resolves per cabinet.
+- Commands: `cod host list/map/view/delete`.
+
+---
+
+## 7. The API surface
+
+Codiac's data plane is **NATS, not HTTP**. Key implications:
+
+- The platform communicates over **NATS pub/sub** (subjects, request/reply, streaming events), not
+  REST. The web frontend follows a **Facade → NATS → Store (Akita) → Query → Component** pattern;
+  it does not fetch over HTTP for platform data.
+- There is a **relay** with endpoints (operationIds) invoked over NATS; the CLI's `executeTask`
+  makes exactly one such relay call per command. This is why the CLI is the safe surface — it wraps
+  the correct subjects, auth, and payloads for you.
+- There is a **tenant → hub account boundary**. A long *synchronous* request/reply does **not**
+  survive the import across that boundary — long operations use an **ack-then-stream** pattern
+  (return an ack immediately, then publish terminal status as an event on the tenant's
+  `events.>` channel). If you ever build against the API directly, don't expect a long blocking
+  reply from a customer tenant to the hub; subscribe for the streamed result instead.
+
+Practically: **use the CLI.** Only reach for the raw NATS API when the CLI genuinely cannot express
+what you need — and then mirror how the CLI builds the call.
+
+---
+
+## 8. Agents on Codiac
+
+Codiac can run AI agents as first-class workloads.
+
+- **`cod ai agent install`** provisions an agent into a cabinet. `--type` selects the framework:
+  `openclaw`, `hermes`, or `byoa` (bring-your-own-agent). `--name` is the workload name, `-c` the
+  cabinet, and ingress is on by default (needs a `--naming` strategy in silent mode).
+- Provisioning follows the same asset/scoped-config/deploy machinery above: it registers an asset,
+  writes scoped settings (secrets sourced to the vault, shared config at enterprise scope), maps the
+  ingress host, and deploys — so everything in §§2–6 applies to agents too.
+- Secrets an agent needs (API keys, dashboard password) are scoped settings; set them **once** at
+  enterprise scope and let cabinets inherit, rather than re-prompting per install.