From ef1d6b517da84d6898d05e2292b37426b06c0cc2 Mon Sep 17 00:00:00 2001
From: Markus Fritsche <fritsche.markus@gmail.com>
Date: Fri, 24 Jul 2026 09:22:24 +0200
Subject: [PATCH] =?UTF-8?q?README:=20document=20nesting=20=E2=80=94=20the?=
 =?UTF-8?q?=20nested-container-hop=20feature=20(V2)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README covered only single-host use; the differentiator from a shell helper
— reaching into containers several hops deep with the argv frame preserved at
every layer — was undocumented. Add a Nesting section (host/guest/svc syntax,
/etc/sic/hosts.toml nest stanzas, and the quoting-hell contrast with the ssh
equivalent), surface it in the intro line, and link docs/design-nested.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EWpfhDgYNA21tETDP9ueBE
---
 README.md | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index edb2a2f..cc12349 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # sic
 
-Run a command on a remote host without a shell re-parsing its arguments.
+Run a command on a remote host — or inside a container several hops deep —
+without a shell re-parsing its arguments.
 
 `ssh host touch 'a b'` creates two files: `ssh` joins its arguments with spaces
 and hands the result to the remote login shell, which splits it again. `sic host
@@ -50,6 +51,38 @@ sic host1 echo '$HOME'               # literal, no expansion
 sic --sh host1 'echo hi | wc -c'
 ```
 
+## Nesting
+
+The frame survives being wrapped again, so `sic` reaches *into* containers with no
+shell anywhere in the path, at any depth. A target is a host followed by container
+hops separated by `/`:
+
+```
+sic host1/app cat /etc/os-release     # into the 'app' guest on host1
+sic host2/ct/svc touch 'a b'          # host2 -> ct -> svc, ONE file, three layers deep
+```
+
+Each host's hop runtimes come from `/etc/sic/hosts.toml`, one stanza per host:
+
+```toml
+[host1]
+nest = ["incus"]            # host1/app     ->  incus exec app -- <argv>
+
+[host2]
+nest = ["pct", "docker"]    # host2/ct/svc  ->  pct exec ct -- docker exec svc -- <argv>
+```
+
+This is what separates `sic` from a shell helper script. The `ssh` equivalent —
+
+```
+ssh host2 "pct exec ct -- docker exec svc -- touch \"a b\""
+```
+
+nests quotes inside quotes inside quotes, and every layer re-splits the arguments; a
+body containing a space, `$()`, a pipe, or a newline breaks a different layer each time.
+`sic` frames the argv once and re-frames it at each hop, so `touch 'a b'` is one file
+whether it runs on the host or three containers deep. No escaping, at any level.
+
 ## Build
 
 ```
@@ -88,5 +121,6 @@ sic host echo hello world
 ## See also
 
 - `docs/design.md` — wire format, exec modes, transport and security, prior art.
+- `docs/design-nested.md` — how nested container hops resolve.
 - `demos/quoting-hell.py` — six cases run both ways, plain `ssh` versus `sic`.
 - `SKILL.md`, `SKILL-bg.md` — agent skill definitions (foreground and background).