feat: unify Chronicle service operations

Author: AnkushMalaker

AGENTS.md

@@ -114,12 +114,25 @@ journalctl --user -u chronicle-service-manager
 journalctl --user -u chronicle-stack
 ```
 
-For an unmanaged node agent, inspect `edge/service-manager.log`. Container logs remain
-the next source for why a service exited. Direct commands such as
-`services.py restart`, `./restart.sh`, or raw Compose/Podman commands do **not** create
-service-operation ledger entries, so absence from the ledger does not prove a restart
-was automatic. Also check the relevant shell history or host journal when direct
-execution is plausible.
+For an unmanaged node agent, inspect `edge/service-manager.log`. Normal CLI and WebUI
+lifecycle commands report to the same ledger. Explicit `--direct` recovery, failed
+ledger reporting, and raw engine operations can leave no entry; absence does not
+prove an automatic restart.
+
+## Service operations
+
+For status, lifecycle, rebuilds, or unavailable-service reports, read
+[the service-management workflow](docs/init-system.md#service-management) first.
+Use `./services status --detailed`, then the CLI's `logs`, `inspect`, `doctor`, and
+`deployments --status` commands as appropriate. Start/stop/restart requires named
+groups or explicit `--all`; remote execution requires `--node` with a registered ID.
+LLM, wakeword, and TTS are managed groups. Normal actions wait for readiness and
+share WebUI operation tracking. Use explicit `--direct` only for local recovery
+without the manager; admission still applies.
+
+Use raw engine commands for evidence the CLI does not expose, isolated development,
+unmanaged services, or a broken CLI. State the gap before going lower-level and
+redact secrets. After repairs, exercise the affected capability as well as readiness.
 
 ## Initial Setup & Configuration
 
@@ -144,7 +157,7 @@ uv run --with-requirements setup-requirements.txt python wizard.py
 # For step-by-step instructions, see quickstart.md
 ```
 
-**Note on Convenience Scripts**: Chronicle provides wrapper scripts (`./wizard.sh`, `./start.sh`, `./restart.sh`, `./stop.sh`, `./status.sh`) that simplify the longer `uv run --with-requirements setup-requirements.txt python` commands. Use these for everyday operations.
+**Operator entry points**: Use `./wizard.sh` for configuration and `./services` for service management. See [service operations](#service-operations).
 
 **Temporary Tooling Rule**: When a Python tool or dependency is needed only for a one-off task, run it ephemerally with `uv run --with <package> ...`; do not install it into a project environment or add it to project dependencies. For a package-owned CLI, use `uvx --from <package> <entrypoint>`. This applies to browser automation, screenshots, data inspection, and other temporary utilities.
 
@@ -172,11 +185,12 @@ Key features:
 
 ### Backend Development (Chronicle Backend - Primary)
 ```bash
-cd backend
+# From the repository root, start the managed backend
+./services start backend
 
-# Start full stack with Docker
-docker compose up --build -d
+cd backend
 
+# Standalone development alternative (use an isolated configuration)
 uv run python src/main.py
 
 # Code formatting and linting
@@ -264,28 +278,21 @@ npm run web
 ```
 
 ### Additional Services
-```bash
-# ASR Services
-cd extras/asr-services
-docker compose up parakeet-asr   # Offline ASR with Parakeet
 
-# Speaker Recognition (with tests)
-cd extras/speaker-recognition
-docker compose up --build
-./run-test.sh  # Run speaker recognition integration tests
+Start configured service groups from the repository root:
 
-# HAVPE Relay (ESP32 bridge)
-cd extras/havpe-relay
-docker compose up --build
-
-# TTS Services (text-to-speech, run ONE provider at a time on port 8770)
-cd extras/tts
-docker compose up tada-tts -d --build        # HumeAI TADA (GPU, voice cloning)
-docker compose up fish-tts -d --build        # Fish Speech (GPU, 50+ langs, emotion tags)
-docker compose up kittentts-tts -d --build   # KittenTTS (~25MB CPU ONNX, no GPU)
-docker compose up kokoro-tts -d --build       # Kokoro-82M (<~1GB VRAM GPU/CPU, preset voices)
+```bash
+./services start asr-services
+./services start speaker-recognition
+./services start tts
 ```
 
+Choose the ASR/TTS provider through setup or the WebUI System controls. For builds,
+provider changes, and diagnostics, follow the
+[service-management workflow](docs/init-system.md#service-management).
+Speaker recognition integration tests remain in `extras/speaker-recognition/run-test.sh`.
+The HAVPE relay has its own lifecycle; see `extras/havpe-relay/` for its setup.
+
 ## Architecture Overview
 
 ### Unknown speaker invariant
@@ -605,9 +612,8 @@ Provider-based text-to-speech (`extras/tts/`), built on the same provider patter
 # Configure (selects provider, model, CUDA version) — from the repository root
 uv run --with-requirements setup-requirements.txt python extras/tts/init.py
 
-# Start ONE provider
-cd extras/tts
-docker compose up tada-tts -d --build       # or fish-tts / kittentts-tts
+# Start the configured provider through the managed TTS group
+./services start tts
 
 # Test
 curl http://localhost:8770/health
@@ -625,7 +631,7 @@ curl -X POST http://localhost:8770/synthesize -F "text=Hello world." -o output.w
 **POST /synthesize** — `text` (required); optional `reference_audio` (WAV) + `reference_text` for voice cloning; optional generation params (`temperature`, `top_p`, `repetition_penalty`, `seed`, `max_new_tokens`). Returns WAV bytes with `X-Sample-Rate`, `X-Provider`, `X-Model` headers.
 
 **Notes:**
-- Not registered in `services.py` — manage with `docker compose` directly (like the HAVPE relay).
+- Registered as `tts` in `services.py`; select the provider via setup or the WebUI System controls. See [service management](docs/init-system.md#service-management).
 - GPU providers require CUDA 12.6+ (`PYTORCH_CUDA_VERSION=cu126`/`cu128`); `cu121` is unsupported (torch>=2.7).
 - Add a provider by creating `extras/tts/providers/{name}/` with `service.py`, `synthesizer.py`, and `Dockerfile` (subclass `BaseTTSService`).
 - An optional `edge-agent` sidecar (`--profile edge`) advertises the service on the Tailnet.
@@ -636,22 +642,18 @@ curl -X POST http://localhost:8770/synthesize -F "text=Hello world." -o output.w
 
 **Single Machine (Default):**
 ```bash
-# Everything on one machine
-docker compose up --build -d
+# Start configured services assigned to this node
+./services start --all
 ```
 
 **Distributed Setup (GPU + Backend separation):**
 
 #### GPU Machine Setup
 ```bash
-# Start GPU-accelerated services
-cd extras/asr-services
-docker compose up moonshine -d
+# From the repository root on the GPU node, start configured service groups
+./services start asr-services speaker-recognition
 
-cd extras/speaker-recognition
-docker compose up --build -d
-
-# Ollama with GPU support
+# Optional external Ollama, outside Chronicle's managed service registry
 docker run -d --gpus=all -p 11434:11434 \
   -v ollama:/root/.ollama \
   ollama/ollama:latest
@@ -664,8 +666,8 @@ OLLAMA_BASE_URL=http://[gpu-machine-tailscale-ip]:11434
 SPEAKER_SERVICE_URL=http://[gpu-machine-tailscale-ip]:8085
 PARAKEET_ASR_URL=http://[gpu-machine-tailscale-ip]:8080
 
-# Start lightweight backend services
-docker compose up --build -d
+# From the repository root, start the managed backend
+./services start backend
 ```
 
 #### Tailscale Networking
@@ -817,7 +819,7 @@ For temporary Python-backed tooling that is not part of the repo dependencies, p
 - Prefer GPU acceleration whenever the workload and deployed service support it.
 
 **Container Engine (Docker or Podman):**
-- The project supports **both Docker and Podman**. The active engine is set by `container_engine` in `config/config.yml` (default `docker`); prefer the lifecycle scripts (`./start.sh`/`./stop.sh`/`./restart.sh`) which route through the selected engine. For one-off manual commands under Podman use `podman-compose` (not `docker compose`). See **[@docs/podman.md](docs/podman.md)**.
+- The project supports **both Docker and Podman**. The active engine is set by `container_engine` in `config/config.yml` (default `docker`); prefer the lifecycle scripts (`./services start --all`/`./services stop --all`/`./services restart --all`) which route through the selected engine. For the lower-level cases described in [service operations](#service-operations), use `podman-compose` under Podman. See **[@docs/podman.md](docs/podman.md)**.
 
 **Docker Build Guidelines:**
 - Use `docker compose build` (or `podman-compose build`) without `--no-cache` by default for faster builds

README.md

@@ -67,7 +67,8 @@ chronicle/
 ├── config/                 # Central configuration files
 ├── tests/                  # Integration & unit tests
 ├── wizard.py              # Root setup orchestrator
-├── services.py            # Service lifecycle manager
+├── services               # Operator CLI
+├── services.py            # Shared lifecycle implementation
 └── *.sh                   # Convenience scripts (wrappers)
 ```
 
@@ -113,34 +114,21 @@ chronicle/
 uv run --with-requirements setup-requirements.txt python wizard.py
 ```
 
-**Note**: Convenience scripts (*.sh) are wrappers around `wizard.py` and `services.py` that simplify the longer `uv run` commands.
+Use `./wizard.sh` for configuration and `./services` for operations.
 
 ### Service Management
-```bash
-# Start all configured services
-./start.sh
-
-# Restart all services (preserves containers)
-./restart.sh
-
-# Check service status
-./status.sh
-
-# Stop all services
-./stop.sh
-```
-
-<details>
-<summary>Full commands (click to expand)</summary>
 
 ```bash
-# What the convenience scripts wrap
-uv run --with-requirements setup-requirements.txt python services.py start --all --build
-uv run --with-requirements setup-requirements.txt python services.py restart --all
-uv run --with-requirements setup-requirements.txt python services.py status
-uv run --with-requirements setup-requirements.txt python services.py stop --all
+./services status --detailed
+./services start llm-services wakeword-service
+./services start --all
+./services restart backend
+./services stop --all
+./services logs wakeword-service --tail 100
 ```
-</details>
+
+Start/restart waits for readiness. See the [operator workflow](docs/init-system.md#service-management)
+for remote nodes, image builds, operation history, and explicit local recovery.
 
 ### Development
 ```bash

backend/docker-compose.yml

@@ -1,6 +1,6 @@
 # The Chronicle backend stack. What each service is for, and why the non-obvious
 # settings below are the way they are: docs/backend/compose-stack.md
-# Drive it with ./start.sh / ./stop.sh / ./restart.sh, not by hand.
+# Drive it with ./services start --all / ./services stop --all / ./services restart --all, not by hand.
 
 # Explicit DNS upstreams; Tailscale's resolver first. Without these, aardvark
 # (Podman) can silently stop forwarding external queries; with only public ones,

backend/webui/README.md

@@ -76,7 +76,7 @@ This starts:
 ## Deployment
 
 This project runs the Vite dev server (`webui-dev`) as the only webui — there is
-no separate static/nginx production build. The standard stack (`./start.sh`)
+no separate static/nginx production build. The standard stack (`./services start --all`)
 starts it on http://localhost:5173, and Caddy fronts it for HTTPS (microphone
 access, remote/Tailscale). Source is volume-mounted, so changes hot-reload with
 no rebuild.

backend/webui/src/components/ExternalServices.tsx

@@ -236,7 +236,7 @@ export default function ExternalServices({
     setLastFailedOp(null)
     if (service.name === 'backend' && action !== 'start') {
       const confirmed = window.confirm(
-        'Stopping the backend takes down this dashboard — you will need ./start.sh on the host to bring it back. Continue?'
+        'Stopping the backend takes down this dashboard — you will need ./services start backend on the host to bring it back. Continue?'
       )
       if (!confirmed) return
     }
@@ -391,8 +391,7 @@ export default function ExternalServices({
           </h3>
           <p className="text-sm text-gray-500 dark:text-gray-400">
             Service manager agent is not reachable. Start it on the host with{' '}
-            <code className="px-1 bg-gray-100 dark:bg-gray-700 rounded">./start.sh</code> or{' '}
-            <code className="px-1 bg-gray-100 dark:bg-gray-700 rounded">uv run python services.py manager start</code>.
+            <code className="px-1 bg-gray-100 dark:bg-gray-700 rounded">./services manager start</code>.
           </p>
         </Card>
       )

backend/webui/src/components/RemoteControl.tsx

@@ -136,7 +136,7 @@ export default function RemoteControl({ isAdmin }: { isAdmin: boolean }) {
       <p className="mt-3 text-xs text-gray-500 dark:text-gray-400">
         Backed by a tmux session (<code className="text-xs">tmux attach -t {data.session ?? 'chronicle-rc'}</code> at
         the desktop). Make it survive reboots from the wizard's "auto-start on boot" step, or{' '}
-        <code className="text-xs">services.py remote-control install</code>.
+        <code className="text-xs">./services remote-control install</code>.
       </p>
     </Card>
   )

deployment_guard.py

@@ -0,0 +1,114 @@
+"""Host-side admission adapter shared by CLI, boot and node-agent operations."""
+
+import os
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+
+import requests
+import yaml
+from dotenv import dotenv_values
+
+from service_deployments import PlacementError, Plan
+
+_held = ContextVar("deployment_activations", default=frozenset())
+
+
+def placement_config(root: Path) -> dict:
+    path = root / "config" / "config.yml"
+    if not path.exists():
+        return {}
+    config = yaml.safe_load(path.read_text()) or {}
+    return config.get("service_placement") or {}
+
+
+def control_token(root: Path) -> str:
+    return (
+        os.getenv("SERVICE_PLACEMENT_TOKEN")
+        or dotenv_values(root / "backend" / ".env").get("SERVICE_PLACEMENT_TOKEN")
+        or ""
+    )
+
+
+def control_headers(root: Path) -> dict:
+    token = control_token(root)
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+
+def local_services(root: Path, services: list[str]) -> list[str]:
+    """Select bulk activation targets; admission still fences each activation.
+
+    Groups absent from the plan remain node-local. Both primary and warm standby
+    instances are eligible. An unreadable plan must never become permission to
+    start every enabled service.
+    """
+    cfg = placement_config(root)
+    if not cfg:
+        return services
+    url = cfg.get("coordinator_url", "").rstrip("/")
+    node = cfg.get("node_id")
+    if not url or not node:
+        raise PlacementError("service_placement requires coordinator_url and node_id")
+    try:
+        response = requests.get(
+            f"{url}/deployments", headers=control_headers(root), timeout=15
+        )
+        response.raise_for_status()
+        plan = Plan.model_validate(response.json()["plan"])
+    except (requests.RequestException, ValueError, KeyError, TypeError) as exc:
+        raise PlacementError(
+            f"Cannot read deployment plan; refusing bulk activation: {exc}"
+        ) from exc
+    if node not in plan.nodes:
+        raise PlacementError(
+            f"Register node {node} in the deployment plan before starting services"
+        )
+    return [
+        name
+        for name in services
+        if name not in plan.deployments
+        or any(instance.node == node for instance in plan.deployments[name].instances)
+    ]
+
+
+@contextmanager
+def activation(root: Path, service: str, *, stop_revision: int | None = None):
+    cfg = placement_config(root)
+    if not cfg or service in _held.get():
+        yield
+        return
+    url = cfg.get("coordinator_url", "").rstrip("/")
+    node = cfg.get("node_id")
+    if not url or not node:
+        raise PlacementError("service_placement requires coordinator_url and node_id")
+    try:
+        response = requests.post(
+            f"{url}/deployments/activate",
+            json={"service": service, "node": node, "stop_revision": stop_revision},
+            headers=control_headers(root),
+            timeout=60,
+        )
+        if not response.ok:
+            raise PlacementError(response.json().get("detail", response.text))
+        token = response.json().get("token")
+    except requests.RequestException as exc:
+        raise PlacementError(
+            f"Deployment authority unavailable; refusing activation: {exc}"
+        ) from exc
+    marker = _held.set(_held.get() | {service})
+    try:
+        yield
+    finally:
+        _held.reset(marker)
+        if token:
+            try:
+                response = requests.delete(
+                    f"{url}/deployments/activations/{token}",
+                    headers=control_headers(root),
+                    timeout=15,
+                )
+                response.raise_for_status()
+            except requests.RequestException as exc:
+                raise PlacementError(
+                    f"Activation completed but reservation {token} could not be released: {exc}"
+                ) from exc