kanibako-cli 1.7.2rc5__tar.gz → 1.8.0.dev95__tar.gz

{kanibako_cli-1.7.2rc5/src/kanibako_cli.egg-info → kanibako_cli-1.8.0.dev95}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanibako-cli
-Version: 1.7.2rc5
+Version: 1.8.0.dev95
 Summary: Run AI coding agents in rootless containers with per-project isolation
 Requires-Python: >=3.11
 License-File: LICENSE.md
@@ -8,10 +8,10 @@ Requires-Dist: argcomplete>=3.0
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: packaging>=20.0
 Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest==9.0.2; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: ruff==0.15.5; extra == "dev"
 Requires-Dist: bump2version; extra == "dev"
 Requires-Dist: pexpect>=4.8; extra == "dev"
 Dynamic: license-file

{kanibako_cli-1.7.2rc5 → kanibako_cli-1.8.0.dev95}/README.md

@@ -21,174 +21,119 @@ No Docker or Podman experience required.  Just `cd` into a project and run
 Claude Code, Codex, and Goose ship as first-class agent plugins (all installed
 by the `kanibako` meta-package); other agents can be added as plugins.
 
-## Features
+## Quick Start
 
-- **Safe by default** -- rootless containers with no host access; the sandbox
-  is what makes it safe to give agents real autonomy
-- **Automatic sandboxing** -- no Docker or Podman experience required;
-  Kanibako manages all container operations for you
-- **Session continuity** -- `kanibako start` defaults to `--continue`, picking
-  up where you left off; persistent tmux sessions survive SSH disconnects
-- **Per-box isolation** -- each box gets its own home, config, and
-  credentials (three modes: primary, workset/named, standalone)
-- **Credential forwarding** -- host credentials are synced into the box
-  and written back after each session
-- **Setup wizard** -- `kanibako setup` detects installed agents, checks your
-  container runtime, and lets you pick a default agent (the only interactive
-  prompt in the CLI); no manual configuration needed
-- **Diagnostics** -- `kanibako system diagnose` checks runtime, images,
-  agents, and storage; `box diagnose` and `rig diagnose` drill into specific
-  scopes
-- **Vault snapshots** -- per-box read-only and read-write shared
-  directories with smart snapshot strategy detection (reflink, hardlink,
-  or tar.xz depending on filesystem)
-- **Shell customization** -- per-box environment variables (`box set
-  env.*`), drop-in init scripts (`shell.d/`), and layered seed-once home
-  templates
-- **Agent configuration** -- per-agent YAML config with default args, state
-  knobs, env vars, and shared caches; per-box setting overrides via
-  `box set`
-- **Shared caches** -- global download caches (pip, cargo, npm, etc.)
-  shared across boxes; agent-level caches via the agent config
-- **Plugin system** -- agent-agnostic core (`kanibako-cli`); Claude/Codex/Goose
-  plugins (`kanibako-agent-*`) ship with the meta-package; descriptor-only
-  three-tier discovery (entry points, user directory, project directory)
-- **Rig freshness checks** -- non-blocking digest comparison against GHCR
-  on startup (24h cache)
-- **Helper spawning** -- spawn child agent instances for parallel workloads
-  with budget-controlled depth and breadth
-- **Concurrency lock** -- prevents two sessions from running in the same
-  project simultaneously
-
-## Prerequisites
+```bash
+# Install & Setup
+pipx install kanibako   # uv and pip also work!
+kanibako setup
 
-- Python 3.11+
-- [Podman](https://podman.io/) 4.3+ (recommended) or Docker -- just needs to be
-  installed; Kanibako manages all container operations automatically
-- An AI coding agent installed on the host (e.g.
-  [Claude Code](https://docs.anthropic.com/en/docs/claude-code))
+# Create a box for your project - a one-time step per project 'box':
+cd ~/my-project && kanibako create
 
-## Installation
+# Launch the agent session -- that's it!
+kanibako
 
-> **Pre-release:** the current line (`1.7.0`) is still in release candidates, so
-> add `--pre` (pip/pipx) or `--prerelease allow` (uv) to get the newest rc. Plain
-> `pip install kanibako` gets the last *stable* release (`1.6.0`). Once `1.7.0`
-> ships, drop the flag.
+# Optional - launch in VS Code (new, experimental):
+kanibako code
+```
 
-```bash
-# Standard install (cli + Claude, Codex, and Goose plugins) -- current rc
-uv tool install --prerelease allow kanibako
-# -- or --
-pip install --pre kanibako
+## Features
+
+- **Seamless Isolation** -- rootless containers with no host access, so its safe to give agents autonomy
+- **Automatic Sandboxing** -- no Docker or Podman experience required - it's all automated
+- **Session Continuity** -- `kanibako start` by default to picks up where you left off
+- **Painless Persistence** -- boxes launch in tmux by default - so you can detach and leave agents running
+- **Credential Forwarding** -- host credentials optionally synced into the box from host
+- **Customized, Per-Box** -- each box gets its own home, config, & credentials (multiple sharing modes)
+- **Layered Customizations** -- per box/workset/agent and global customizations (settings, scripts, etc.)
+- **Nuanced Custrols** --per box/workset/agent and global environment, mount, and share controls
+- **Helper / Subagents** -- subagent spawning system for distributed workloads
+- **Diagnostics** -- `kanibako system diagnose` (runtime, images, agents, & storage)
+- **Plugins** -- agent-agnostic core (`kanibako-cli`) with custom plguin system for others harnesses
+
+## Using Kanibako
+See the [Quick Start](#quick-start) Guide for get started right away; below are the nitty-gritty details.
 
-# Base only (no agent plugins -- agent-agnostic shell mode)
-pip install --pre kanibako-cli
+### Prerequisites
 
-# Development install
-git clone https://github.com/doctorjei/kanibako.git
-cd kanibako
+- Python 3.11+
+- [Podman](https://podman.io/) 4.3+ (recommended) or Docker (Containers managed automatically)
+- An agent harness or full agent system (e.g., Claude Code, Codex, or Goose)
+
+### Install from Source
+
+```bash
+git clone https://github.com/doctorjei/kanibako-cli.git
+cd kanibako-cli
 pip install -e '.[dev]' -e packages/agent-claude/ -e packages/agent-codex/ -e packages/agent-goose/
 ```
 
 On first use, Kanibako automatically creates its config and data directories.
 Run `kanibako setup` to verify your environment and pick a default agent. If you
-have **more than one** agent installed (the meta-package ships all three), you
-**must** choose one — either with `setup` or per-run with `--agent <name>` —
+have **more than one** agent harness installed (the meta-package ships all three),
+you **must** choose one — either with `setup` or per-run with `--agent <name>` —
 otherwise `kanibako` will error rather than guess. With a single agent installed
 it is used automatically. See [Agent Selection](#agent-selection).
 
-## Quick Start
+No `docker run`, no volume flags, no Containerfile. The first launch pulls the
+container rig and copies in your agent credentials; after that, `kanibako` in the
+same directory picks up right where you left off.
 
-```bash
-# Create a box for the current directory (a deliberate, one-time step)
-cd ~/my-project
-kanibako create
+More ways to launch:
 
-# Start an agent session (shortcut for `kanibako start`)
-kanibako
-
-# Start with a specific rig
-kanibako --image kanibako-min:latest
-
-# Open a plain bash shell (no agent)
-kanibako shell
-
-# Run a one-shot command in the container
-kanibako shell -- echo hello
-
-# Start a new conversation
-kanibako -N
+```bash
+kanibako -N                            # start a fresh conversation
+kanibako shell                         # plain bash shell, no agent
+kanibako shell -- echo hello           # run a one-shot command in the box
+kanibako --agent codex                 # choose the agent for this run
+kanibako --image kanibako-min:latest   # launch on a specific rig
 ```
 
-That's it -- no `docker run`, no volume flags, no Containerfile.  Creating a box
-is an explicit step (`kanibako create`); a launch (`kanibako` / `start` / `code` /
-`shell`) never invents a box, so a typo'd project or wrong directory can't
-silently make one.  On the first launch of a box, Kanibako pulls the container
-rig and syncs your credentials; subsequent runs pick up where you left off.
+Creating a box is deliberate: a launch (`kanibako` / `start` / `code` / `shell`)
+never invents one, so a typo'd path or wrong directory can't silently make a box.
 
-## Example: Python Project
+### Example: Python Project
 
 The default `kanibako-oci` rig (based on droste-fiber) includes Python, git,
 gh, nano, jq, ripgrep, tmux, Podman, and common dev tools.  This is enough for
 most Python, JavaScript, and general scripting work.
 
 ```bash
-# 1. Install kanibako (--pre while 1.7.0 is in rc; see Installation)
-pip install --pre kanibako
-
-# 2. Create or clone a project
-mkdir ~/my-flask-app && cd ~/my-flask-app
-git init
-# (or: git clone https://github.com/you/my-flask-app.git && cd my-flask-app)
-
-# 3. Create the box for this project (explicit, one-time)
-kanibako create
-
-# 4. Launch -- that's it
-kanibako
+pipx install kanibako                       # installation
+mkdir ~/my-flask-app && cd ~/my-flask-app   # Create project
+git init                                    # New git repo (alt: clone a project)
+kanibako create                             # Create new box for project (one-time)
+kanibako                                    # launch (app done!)
 ```
 
-`kanibako create` sets up an isolated environment for this project.  On the
-first launch, Kanibako will:
+`kanibako create` builds an isolated environment. On first launch, Kanibako will automatically...
 - Pull the base container rig (once, cached afterwards)
 - Copy your agent credentials into the sandbox
 - Drop you into an agent session inside the container
 
-The agent sees your project files in `~/workspace/` and has full access to
-Python, git, and the other base tools.  When you exit, your project files
-and agent state are preserved -- next time you run `kanibako` in the same
-directory, it picks up where you left off.
+The agent sees your project files in `~/workspace/` and has full access to standard tools. On exit,
+project files and agent state are preserved; on next run, `kanibako` will pick up where you left off.
 
 ```bash
-# Later: come back to the same project
+# Come back to the same project latyer...
 cd ~/my-flask-app
 kanibako              # resumes your previous session
 kanibako -N           # or start a fresh conversation
 ```
 
-## Example: C/Rust Project (custom rig)
+### Example: C/Rust Project (custom rig)
 
-For projects that need compiled languages, create a custom rig with the
-toolchains you need:
+For projects that need compiled languages, create a custom rig with needed tools:
 
 ```bash
-# 1. Build the bundled C/C++ + Rust toolchain template
-kanibako rig prep systems
-# (or build one interactively with: kanibako rig extend my-systems --from kanibako-oci)
-
-# 2. Create the box for your project, pinned to that rig (explicit, one-time)
-cd ~/my-rust-project
-kanibako create --image kanibako-template-systems
-
-# 3. Launch
-kanibako
+kanibako rig prep systems                          # Build bundled C/C++ + Rust toolchain template
+cd ~/my-rust-project                               # Enter the project directory
+kanibako create --image kanibako-template-systems  # Create a box using the systems template
+kanibako                                           # Start & enter the box
 ```
 
-`kanibako create` pins the rig choice for this project, so you can just run
-`kanibako` next time.
-
-See [Container Rigs](#container-rigs) for the base rigs and custom rig
-creation.
+See [Container Rigs](#container-rigs) for the base rigs and custom rig creation.
 
 ## Commands
 
@@ -235,7 +180,7 @@ shortcuts for common operations:
 
 | Subcommand | Description |
 |------------|-------------|
-| `box create [path]` | Create project (`--name`, `--standalone`, `--image`, `--no-vault`, `--distinct-auth`, `--allow-home`) |
+| `box create [path]` | Create project (`--name`, `--standalone`, `--register`, `--image`/`--rig`, `--no-vault`, `--private`, `--allow-home`, `--agent`) |
 | `box list` / `box ls` | List projects (`--all`, `--orphan`, `-q`) |
 | `box info` / `box inspect` | Project details (mode, paths, lock, rig) |
 | `box rm` / `box delete` | Remove project (`--purge` deletes metadata, `--force` skips confirm) |
@@ -320,9 +265,16 @@ The runtime helper and fork verbs (formerly under `crab`) now live under `box`:
 |------------|-------------|
 | `system info` / `system inspect` | System details (version, runtime, paths) |
 | `system set` / `system get` / `system show` / `system reset` | View or modify global configuration |
+| `system defaults` | List every default kanibako ships, with its scope and source |
 | `system upgrade` | Self-update (`--check` for dry run) |
 | `system diagnose` | Check system health (runtime, images, agents, storage) |
 
+## Preview / Experimental Features
+- **Vault snapshots** -- per-box read-only and read-write shared
+  directories with smart snapshot strategy detection (reflink, hardlink,
+  or tar.xz depending on filesystem)
+- Build rigs interactively with: kanibako rig extend my-systems --from kanibako-oci)
+
 ## VS Code Integration
 
 > **⚠ Experimental.** VS Code integration is **experimental** in this release.
@@ -416,7 +368,7 @@ context.
 
 | Flag | Description |
 |------|-------------|
-| `-e, --env KEY=VALUE` | Per-run environment variable (repeatable) |
+| `-e, --env VAR=VALUE` | Set a per-run environment variable, overriding the key that owns it (repeatable; a malformed item refuses the launch) |
 | `--image IMAGE` | Container rig override |
 | `--entrypoint CMD` | Override container entrypoint |
 | `--persistent` | Use tmux session wrapper (default) |
@@ -424,6 +376,18 @@ context.
 | `--no-helpers` | Disable helper spawning |
 | `--no-auto-auth` | Disable automated browser-based OAuth refresh |
 | `--browser` | Launch a headless browser sidecar (`BROWSER_WS_ENDPOINT` injected) |
+| `--restart` | Stop the box first, then start it fresh (`start` only) — the way to apply flags to a box that is already running |
+
+⚑ **Against a box that is already RUNNING, most of these are refused, not applied.** A running
+container keeps the creation-time settings and the agent session it was launched with, so
+`--image`, `-e` (except where something in the box will actually apply it, below), `--no-helpers`,
+`--no-auto-auth`, `--browser`, `--share-images`, an explicit `--persistent`/`--ephemeral`, and the
+agent flags `-N -C -R -M -A -S` produce an error naming the cure rather than being silently
+dropped. Use `kanibako --restart [box]` to stop and relaunch with them in force. Two exceptions:
+`--detach`/`--print-container`/`--warm-only` are honoured; and anything that starts a **second
+process inside the running box** — `--entrypoint CMD`, or `kanibako shell --persistent` at a box
+that is running an agent — runs with `-e` applied, so `-e` is refused only where nothing would
+apply it.
 
 ### Global Flags
 
@@ -465,9 +429,14 @@ Which agent a command uses is resolved by a single cascade (highest precedence
 first):
 
 ```
---agent  >  box.agent  >  workset default  >  system.default_agent
+--agent  >  box pref  >  workset pref  >  system.agent
 ```
 
+A box or workset REQUESTS an agent with `pref.system.agent` (a request to set a key
+that resolves earlier than the file making it); `system.agent` is the host-global
+default and `--agent` is the ephemeral per-launch override. `kanibako create --agent
+<name>` persists the request into the new box, so a plain `kanibako start` runs it.
+
 If a name resolves, it is used (and an error is raised if that agent's plugin
 isn't installed). If **nothing** resolves, the **installed-agent count** decides --
 with no ordering and no tie-break:
@@ -491,7 +460,7 @@ when no agent is configured.
 
 ### Choosing a default agent
 
-`kanibako setup` is where you pick the host-global default (`system.default_agent`).
+`kanibako setup` is where you pick the host-global default (`system.agent`).
 On a TTY it shows a numbered menu of detected agents (the only interactive prompt in
 the CLI); `setup --agent <name>` sets it non-interactively. A "skip" option is
 offered -- with 2+ agents it warns that a bare launch will then fail and asks you to
@@ -577,6 +546,17 @@ kanibako create --standalone           # in the current directory
 kanibako create --standalone ~/myproj  # create and initialize a new directory
 ```
 
+A standalone box is **unregistered by default** -- it carries its own identity
+in-tree, so it needs no registry entry and can be moved or copied anywhere.
+The registry entry is only a shortcut for addressing the box **by name from
+another directory**; add it at create time with `--register` (which is also
+what makes `--name` meaningful), or later with `kanibako box register <path>`.
+
+```bash
+kanibako create --standalone --register --name myproj ~/myproj
+kanibako box register ~/myproj         # or opt in afterwards
+```
+
 ```
 {project}/                       ← project root
 ├── settings.yaml                ← box metadata (at the root)
@@ -721,23 +701,27 @@ Set per-project or global environment variables that are passed to the
 container:
 
 ```bash
-# Persistent (stored in project config)
-kanibako box set env.EDITOR=vim              # project-level
-kanibako system set env.EDITOR=nano          # global (all projects)
-kanibako box get env.EDITOR                  # show one value
+# Persistent (stored in the scope's settings file)
+kanibako box set box.env.EDITOR=vim             # box-level
+kanibako workset set workset.env.EDITOR=vim     # workset-level
+kanibako system set system.env.EDITOR=nano      # global (all boxes)
+kanibako box get box.env.EDITOR                 # show one value
 
 # Per-run (not persisted)
 kanibako start -e EDITOR=vim -e DEBUG=1
 ```
 
-Project env vars override global ones.
+The scope is part of the key: `<scope>.env.<VAR>`, where `<scope>` is
+`system`, `workset` or `box` (an agent's own vars are
+`agent.<agent>.env.<VAR>`).  The most specific scope wins, so a box var
+overrides a workset one, which overrides the global one.
 
 ### Custom prompt
 
 The shell prompt is controlled by the `KANIBAKO_PS1` environment variable:
 
 ```bash
-kanibako box set env.KANIBAKO_PS1="(myproject) \u:\w\$ "
+kanibako box set box.env.KANIBAKO_PS1="(myproject) \u:\w\$ "
 ```
 
 ### Init scripts
@@ -787,9 +771,9 @@ tweakcc:
 - `tweakcc:` -- optional tweakcc integration for binary patching
   (see [docs/tweakcc.md](docs/tweakcc.md))
 
-Per-agent shares/caches are declared by the plugin (`agent.<agent>.shared.*` /
-`agent.<agent>.caches.*`) and served from the per-agent store dir
-(`agents/<agent>/{plugins,cache}`).
+Per-agent common dirs/caches are declared by the plugin (`agent.<agent>.common` /
+`agent.<agent>.caches` — one key per category, holding a map keyed by box destination) and
+served from the per-agent store dir (`agents/<agent>/{common,caches}/<name>`).
 
 Manage agent settings via the CLI:
 
@@ -799,39 +783,56 @@ kanibako agent get claude model        # show the agent's model
 kanibako agent set claude model=sonnet # set agent-level default
 ```
 
-## Home Templates
+## Box Templates
+
+Box templates provide **layered seed-once** initialization for a new box.
+Three layers are copied into the box STORE in order (later overlays earlier;
+absent layers are skipped), **once** -- edits you make inside a box afterward
+are never overwritten.
 
-Home templates provide **layered seed-once** initialization for a new box.
-Three layers are copied into the box home `~/` in order (later overlays
-earlier; absent layers are skipped), **once** -- edits you make inside a box
-afterward are never overwritten:
+Each layer has a `box/` subtree with the same two entries, and each entry has
+its own destination:
 
 ```
-1. base    @system.base_template     → ~/   (always; the flat base skeleton)
-2. agent   @agent.<agent>.template    → ~/   (= agents/<agent>/template; if box.agent set)
-3. workset @workset.template          → ~/   (= <wsroot>/template; optional, primary/named)
+                                            ->  <box_dir>/home       (delivered at ~/)
+1. system   @system.template/box/...        ->  <box_dir>/canon/handbook
+2. agent    @agent.<agent>.template/box/... (= agents/<agent>/template/box; if an agent is set)
+3. workset  @workset.template/box/...       (= <wsroot>/template/box; optional, primary/named)
 ```
 
-Per-file rule: plain ordered copy, **last layer wins**, seed-once.  There is no
-per-file merge of any file -- `CLAUDE.md` is an ordinary template file, and the
-base layer's guidance lives in a separate non-colliding `INSTRUCTIONS.md` so it
-never clobbers an agent template's `CLAUDE.md`.
+- `box/home/**` seeds the box HOME -- what you see at `~/` inside the box,
+  including `~/canon/notebook` and `~/canon/workbook`, the two books the box
+  owns and can write.
+- `box/canon/handbook/**` seeds the box's HANDBOOK CHAPTER at `@box.canon`,
+  which is a **sibling** of the home, not inside it. It is bound back into the
+  box read-only at `~/canon/handbook/box`.
+
+⚑ `@box.canon` is not `~/canon`: the first is the box's contribution to the
+canon (on the host), the second is the assembled canon (in the box).
+
+Per-file rule: plain ordered copy, **last layer wins**, seed-once. There is no
+per-file merge of any file.
 
 The old shell-variant selector (`crab.shell` / `template_name`) is gone -- there
 is one fixed `template/` dir per agent, with no variant subdirectory.  `box.shell`
 now means only the login shell (see [Configuration](#configuration)).
 
-**Example agent template layout** (for agent `claude`):
+**Example agent store layout** (for agent `claude`):
 
 ```
-agents/claude/template/
-|- .claude/
-|   '- settings.json
-'- CLAUDE.md
+agents/claude/
+|- template/box/home/
+|   |- .claude/
+|   |   '- settings.json
+|   '- .claude.json
+'- canon/handbook/
+    '- directives/
+        '- SYS_AGENT.md      # this agent's handbook chapter
 ```
 
-To ship custom per-agent config into boxes, put it in that agent's `template/`
-dir; it seeds via layer 2.
+To ship custom per-agent config into boxes, put it under that agent's
+`template/box/home/`; it seeds via layer 2. To give the agent its own standing
+directives, put them under `canon/handbook/`.
 
 ## Vault
 
@@ -843,9 +844,21 @@ inside the box at `~/vault/ro` and `~/vault/rw`:
 - **vault/rw/** -- files that persist across sessions and can be modified
   (databases, build caches, generated artifacts)
 
-The host-side vault lives under the workset (`vault/{ro,rw}/<box>`); inside the
-box the local `~/workspace/vault` path is masked by a read-only tmpfs, so the
-agent cannot see or modify host vault metadata.
+The host-side vault lives under the workset (`vault/{ro,rw}/<box>`).
+
+A box can hide any guest path it likes with a **mask** — an empty tmpfs mounted
+over that path, so whatever the box home holds there is not visible inside the
+box at all:
+
+```yaml
+box:
+  masks:
+    "~/private": true
+```
+
+No mask is applied by default. (Before 1.6.0 the vault lived inside the
+workspace and `~/workspace/vault` was masked automatically; the vault moved out,
+so there is nothing in `~/workspace` left to hide.)
 
 ### Snapshots
 
@@ -962,10 +975,11 @@ kanibako system set model=opus
 kanibako system reset --all             # reset all global settings
 ```
 
-`kanibako system set` sets **non-`system.`** settings only. `system.*`-prefixed
-keys (layout paths AND `system.default_agent`) are **file-only**: the CLI shows them
-but refuses to set/reset them, pointing you at the config file. Set the default agent
-with `kanibako setup`; edit structural paths in `~/.config/kanibako.yaml` directly.
+`system.*` LAYOUT-PATH keys are **file-only**: the CLI shows them but refuses to
+set/reset them, pointing you at the config file. `system.agent` is NOT one of those —
+it is an ordinary system-scope setting, so `kanibako system set
+system.agent=<name>` works (as does `kanibako setup`). Edit structural paths in
+`~/.config/kanibako_config.yaml` directly.
 
 ### Files
 
@@ -976,7 +990,10 @@ All kanibako config/settings files are YAML.
 - **Workset settings**: `<workset_root>/settings.yaml`
 - **Per-agent settings**: `$XDG_DATA_HOME/kanibako/agents/{agent}/settings.yaml`
 - **Per-box settings**: `boxes/{name}/settings.yaml` (standalone: `<root>/settings.yaml`)
-- **Base template**: `$XDG_DATA_HOME/kanibako/global/base_template/`
+- **Template root**: `$XDG_DATA_HOME/kanibako/global/template/` (the `box`,
+  `workset` and `agent` moulds new stores are stamped from)
+- **System handbook**: `$XDG_DATA_HOME/kanibako/global/canon/handbook/` -- your
+  own system-wide directives, delivered read-only into every box
 
 ### Common settings keys
 
@@ -992,9 +1009,11 @@ All kanibako config/settings files are YAML.
 | `group_auth` | `true` | Shared credentials across the group (`true`) vs. per-box (`false`) |
 | `enable_vault` | `true` | Enable vault directories |
 | `env.*` | | Persistent environment variables (`<scope>.env.<VAR>`) |
-| `<scope>.bindings.ro.*` / `.rw.*` | | Scoped bind-mounts (`host_src:box_dest`) |
-| `<scope>.caches.*` | | Scoped cache mounts (`host_src:box_dest`) |
-| `<scope>.seeded.*` | | Copy-once seeds applied at box init |
+| `<scope>.bindings.ro` / `.rw` | | Scoped bind-mounts. ⚑ **Settings-file only** — one key per arm, holding a map keyed by box destination. There is no `.<name>` sub-key and no `config set` route; `config get` reads it |
+| `<scope>.caches` | | Scoped cache mounts — same shape: one key, `{box_dest: [host_src[, options]]}`, settings-file only |
+| `<scope>.common` | | Shared dirs mounted rw — same shape |
+| `<scope>.seeded` | | Copy-once seeds applied at box init — same shape; a COPY, not a mount |
+| `<scope>.synced` | | Per-launch mtime-gated copies — same shape; a COPY, not a mount |
 
 ### Global config file
 
@@ -1114,6 +1133,16 @@ kanibako start myproject
 # Reattach later:
 kanibako start myproject
 
+# A reattach does ONLY what reattaching needs: it does not rebuild or pull an
+# image, probe the launch baseline, or verify a persona endpoint over the
+# network -- none of which could affect the session it is attaching to.
+# Flags that the running container cannot adopt are refused rather than
+# ignored; restart the box to apply them:
+kanibako --restart -N myproject     # stop, then start a NEW conversation
+
+# Run a command as a second process inside the running box:
+kanibako start --entrypoint htop myproject
+
 # Start without tmux (session dies when terminal closes)
 kanibako start --ephemeral myproject