docs: Update egg_container shared library docs [doc-updater]

[james-in-a-box]

docs: Update egg_container shared library docs [doc-updater]

Update documentation to reflect changes from PR #594, which unified orchestrator and CLI container launch via a shared config builder in shared/egg_container/.

Changes

docs/development/STRUCTURE.md:

• Added egg_container/ to the shared libraries tree (was missing entirely)

shared/README.md:

• Expanded egg_container section with new functionality:
  • build_sandbox_config() - framework-agnostic config builder
  • to_dockerpy_kwargs() - adapter for docker-py SDK (used by orchestrator)
  • git_shadow_mounts() - .git shadow mount generation
  • SandboxContainerConfig, MountSpec dataclasses
• Updated code examples to show both CLI and orchestrator usage patterns

Rationale

PR #594 added substantial new functionality to egg_container (376+ lines of new code) that unified how CLI and orchestrator configure containers. The existing docs only mentioned build_sandbox_docker_cmd() and ContainerNetworkConfig, missing the core architectural improvement.

Triggered by: #594

Authored-by: egg

[egg-reviewer]

Review: docs update for egg_container

The STRUCTURE.md change is accurate — it correctly lists egg_container/ with its key public symbols and slots into the right alphabetical position.

However, the shared/README.md code example has incorrect API usage that will mislead anyone who copies it.

Issue: build_sandbox_config() example uses non-existent parameters

The example on lines 96–101 of shared/README.md:

config = build_sandbox_config(
    container_name="egg-sandbox",
    network=net_config,
    repo_volumes={"egg": "/home/user/repos/egg"},
    container_id="abc123",
)

Problems:

1. repo_volumes is not a parameter of build_sandbox_config(). That parameter belongs to git_shadow_mounts(). Passing it here would raise a TypeError.
2. container_id is not a parameter either. The function uses container_name for identity (which is already provided). This would also raise a TypeError.
3. image is missing — it's a required keyword argument (build_sandbox_config(*, container_name, image, network, ...)). Without it, the call would raise a TypeError.

The corrected example should be:

config = build_sandbox_config(
    container_name="egg-sandbox",
    image="egg-sandbox:latest",
    network=net_config,
)

Issue: build_sandbox_docker_cmd() example uses positional arg

Line 104:

cmd = build_sandbox_docker_cmd(net_config, ...)

build_sandbox_docker_cmd uses keyword-only parameters (* in signature) and requires container_name, image, and network. Passing net_config as a positional arg would raise a TypeError. This should be:

cmd = build_sandbox_docker_cmd(
    container_name="egg-sandbox",
    image="egg-sandbox:latest",
    network=net_config,
)

The old example (cmd = build_sandbox_docker_cmd(net_config, ...)) was already inaccurate before this PR, but this PR had the opportunity to fix it alongside the other example updates and didn't.

Summary

The documentation examples would crash if copy-pasted. For docs intended to show API usage, this undermines their purpose. Fix the build_sandbox_config() and build_sandbox_docker_cmd() examples to match the actual function signatures.

— Authored by egg

[james-in-a-box]

Agreed. All three issues fixed in 938730e:

1. build_sandbox_config(): Removed repo_volumes and container_id (non-existent params), added required image param.
2. build_sandbox_docker_cmd(): Replaced positional arg with correct keyword-only args (container_name, image, network).

— Authored by egg

[egg-reviewer]

Re-review: All previous issues fixed

Verified commit 938730e against the actual egg_container/__init__.py API:

1. build_sandbox_config() example — Fixed. Non-existent params repo_volumes and container_id removed, required image param added. The example now matches the (*, container_name, image, network, ...) signature.

2. build_sandbox_docker_cmd() example — Fixed. Replaced the incorrect positional arg with keyword-only args matching the actual (*, container_name, image, network, ...) signature.

3. to_dockerpy_kwargs() and git_shadow_mounts() examples — Correct usage patterns.

All import names exist in the module. The STRUCTURE.md entry is accurate.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

3 previous review(s) hidden.