docs: Add egg-orch CLI documentation [doc-updater]

[james-in-a-box]

Update documentation to reflect the addition of the egg-orch CLI tool introduced in #636.

Changes

README.md:

• Added new "egg-orch CLI" section documenting the command groups (health, pipeline, signal, phase, decision, container, gateway, env)
• Noted that all commands support --json output and include help

docs/development/STRUCTURE.md:

• Added bin/egg-orch to the sandbox bin directory listing
• Added egg_lib/orch_cli.py to the container utility libraries section

docs/architecture/orchestrator.md:

• Added "CLI Access" subsection under API Endpoints
• Referenced the README CLI Reference for detailed command documentation

Context

The egg-orch CLI provides programmatic command-line access to the orchestrator API for:

• Pipeline management (create, list, get, delete, status)
• Agent signaling (complete, progress, error, heartbeat)
• Phase transitions (get, advance, start, complete)
• HITL decision queue operations
• Container lifecycle management
• Gateway operations (health, phase, permissions)

This tool is available in sandbox containers for agent use and can also be run from the host with appropriate environment variables.

Triggered By

Merged PR: #636
Commit: a811096 "Add egg-orch CLI for orchestrator API"

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns. This is a documentation-only PR adding CLI reference material — no agent workflow, prompt, or output format changes involved.

— Authored by egg

[egg-reviewer]

Documentation-only PR. All three files checked against the actual implementation. Findings:

All documented commands verified against sandbox/egg_lib/orch_cli.py — every command group and subcommand listed in the README table exists in the implementation, and the --json claim is accurate (applied universally via _add_json_flag() helper).

One minor inconsistency:

STRUCTURE.md — inconsistent comment style for symlinks (docs/development/STRUCTURE.md):
egg-contract and egg-checkpoint are annotated as "Symlink to contract_cli.py" / "Symlink to checkpoint_cli.py", but the new egg-orch entry just says "Orchestrator API CLI". Since egg-orch is also a symlink (-> ../egg_lib/orch_cli.py), this should follow the same pattern:

│   ├── egg-orch            # Symlink to orch_cli.py

This keeps the STRUCTURE.md internally consistent — the "what it does" description already lives on the egg_lib/orch_cli.py line below.

This is non-blocking. Everything else looks correct — the README table accurately reflects the CLI, the orchestrator.md cross-reference and anchor link are valid, and the egg_lib/ listing is properly structured.

— Authored by egg

[james-in-a-box]

Agreed. Updated the egg-orch comment in STRUCTURE.md to follow the symlink annotation convention used by egg-contract and egg-checkpoint: # Symlink to orch_cli.py.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns. The delta since last review is a single documentation consistency fix (STRUCTURE.md comment style) addressing the general review bot's feedback. No agent workflow, prompt, or output format changes involved.

— Authored by egg

[egg-reviewer]

Re-review after commit 55d046a ("Fix STRUCTURE.md egg-orch comment to match symlink convention").

Previous feedback addressed: The egg-orch entry in STRUCTURE.md now follows the symlink annotation convention (# Symlink to orch_cli.py) consistent with egg-contract and egg-checkpoint. Verified correct.

Delta review: The only change since e7d5559 is this single-line comment fix in docs/development/STRUCTURE.md. No new issues.

Verification against implementation:

• sandbox/bin/egg-orch confirmed as symlink to ../egg_lib/orch_cli.py
• All command groups in README table (health, pipeline, signal, phase, decision, container, gateway, env) verified against orch_cli.py command parsers and handler functions
• --json flag confirmed applied universally via _add_json_flag() helper
• Cross-reference anchor README.md#egg-orch-cli resolves correctly to the ### egg-orch CLI heading
• orchestrator.md CLI Access section accurately describes the tool and its location

No issues found.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.