More docs

docs/commands/auth.md

@@ -83,12 +83,18 @@ export NEBIUS_AI_PROJECT=your-project-id
 contree auth -y      # no prompts, saves immediately
 ```
 
-## `auth ls` status column
+## `auth list`
 
-`contree auth ls` verifies each saved profile against the API
-with a 2-second timeout and adds a `status` column.
+`contree auth list` (alias `auth ls`, `profiles`) prints every saved
+profile from `auth.ini` and verifies each one against the API with a
+2-second timeout, adding a `status` column that tells you at a glance
+which profiles are usable. Pass `--offline` to suppress the probe
+entirely when you only want to inspect what is saved locally.
 
-Possible values:
+```{terminal-shell} contree auth list --help
+```
+
+Possible `status` values:
 
 - `ok` -- probe succeeded and the token has the `list` permission
 - `inactive` -- probe succeeded but the token lacks the `list`
@@ -98,29 +104,42 @@ Possible values:
   another network/API error
 - `offline` -- you passed `--offline`, so no probe was attempted
 
-Use `contree auth ls --offline` when you want to inspect saved
-profiles without any network traffic.
-
 For automation and agents, prefer:
 
 ```bash
 contree -f json auth ls
 contree -f json auth ls --offline
 ```
 
+## `auth switch`
+
+`contree auth switch NAME` rewrites the `active` pointer in `auth.ini`
+so subsequent commands resolve credentials from that profile. The
+profile must already exist (created by `contree auth --profile=NAME`).
+Switching does not touch token data, so it is safe to run as often as
+you like to bounce between projects.
+
+```{terminal-shell} contree auth switch --help
+```
+
 ## `auth remove`
 
-Delete a saved profile from the config file.
+`contree auth remove NAME` (aliases `rm`, `del`) deletes the profile
+from `auth.ini` and removes its per-profile session database
+(`sessions-NAME.db`). If the deleted profile was the active one, the
+CLI promotes the first remaining profile to active (or falls back to
+`default` if none remain). Confirmation is required unless `-y` is
+passed.
+
+```{terminal-shell} contree auth remove --help
+```
 
 ```bash
 contree auth remove personal
 contree auth rm personal         # alias
 contree auth del personal -y     # skip confirmation
 ```
 
-If the removed profile was active, the CLI switches to the first
-remaining profile (or `default` if none remain).
-
 :::{warning}
 Avoid `--token=eyJ...` on the command line — the token is visible in
 process listings (`ps`) and shell history. Omit `--token` to use the

docs/commands/file.md

@@ -25,21 +25,31 @@ contree run nginx -t
 
 ### `file edit`
 
-Downloads a file from the session image, opens it in `$EDITOR` (defaults to
-`vi`), and stages the changes if the file was modified. If the file does not
-exist in the image, an empty file is created.
+`contree file edit PATH` (alias `e`) downloads the file at `PATH` from
+the session image, opens it in `$EDITOR` (defaults to `vi`), and stages
+the modified buffer as a pending upload that will be injected into the
+next `contree run`. Missing files are created as empty buffers so the
+command doubles as `touch + open`.
+
+```{terminal-shell} contree file edit --help
+```
 
 ### `file cp`
 
-Copies a local file and stages it at the given path inside the image. The
-file is uploaded immediately but only applied to the sandbox on the next
-`contree run`.
+`contree file cp SRC DEST` (alias `f`) reads a local file at `SRC`, uploads
+it to the project's file store, and stages it for delivery at `DEST` inside
+the session image on the next `contree run`. Use this when you have a file
+ready on disk locally and just want it materialised inside the sandbox
+without spawning an instance first.
+
+```{terminal-shell} contree file cp --help
+```
 
 ### `file ls`
 
-Lists files uploaded to the project (`GET /v1/files`) and joins each row
-with the local upload cache. The `SOURCE` column shows whatever this
-machine produced the file from:
+`contree file ls` lists files uploaded to the project (`GET /v1/files`)
+and joins each row with the local upload cache. The `SOURCE` column shows
+whatever this machine produced the file from:
 
 - absolute host path for files uploaded via `run --file` or `COPY`;
 - `https://...` URL for files fetched via `ADD URL`.
@@ -72,6 +82,9 @@ contree file ls -q                # uuid + sha256 + source only
 contree -f json file ls | jq 'select(.source != "")'
 ```
 
+```{terminal-shell} contree file ls --help
+```
+
 ## Pending files
 
 Pending files accumulate until the next `contree run` consumes them.

docs/commands/images.md

@@ -43,6 +43,30 @@ contree images --prefix=common/
 `--since` and `--until` accept either ISO timestamps or duration intervals
 like `1h`, `30m`, `7d`.
 
+## Subcommands
+
+### `images list`
+
+`contree images list` (alias `ls`) is the explicit form of the bare
+`contree images` invocation. Both share the same flag set -- pick the
+explicit form when you want a command that reads symmetrically with
+`images import`, or in scripts that already use the subcommand style
+everywhere.
+
+```{terminal-shell} contree images list --help
+```
+
+### `images import`
+
+`contree images import REF [REF ...]` pulls one or more images from an
+external OCI registry into the project and waits for the import
+operation to finish. Each reference may be a `docker://` URL or any
+form the platform accepts; multiple refs are imported sequentially with
+shared credentials, and Ctrl-C cancels the in-flight operation cleanly.
+
+```{terminal-shell} contree images import --help
+```
+
 ## See also
 
 - {doc}`tag` -- assign a tag to an image

docs/commands/operation.md

@@ -41,20 +41,23 @@ contree op cancel --all
 
 ## Help output
 
+The top-level `op` command is a dispatcher: by itself it only prints
+usage and routes to the three subcommands described below.
+
 ```{terminal-shell} contree op --help
 ```
 
-```{terminal-shell} contree op list --help
-```
+## `op list` -- dynamic columns
 
-```{terminal-shell} contree op show --help
-```
+`contree op list` (alias `op ls`) accepts the same filter flags as
+`contree ps` (`-a`, `-S STATUS`, `-K KIND`, `--since`, `--until`,
+`-q`/`--quiet`) and shares its rendering pipeline. Reach for it when
+you want the operations namespace to feel symmetric with the
+multi-UUID `show` and `cancel`; otherwise `contree ps` is just as good.
 
-```{terminal-shell} contree op cancel --help
+```{terminal-shell} contree op list --help
 ```
 
-## `op list` -- dynamic columns
-
 The listing renders **every scalar top-level field** the API returns,
 not a hard-coded subset. When the server adds a new field (for example
 `cost`, `project_id`, `started_at`), it appears in the output without a
@@ -81,6 +84,9 @@ work uniformly. On API errors (e.g. 404 for an unknown UUID), the
 command logs the failure and continues with the remaining UUIDs, exiting
 with status `1` at the end.
 
+```{terminal-shell} contree op show --help
+```
+
 :::{note}
 With table output (`-f table`) and several UUIDs, each operation
 currently renders as its own mini-table. Use `default` or `json` for a
@@ -95,6 +101,9 @@ operation (`PENDING`, `ASSIGNED`, `EXECUTING`). Combining both is allowed:
 with `op show`, errors on individual UUIDs do not abort the run; the
 command exits `1` if any cancellation failed.
 
+```{terminal-shell} contree op cancel --help
+```
+
 ```bash
 # Mixed: --all still wins, "ignored-1" is not cancelled
 contree op cancel --all ignored-1

docs/commands/session.md

@@ -56,9 +56,95 @@ branch just adds a new pointer at the current position.
 Rollback moves the branch pointer backwards. History entries are preserved
 and can be recovered by creating a new branch.
 
-## `session delete`
+## Subcommands
 
-Remove sessions and all their data (history, branches, files, shell history).
+### `session list`
+
+`contree session list` (alias `ls`) prints every session known to the
+current profile, with the active session marked. The optional
+`--filter` flag narrows the list by substring match against the session
+key, which is handy when you keep many disposable sessions named after
+features or tickets.
+
+```{terminal-shell} contree session list --help
+```
+
+### `session use`
+
+`contree session use KEY` imports the **current image** of another
+session into the active session as a new history entry. The source
+session is not modified; this is a "fork the snapshot, keep working
+here" operation, distinct from the top-level `contree use` which starts
+or resumes a session against an image reference.
+
+```{terminal-shell} contree session use --help
+```
+
+### `session branch`
+
+`contree session branch` (alias `br`) lists branches with `*` marking
+the active one. Pass a name to create a new branch pointing at the
+current history position, or combine with `--from BRANCH` to fork off a
+different branch. The `-U`/`--prune` flag removes branches that no
+longer reference live history.
+
+```{terminal-shell} contree session branch --help
+```
+
+### `session checkout`
+
+`contree session checkout BRANCH` (alias `co`) switches the active
+branch pointer. Working directory, pending files, and the current
+image are all reset to whatever the target branch currently points at,
+so it is the safe way to bounce between parallel experiments.
+
+```{terminal-shell} contree session checkout --help
+```
+
+### `session rollback`
+
+`contree session rollback [TARGET]` (alias `rb`) navigates the history
+of the current branch. With no argument it steps back one entry; a
+positive number jumps to that absolute history index, `-N` steps back
+`N` entries, and `+N` steps forward. History entries are preserved --
+rollback only moves the branch pointer.
+
+```{terminal-shell} contree session rollback --help
+```
+
+### `session show`
+
+`contree session show` prints the session history DAG with one row per
+entry, including operation IDs, image UUIDs, branch pointers, and
+relative timestamps. Use `-a` to include hidden entries, `-k KIND` to
+filter by entry kind (e.g. `run`, `cd`), and `-l LAST` to show only the
+last N rows.
+
+```{terminal-shell} contree session show --help
+```
+
+### `session wait`
+
+`contree session wait [OP_ID ...]` blocks until the specified operations
+reach a terminal state (`SUCCESS`, `FAILED`, or `CANCELLED`). When no
+IDs are given it waits for every active operation in the session, which
+is the canonical way to drain background `contree run -d` jobs before
+moving on.
+
+```{terminal-shell} contree session wait --help
+```
+
+### `session delete`
+
+`contree session delete KEY [KEY ...]` (aliases `rm`, `del`) removes
+sessions and all their data -- history, branches, pending files, shell
+history. The command prompts before deleting unless `-y` is passed.
+Use this to garbage-collect throwaway sessions; the disk savings on
+the SQLite database can be substantial when many short-lived sessions
+accumulate.
+
+```{terminal-shell} contree session delete --help
+```
 
 ```bash
 contree session delete KEY [KEY ...]