docs: document profile args
Assisted-by: Claude Opus 4.8 via pi
diff --git a/AGENTS.md b/AGENTS.md
index 8c9f635..811ea61 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,8 +44,8 @@ just # All four
## Architecture notes
- The config redesign is documented in `docs/config-redesign.md`; all four steps of its sequencing are implemented.
-- Config files are parsed directly with the `kdl` crate (`parse_config` in `config.rs`), not serde: the grammar is `mounts` blocks (one child node per mount: name = host source, `target`/`writable` properties), one `env` block syntax (bare child = host passthrough), and `profile` nodes (with children = definition, bare = selection). Unknown nodes fail loudly.
-- Config merges layers, lowest precedence first: binary (staples `~/.config/git`/`~/.config/jj` plus the active agent's config allowlist, mounted read-only, canonicalized, skip-if-missing), profile (the active profile's env/mounts), user (every `*.kdl` in `~/.config/ramekin/`, merged as one layer, duplicate keys within the layer are errors), and project (`.ramekin/config.kdl`). A `/dev/null` source masks (removes) a mount inherited from a lower layer. `env` merges per variable; profiles merge by name, last writer takes the whole definition.
+- Config files are parsed directly with the `kdl` crate (`parse_config` in `config.rs`), not serde: the grammar is `mounts` blocks (one child node per mount: name = host source, `target`/`writable` properties), one `env` block syntax (bare child = host passthrough), and `profile` nodes (with children = definition carrying `agent`/`env`/`mounts`/`args`, bare = selection). Unknown nodes fail loudly.
+- Config merges layers, lowest precedence first: binary (staples `~/.config/git`/`~/.config/jj` plus the active agent's config allowlist, mounted read-only, canonicalized, skip-if-missing), profile (the active profile's env, mounts, and args), user (every `*.kdl` in `~/.config/ramekin/`, merged as one layer, duplicate keys within the layer are errors), and project (`.ramekin/config.kdl`). A `/dev/null` source masks (removes) a mount inherited from a lower layer. `env` merges per variable; profiles merge by name, last writer takes the whole definition.
- Profiles subsume agent selection: the binary ships trivial `pi`/`claude` profiles, selection precedence is binary < user < project < `-p`. `Agent` (in `config.rs`) carries each agent's host config dir, allowlist, and container config dir; `AgentState` (in `main.rs`) carries its persistent host paths and session mounts.
- Persistence is per-agent, opposite policies: pi is ephemeral-by-default (fresh session dir at `/root/.pi/agent`; allowlisted `auth.json` from `$XDG_DATA_HOME/ramekin/agents/pi/` and per-repo `sessions/` bound on top; teardown logs discarded writes). Claude is persist-by-default (`~/.claude` + `~/.claude.json` from `$XDG_DATA_HOME/ramekin/agents/`, shared across repos; session-scoped dirs bound over the `CLAUDE_EPHEMERAL` denylist).
- Each workspace mounts at `/workspace/<slug>` (slug is `<dirname>-<hash>`, never a shared `/workspace`) so cwd-keyed agent state stays distinct per repo; compose's `working_dir` puts the agent there on start.
diff --git a/docs/config-redesign.md b/docs/config-redesign.md
index 3465744..74bb5e9 100644
--- a/docs/config-redesign.md
+++ b/docs/config-redesign.md
@@ -95,7 +95,7 @@ entry when generating mounts, since bind sources need real paths.
### Profiles: KDL bundles of agent + provider
-A profile is a named bundle: agent, env vars, extra mounts. The binary
+A profile is a named bundle: agent, env vars, extra mounts, and agent CLI args. The binary
ships only the two trivial ones — `pi` and `claude`, bare agent with no
provider plumbing — so ramekin runs with zero config. Everything richer is
defined in KDL:
@@ -120,6 +120,26 @@ profile "pi-glm" {
}
```
+A profile also pins CLI flags for the agent binary through `args`, for
+providers the agent selects by flag rather than by environment (pi reaches
+Amazon Bedrock through `--provider`, which has no env equivalent):
+
+```kdl
+profile "pi-bedrock" {
+ agent "pi"
+ args "--provider" "amazon-bedrock"
+ env {
+ AWS_PROFILE
+ AWS_REGION
+ }
+ mounts { "~/.aws" }
+}
+```
+
+Args ride with the profile definition, so the wholesale profile-merge rule
+covers them too; the run's trailing `ramekin -- ...` args come after and
+override.
+
Profiles merge by name across layers, last writer takes the whole
definition — a project can redefine `claude-bedrock` wholesale, but
fine-grained tweaks (one env var) go through the ordinary layered `env`