docs: update CLI reference to match actual code

cli.md:
- Document `start`/`stop` as preferred commands (`up`/`down` as legacy)
- Add --skip-cluster-management flag for start and stop
- Add --delete-volumes flag for stop
- Add missing subcommands: restart, exec, status, port, push-images, run-job
- Add --helm-chart option to deploy create
- Reorganize deploy vs deployment sections for clarity

deployment_patterns.md:
- Add missing --stack flag to deploy create example

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/cli.md

@@ -68,7 +68,7 @@ $ laconic-so build-npms --include <package-name> --force-rebuild
 
 ## deploy
 
-The `deploy` command group manages persistent deployments. The general workflow is `deploy init` to generate a spec file, then `deploy create` to create a deployment directory from the spec, then runtime commands like `deploy up` and `deploy down`.
+The `deploy` command group manages persistent deployments. The general workflow is `deploy init` to generate a spec file, then `deploy create` to create a deployment directory from the spec, then runtime commands like `deployment start` and `deployment stop`.
 
 ### deploy init
 
@@ -101,35 +101,91 @@ Options:
 - `--spec-file` (required): spec file to use
 - `--deployment-dir`: target directory for deployment files
 - `--update`: update an existing deployment directory, preserving data volumes and env file. Changed files are backed up with a `.bak` suffix. The deployment's `config.env` and `deployment.yml` are also preserved.
+- `--helm-chart`: generate Helm chart instead of deploying (k8s only)
 - `--network-dir`: network configuration supplied in this directory
 - `--initial-peers`: initial set of persistent peers
 
-### deploy up
+## deployment
 
-Start a deployment:
+Runtime commands for managing a created deployment. Use `--dir` to specify the deployment directory.
+
+### deployment start
+
+Start a deployment (`up` is a legacy alias):
 ```
-$ laconic-so deployment --dir <deployment-dir> up
+$ laconic-so deployment --dir <deployment-dir> start
 ```
 
-### deploy down
+Options:
+- `--stay-attached` / `--detatch-terminal`: attach to container stdout (default: detach)
+- `--skip-cluster-management` / `--perform-cluster-management`: skip kind cluster creation/teardown (default: perform management). Only affects k8s-kind deployments. Use this when multiple stacks share a single cluster.
 
-Stop a deployment:
-```
-$ laconic-so deployment --dir <deployment-dir> down
-```
-Use `--delete-volumes` to also remove data volumes.
+### deployment stop
 
-### deploy ps
+Stop a deployment (`down` is a legacy alias):
+```
+$ laconic-so deployment --dir <deployment-dir> stop
+```
+
+Options:
+- `--delete-volumes` / `--preserve-volumes`: delete data volumes on stop (default: preserve)
+- `--skip-cluster-management` / `--perform-cluster-management`: skip kind cluster teardown (default: perform management). Use this to stop a single deployment without destroying a shared cluster.
+
+### deployment restart
+
+Restart a deployment with GitOps-aware workflow. Pulls latest stack code, syncs the deployment directory from the git-tracked spec, and restarts services:
+```
+$ laconic-so deployment --dir <deployment-dir> restart
+```
+
+See [deployment_patterns.md](deployment_patterns.md) for the recommended GitOps workflow.
+
+### deployment ps
 
 Show running services:
 ```
 $ laconic-so deployment --dir <deployment-dir> ps
 ```
 
-### deploy logs
+### deployment logs
 
 View service logs:
 ```
 $ laconic-so deployment --dir <deployment-dir> logs
 ```
 Use `-f` to follow and `-n <count>` to tail.
+
+### deployment exec
+
+Execute a command in a running service container:
+```
+$ laconic-so deployment --dir <deployment-dir> exec <service-name> "<command>"
+```
+
+### deployment status
+
+Show deployment status:
+```
+$ laconic-so deployment --dir <deployment-dir> status
+```
+
+### deployment port
+
+Show mapped ports for a service:
+```
+$ laconic-so deployment --dir <deployment-dir> port <service-name> <port>
+```
+
+### deployment push-images
+
+Push deployment images to a registry:
+```
+$ laconic-so deployment --dir <deployment-dir> push-images
+```
+
+### deployment run-job
+
+Run a one-time job in the deployment:
+```
+$ laconic-so deployment --dir <deployment-dir> run-job <job-name>
+```

docs/deployment_patterns.md

@@ -30,7 +30,7 @@ git commit -m "Add my-stack deployment configuration"
 git push
 
 # On deployment server: deploy from git-tracked spec
-laconic-so deploy create \
+laconic-so --stack my-stack deploy create \
   --spec-file /path/to/operator-repo/spec.yml \
   --deployment-dir my-deployment
 

stack_orchestrator/constants.py

@@ -29,6 +29,7 @@ network_key = "network"
 http_proxy_key = "http-proxy"
 image_registry_key = "image-registry"
 configmaps_key = "configmaps"
+secrets_key = "secrets"
 resources_key = "resources"
 volumes_key = "volumes"
 security_key = "security"

stack_orchestrator/deploy/deployment_create.py

@@ -477,6 +477,9 @@ def init_operation(
             spec_file_content["volumes"] = {**volume_descriptors, **orig_volumes}
         if configmap_descriptors:
             spec_file_content["configmaps"] = configmap_descriptors
+        if "k8s" in deployer_type:
+            if "secrets" not in spec_file_content:
+                spec_file_content["secrets"] = {}
 
     if opts.o.debug:
         print(

stack_orchestrator/deploy/k8s/cluster_info.py

@@ -394,14 +394,6 @@ class ClusterInfo:
             result.append(pv)
         return result
 
-    def _any_service_has_host_network(self):
-        for pod_name in self.parsed_pod_yaml_map:
-            pod = self.parsed_pod_yaml_map[pod_name]
-            for svc in pod.get("services", {}).values():
-                if svc.get("network_mode") == "host":
-                    return True
-        return False
-
     # TODO: put things like image pull policy into an object-scope struct
     def get_deployment(self, image_pull_policy: Optional[str] = None):
         containers = []
@@ -491,6 +483,16 @@ class ClusterInfo:
                         )
                     )
                 ]
+                # Mount user-declared secrets from spec.yml
+                for user_secret_name in self.spec.get_secrets():
+                    env_from.append(
+                        client.V1EnvFromSource(
+                            secret_ref=client.V1SecretEnvSource(
+                                name=user_secret_name,
+                                optional=True,
+                            )
+                        )
+                    )
                 container = client.V1Container(
                     name=container_name,
                     image=image_to_use,
@@ -576,7 +578,6 @@ class ClusterInfo:
                     )
                 )
 
-        use_host_network = self._any_service_has_host_network()
         template = client.V1PodTemplateSpec(
             metadata=client.V1ObjectMeta(annotations=annotations, labels=labels),
             spec=client.V1PodSpec(
@@ -586,10 +587,6 @@ class ClusterInfo:
                 affinity=affinity,
                 tolerations=tolerations,
                 runtime_class_name=self.spec.get_runtime_class(),
-                host_network=use_host_network or None,
-                dns_policy=(
-                    "ClusterFirstWithHostNet" if use_host_network else None
-                ),
             ),
         )
         spec = client.V1DeploymentSpec(

stack_orchestrator/deploy/k8s/helpers.py

@@ -683,35 +683,11 @@ def _generate_kind_port_mappings_from_services(parsed_pod_files):
 
 def _generate_kind_port_mappings(parsed_pod_files):
     port_definitions = []
-    seen = set()
     # Map port 80 and 443 for the Caddy ingress controller (HTTPS support)
     for port_string in ["80", "443"]:
         port_definitions.append(
             f"  - containerPort: {port_string}\n    hostPort: {port_string}\n"
         )
-        seen.add((port_string, "TCP"))
-    # Map ports declared in compose services
-    for pod in parsed_pod_files:
-        parsed_pod_file = parsed_pod_files[pod]
-        if "services" in parsed_pod_file:
-            for service_name in parsed_pod_file["services"]:
-                service_obj = parsed_pod_file["services"][service_name]
-                for port_entry in service_obj.get("ports", []):
-                    port_str = str(port_entry)
-                    protocol = "TCP"
-                    if "/" in port_str:
-                        port_str, proto = port_str.split("/", 1)
-                        protocol = proto.upper()
-                    if ":" in port_str:
-                        port_str = port_str.split(":")[-1]
-                    port_num = port_str.strip("'\"")
-                    if (port_num, protocol) not in seen:
-                        seen.add((port_num, protocol))
-                        port_definitions.append(
-                            f"  - containerPort: {port_num}\n"
-                            f"    hostPort: {port_num}\n"
-                            f"    protocol: {protocol}\n"
-                        )
     return (
         ""
         if len(port_definitions) == 0

stack_orchestrator/deploy/spec.py

@@ -115,6 +115,9 @@ class Spec:
     def get_configmaps(self):
         return self.obj.get(constants.configmaps_key, {})
 
+    def get_secrets(self):
+        return self.obj.get(constants.secrets_key, {})
+
     def get_container_resources(self):
         return Resources(
             self.obj.get(constants.resources_key, {}).get("containers", {})

tests/scripts/run-test-local.sh

@@ -1,53 +0,0 @@
-#!/bin/bash
-# Run a test suite locally in an isolated venv.
-#
-# Usage:
-#   ./tests/scripts/run-test-local.sh <test-script>
-#
-# Examples:
-#   ./tests/scripts/run-test-local.sh tests/webapp-test/run-webapp-test.sh
-#   ./tests/scripts/run-test-local.sh tests/smoke-test/run-smoke-test.sh
-#   ./tests/scripts/run-test-local.sh tests/k8s-deploy/run-deploy-test.sh
-#
-# The script creates a temporary venv, installs shiv, builds the laconic-so
-# package, runs the requested test, then cleans up.
-
-set -euo pipefail
-
-if [ $# -lt 1 ]; then
-  echo "Usage: $0 <test-script> [args...]"
-  exit 1
-fi
-
-TEST_SCRIPT="$1"
-shift
-
-if [ ! -f "$TEST_SCRIPT" ]; then
-  echo "Error: $TEST_SCRIPT not found"
-  exit 1
-fi
-
-REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-VENV_DIR=$(mktemp -d /tmp/so-test-XXXXXX)
-
-cleanup() {
-  echo "Cleaning up venv: $VENV_DIR"
-  rm -rf "$VENV_DIR"
-}
-trap cleanup EXIT
-
-cd "$REPO_DIR"
-
-echo "==> Creating venv in $VENV_DIR"
-python3 -m venv "$VENV_DIR"
-source "$VENV_DIR/bin/activate"
-
-echo "==> Installing shiv"
-pip install -q shiv
-
-echo "==> Building laconic-so package"
-./scripts/create_build_tag_file.sh
-./scripts/build_shiv_package.sh
-
-echo "==> Running: $TEST_SCRIPT $*"
-exec "./$TEST_SCRIPT" "$@"