@codiac.io/codiac-cli 1.3.245 → 1.3.246

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.