RHL-019 refactor(docs): enhance frontend API usage and runbook documentation with additional details and examples

Docs/frontend-api-usage.md

@@ -1,3 +1,13 @@
+<!-- --------------------------------------------------------------------------- -->
+
+<!-- Folder: Docs -->
+
+<!-- File: frontend-api-usage.md -->
+
+<!-- Relative Path: Docs/frontend-api-usage.md -->
+
+<!-- --------------------------------------------------------------------------- -->
+
 # Frontend API Usage (v1)
 
 This document is the **frontend-facing** single source of truth for consuming the Lieferscheine backend APIs.
@@ -8,6 +18,10 @@ Scope:
 - The minimal frontend `apiClient` helper layer (`lib/frontend/apiClient.js`).
 - Practical examples for building the first UI.
 
+> UI developers: For the app shell layout and frontend route scaffold (public vs protected routes, placeholder pages), see **`Docs/frontend-ui.md`**.
+>
+> For UI navigation, prefer centralized route builders from `lib/frontend/routes.js` instead of hardcoding path strings.
+
 Non-goals:
 
 - New major features.
@@ -86,6 +100,33 @@ export async function runExampleFlow() {
 }
 ```
 
+### 1.4 Frontend route helpers (UI navigation)
+
+File:
+
+- `lib/frontend/routes.js`
+
+Purpose:
+
+- Centralize URL building so UI code does not scatter hardcoded strings.
+- Encode dynamic segments defensively.
+
+Example:
+
+```js
+import {
+	branchPath,
+	dayPath,
+	searchPath,
+	loginPath,
+} from "@/lib/frontend/routes";
+
+const loginUrl = loginPath();
+const branchUrl = branchPath("NL01");
+const dayUrl = dayPath("NL01", "2025", "12", "31");
+const searchUrl = searchPath("NL01");
+```
+
 ---
 
 ## 2. The `apiClient` helper
@@ -413,6 +454,7 @@ As of RHL-008, the endpoints and response shapes documented here are considered
 Rules:
 
 - Avoid breaking changes to existing URLs, parameters, or response fields.
+
 - Prefer additive changes:
 
   - add new endpoints

Docs/runbook.md

@@ -1,3 +1,13 @@
+<!-- --------------------------------------------------------------------------- -->
+
+<!-- Folder: Docs -->
+
+<!-- File: runbook.md -->
+
+<!-- Relative Path: Docs/runbook.md -->
+
+<!-- --------------------------------------------------------------------------- -->
+
 # Runbook: Local Development vs Server Deployment
 
 This runbook describes how to run the project locally (developer machine) and on the internal server.
@@ -23,6 +33,12 @@ The goal is a **clean separation** between:
   - Local override
   - Mounts local fixtures: `./.local_nas:/mnt/niederlassungen:ro`
 
+- `docker-compose.server-tools.yml` (optional)
+
+  - Server-only tooling/override compose file.
+  - Intended for additional server services or operational tooling.
+  - Usually enabled on the server via `COMPOSE_FILE` or `-f` flags.
+
 ### 1.2 Env files
 
 - Committed templates:
@@ -38,7 +54,7 @@ The goal is a **clean separation** between:
 
   - `.env.server`
 
-The compose file uses:
+The compose setup uses:
 
 - `ENV_FILE` to select which env file is loaded into the `app` container.
 
@@ -260,6 +276,12 @@ Use the base compose file only (no local override):
 ENV_FILE=.env.server docker compose -f docker-compose.yml up -d --build
 ```
 
+> If you configured a server-local `.env` file (see 3.4.1 / 3.4.2), you can use the short form:
+>
+> ```bash
+> docker compose up -d --build
+> ```
+
 ### 3.4.1 Optional: Persist ENV_FILE selection via `.env`
 
 If you want a simpler startup command (and to avoid forgetting `ENV_FILE=...`), you can create a small `.env` file **on the server only** that defines which env file Compose should use.
@@ -282,6 +304,34 @@ Notes:
 - `.env.server` still contains secrets and must not be committed.
 - Always run `docker compose` from the project root so Compose picks up the correct `.env` file.
 
+### 3.4.2 Optional: Persist ENV_FILE + COMPOSE_FILE selection via `.env`
+
+If your server setup uses multiple compose files (e.g. base + server tooling), you can also persist the compose file selection in the same **server-local** `.env` file.
+
+Example `./.env` (server only, do not commit):
+
+```env
+ENV_FILE=.env.server
+COMPOSE_FILE=docker-compose.yml:docker-compose.server-tools.yml
+```
+
+Notes:
+
+- `COMPOSE_FILE` supports multiple files separated by `:` (common on Linux servers).
+- Keep `.env` and `.env.server` server-local (do not commit).
+
+After that, you can start/update the stack with:
+
+```bash
+docker compose up -d --build
+```
+
+Optional: verify which configuration Compose is actually using:
+
+```bash
+docker compose config
+```
+
 ### 3.5 Verify
 
 On the server:
@@ -322,4 +372,4 @@ docker compose -f docker-compose.yml logs --tail=200 app
 
 For real users, the application should be served over HTTPS (reverse proxy / TLS termination).
 
-If HTTPS is enabled, keep the default secure-cookie behavior.
+If HTTPS is enabl