infocyph · abmmhasan · Sep 24, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -7,6 +7,8 @@ on:
       - "plan/**"
       - "feature/**"
       - "graphify/**"
+      - "core-cli/**"
+      - "lds-core-cli/**"
   pull_request:
   schedule:
     # Related moving latest images refresh weekly; re-run the full compatibility
@@ -41,6 +43,14 @@ jobs:
       - name: CLI contract
         run: tests/cli-contract.sh
 
+      - name: Execution baseline contract
+        run: tests/execution-contract.sh
+
+      - name: Container execution substrate contract
+        run: tests/container-exec-contract.sh
+
+
+
       - name: Environment contract
         run: tests/env-contract.sh
 

diff --git a/README.md b/README.md
@@ -343,6 +343,36 @@ lds clean --global --yes
 
 That global mode can remove unrelated stopped containers, unused images/networks, build cache, and optionally volumes. `lds down --volumes --yes` is also destructive and should not be used for normal upgrades.
 
+## Execution and shells
+
+`lds shell` is the canonical execution navigator. With no arguments it presents a numbered catalog grouped as **Applications / Domains**, **Application Directories**, **Services**, **Containers**, and **Utilities**; choose by number, exact name, or a qualified selector.
+
+```bash
+# Interactive grouped selector.
+lds shell
+
+# Domain/application-aware shell and command.
+lds shell project.localhost
+lds shell project.localhost -- php artisan about
+
+# Current-project service or exact container.
+lds shell php84 -- php -v
+
+# Direct server-tools /app child fallback.
+lds shell billing
+
+# Reserved Tools target.
+lds shell tools -- jq --version
+
+# Intentional shell syntax or interactive TUI.
+lds shell tools --shell 'printf "%s\n" "hello world" | cat'
+lds shell tools --interactive lazydocker
+```
+
+Explicit unqualified targets resolve in this order: discovered domain, reserved `tools`, exact current-project service, exact container, then an exact direct child under `server-tools:/app`. Qualified `domain:`, `app:`, `service:`, `container:`, and `utility:tools` selectors bypass collisions. Image names are not implicitly instantiated.
+
+Normal commands preserve argv rather than being flattened into a shell string. Interactive shells/TUIs require a real TTY; piped/non-interactive commands do not force one. `core`, `cli`, `stack exec`, `exec`, and execution-oriented `tools` commands remain compatibility surfaces during migration. See `docs/reference/cli.rst` for target resolution and exit-code details.
+
 ## Ad-hoc Dockerfile runner
 
 From a directory containing a Dockerfile:

diff --git a/docs/concepts/architecture.rst b/docs/concepts/architecture.rst
@@ -20,6 +20,23 @@ Host Orchestration
 ``configuration/compose/``
    Generated runtime Compose fragments discovered and merged into the effective stack.
 
+Execution Navigation
+--------------------
+
+``lds shell`` is the canonical host-side execution and navigation surface. It resolves
+discovered domains, direct application directories under ``server-tools:/app``, exact
+current-project Compose services, exact Docker containers, and the trusted Tools target
+into one normalized execution context.
+
+Unqualified targets resolve deterministically in this order: discovered domain,
+``tools``, exact Compose service, exact Docker container, then an exact direct child
+under ``/app``. Qualified ``domain:``, ``app:``, ``service:``, ``container:``, and
+``utility:tools`` selectors bypass collisions.
+
+The compatibility commands ``core``, ``cli``, ``stack exec``, and the
+execution-oriented ``tools`` subcommands delegate to the same shell-context execution
+layer while retaining their intentionally narrower public contracts.
+
 Core Services
 -------------
 

diff --git a/docs/guides/databases-and-clients.rst b/docs/guides/databases-and-clients.rst
@@ -154,9 +154,12 @@ Check the whole stack with::
 Inspect a service directly with::
 
    lds logs postgres
-   lds stack exec postgres
+   lds shell service:postgres
    lds restart postgres
 
+The older ``lds stack exec postgres`` form remains available for service-only
+compatibility.
+
 Admin UIs
 ---------
 

diff --git a/docs/guides/domain-setup.rst b/docs/guides/domain-setup.rst
@@ -123,22 +123,31 @@ and Tools can include generated domain/service names.
 The wildcard covers built-in convenience endpoints such as ``admin.localhost``,
 ``webmail.localhost``, and ``llm-ollama.localhost``.
 
-Working in a Domain Container
------------------------------
+Working in a Domain or Application Context
+------------------------------------------
 
-Resolve a domain to its application/runtime container and open a shell::
+Use the canonical shell navigator to resolve a discovered domain to its
+application/runtime container and working directory::
 
-   lds core project.localhost
+   lds shell project.localhost
 
-When no domain is supplied, ``lds core`` lists known domains and prompts on an
-interactive terminal.
+Run a command in that same resolved application context without losing argv boundaries::
 
-A direct container name can also be supplied to ``lds core``.
+   lds shell project.localhost -- php artisan about
 
-For a generic container shell/command flow use::
+With no target, ``lds shell`` opens the grouped selector and includes discovered
+domains, direct application directories under ``server-tools:/app``, services,
+containers, and Tools.
 
-   lds cli <container>
-   lds cli <container> <command...>
+Use qualified selectors when you want a specific target class or a name is ambiguous::
+
+   lds shell domain:project.localhost
+   lds shell app:project
+   lds shell service:php84
+   lds shell container:localdevstack-php84-1
+
+``lds core`` and ``lds cli`` remain compatibility commands, but new workflows
+should use ``lds shell``.
 
 Diagnostics
 -----------

diff --git a/docs/guides/local-ai.rst b/docs/guides/local-ai.rst
@@ -391,5 +391,15 @@ Troubleshooting
 Use ``lds logs llm-fastflow`` or ``lds logs llm-ollama`` only when you explicitly
 want the provider-specific service identity.
 
+For an interactive provider container through the canonical shell navigator, use the
+exact active service identity::
+
+   lds shell service:llm-fastflow
+   lds shell service:llm-ollama
+
+Only the active provider service is expected to exist. The logical ``llm`` alias belongs
+to stack/service operations and is not rewritten by the exact ``service:`` shell
+qualifier.
+
 If FastFlow was expected but not selected, verify ``/dev/accel/accel0`` and the host
 ``amdxdna`` driver before forcing ``lds llm runtime npu``.
diff --git a/docs/guides/operations-and-support.rst b/docs/guides/operations-and-support.rst
@@ -47,13 +47,17 @@ Status and Logs
 ``lds status`` delegates the richer status view to Tools. ``lds ps`` uses Compose
 directly.
 
-Execute a command in a service::
+Execute a command in an exact current-project service through the canonical
+execution surface::
 
-   lds stack exec nginx nginx -t
+   lds shell service:nginx -- nginx -t
 
-Open an interactive shell when no command is supplied::
+Open an interactive shell in that service::
 
-   lds stack exec nginx
+   lds shell service:nginx
+
+``lds stack exec nginx ...`` and the top-level ``lds exec nginx ...`` alias remain
+service-only compatibility forms.
 
 Stack Diff
 ----------

diff --git a/docs/guides/secrets-sops-age.rst b/docs/guides/secrets-sops-age.rst
@@ -35,12 +35,12 @@ The LocalDevStack command::
 delegates directly to the Tools ``senv`` command inside the running ``server-tools``
 container.
 
-Use::
+Use the canonical Tools shell target::
 
-   lds tools sh
+   lds shell tools
 
 when you need to inspect the trusted Tools environment interactively before running a
-manual SOPS/Age operation.
+manual SOPS/Age operation. ``lds tools sh`` remains a compatibility form.
 
 Trust Boundary
 --------------