docs: correct migration records that outlived their migrations

Both documents described work as outstanding that the cluster shows finished.
A record that says "REMAINING" long after the fact is worse than no record:
it is read as current state, and the next person plans around it.

## Home Assistant recorder

Phase 2c is done, and done correctly. Against the live database:

  statistics             11,092,586   2024-03-13 20:00 -> current
  statistics_short_term   1,883,709   rolling ~7 days
  statistics_meta             1,480

The 2024-03-13 origin is the part that matters. It is unchanged from the
10,793,712-row count recorded on 2026-08-19, so the history was copied across
engines rather than started from zero — the exact failure the document was
written to prevent. `states` carries current rows, so db_url points at
Postgres.

The three "INERT"/"PHASE 1" comments went with it. All three described a
cluster that nothing consumed; it is now the recorder's live database, and the
render-db-url init container is load-bearing rather than inert — HA will not
start without the secret it renders.

## Bare-metal conversion

`talosctl get systeminformation` reports Minisforum MS-01 hardware with
distinct chassis serials for all three nodes and no hypervisor, so saturn and
neptune are not outstanding. Node creationTimestamp is not evidence either way:
k8s-3 still carries its 2026-05-09 object and is on metal regardless.

The runbook stays as the procedure for a rebuild.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

kubernetes/RUNBOOK-baremetal-conversion.md

@@ -2,7 +2,12 @@
 
 Converts one MS-01 from "Proxmox host running a Talos VM" to "Talos on bare
 metal", and swaps its Ceph OSD onto a Samsung PM983 at the same time. Written
-after doing jupiter on 2026-08-25; saturn and neptune remain.
+after doing jupiter on 2026-08-25.
+
+All three nodes are now on bare metal — `talosctl get systeminformation`
+reports Minisforum MS-01 hardware with distinct chassis serials for k8s-1,
+k8s-2 and k8s-3, with no hypervisor in between. Kept as the procedure for a
+rebuild, not as outstanding work.
 
 Everything here that reads like an over-specific warning is something that
 actually happened. The conversion itself is straightforward — the failures were

kubernetes/apps/home-assistant/MIGRATION-recorder-postgres.md

@@ -111,9 +111,23 @@ statistics             max_id=13323904    max_start_ts=1787162400.0
 statistics_short_term  max_id=159205762   max_start_ts=1787166000.0
 ```
 
-## Phase 2c — cutover (REMAINING)
+## Phase 2c — cutover: DONE
 
-Do not start until phase 1 is verified.
+Verified 2026-09-02 against the live database:
+
+| table | rows | span |
+|---|---|---|
+| `statistics` | 11,092,586 | 2024-03-13 20:00 → current |
+| `statistics_short_term` | 1,883,709 | rolling ~7 days |
+| `statistics_meta` | 1,480 | |
+
+The 2024-03-13 origin is the proof that matters. It is unchanged from the
+pre-migration count in "What is at risk" above, so the history was copied
+across engines rather than started from zero — which is the failure this
+document exists to prevent. `states` carries current rows, so `db_url` points
+at Postgres.
+
+The procedure below is kept as the record of what was done.
 
 **Migrate statistics only.** Copying all 18M `states` rows is slow, needs a long
 HA outage, and buys a table that is discarded within 7 days anyway.

kubernetes/apps/home-assistant/deployment.yaml

@@ -56,10 +56,9 @@ spec:
         # Re-rendered on every pod start, so a CNPG password rotation takes
         # effect rather than silently leaving a stale URI behind.
         #
-        # INERT until the recorder is repointed: nothing reads this key until
-        # `db_url: !secret recorder_db_url` lands in configuration.yaml in the
-        # homeassistant repo. That ordering is required — HA refuses to start
-        # when a referenced secret is missing.
+        # Load-bearing: `db_url: !secret recorder_db_url` in the homeassistant
+        # repo's configuration.yaml reads this key, so HA does not start
+        # without it. Removing this init container takes the recorder down.
         - name: render-db-url
           image: busybox:1.36
           command:

kubernetes/apps/home-assistant/ha-pg-cluster.yaml

@@ -18,12 +18,12 @@
 # That is the point of the move — it attacks the multiplier rather than trimming
 # what gets recorded, which would only hide the problem.
 #
-# STAGING
-# Phase 1 (this manifest): the cluster comes up EMPTY and HA keeps using SQLite.
-# Nothing depends on it, so a failure here is inert. Verify Ready, WAL archiving
-# to Hetzner, and a successful base backup before going further.
-# Phase 2: migrate the statistics tables and repoint recorder.db_url.
-# See MIGRATION-recorder-postgres.md for the sequence and the rollback.
+# This is the live recorder database. HA writes here; the SQLite file is no
+# longer the system of record. The 2.4 years of long-term statistics were
+# copied across engines rather than regenerated — HA does not migrate data
+# between database engines, so an empty Postgres would have silently started
+# from zero and taken the energy dashboard's history with it.
+# MIGRATION-recorder-postgres.md holds the sequence that was followed.
 apiVersion: postgresql.cnpg.io/v1
 kind: Cluster
 metadata:

kubernetes/apps/home-assistant/kustomization.yaml

@@ -60,9 +60,8 @@ resources:
   - zigbee2mqtt-gate-service.yaml
   - zigbee2mqtt-ingress.yaml
   # Postgres backend for the recorder (MIGRATION-recorder-postgres.md).
-  # PHASE 1: this cluster comes up EMPTY and nothing consumes it — HA is still
-  # on SQLite. Deploying it is therefore inert; phase 2 migrates the statistics
-  # tables and repoints recorder.db_url in the homeassistant repo.
+  # Live: recorder.db_url in the homeassistant repo points here, and the
+  # long-term statistics carry their full history from 2024.
   - ha-pg-hetzner-creds-externalsecret.yaml
   - ha-pg-objectstore.yaml
   - ha-pg-cluster.yaml

kubernetes/apps/llama-server/embed.yaml

@@ -44,12 +44,37 @@ spec:
             - Qwen/Qwen3-Embedding-0.6B-GGUF:Q8_0
             # Serves POST /v1/embeddings.
             - --embeddings
+            # A short, stable id for consumers. Without it the model is
+            # advertised as the whole --hf-repo string, which would end up
+            # verbatim in Paperless's config and break on the next model swap.
+            # One name only: llama-server keeps aliases in a sorted set and
+            # reports the first as the id, so a second name can steal it.
+            - --alias
+            - qwen3-embedding-0.6b
+            # Qwen3-Embedding is trained for last-token pooling. Left
+            # unspecified llama-server takes the GGUF's default, which is not
+            # visible from outside and would silently produce vectors the model
+            # was not trained to emit. Set before anything is indexed: changing
+            # pooling later invalidates every stored embedding.
+            - --pooling
+            - last
             - --n-gpu-layers
             - "99"
             - --threads
             - "2"
+            # Paperless chunks documents at 1024 tokens. The defaults are
+            # batch 2048 / ubatch 512, and with --embeddings llama-server
+            # clamps both down to 512 rather than run them mismatched — below
+            # the chunk size. Matching both to 1024 fits a whole chunk in one
+            # pass; 2048 is deliberately avoided, since that is where this
+            # Vulkan stack fails with ErrorDeviceLost.
+            - --batch-size
+            - "1024"
+            - --ubatch-size
+            - "1024"
+            # Room for a full chunk plus overhead rather than exactly one.
             - --ctx-size
-            - "2048"
+            - "4096"
             # No browser ever talks to this Service, so the WebUI is dead weight
             # and one more unauthenticated surface.
             - --no-webui

kubernetes/apps/paperless/network-policy.yaml

@@ -57,6 +57,20 @@ spec:
               protocol: UDP
             - port: "53"
               protocol: TCP
+    # The cluster's own LLM, for AI suggestions and RAG embeddings. Scoped to
+    # the two pods and the one port rather than the ai namespace as a whole, so
+    # this grant cannot widen if something else is ever placed there.
+    - toEndpoints:
+        - matchLabels:
+            "k8s:io.kubernetes.pod.namespace": ai
+            app.kubernetes.io/name: llama-server
+        - matchLabels:
+            "k8s:io.kubernetes.pod.namespace": ai
+            app.kubernetes.io/name: llama-embed
+      toPorts:
+        - ports:
+            - port: "8080"
+              protocol: TCP
     # External HTTPS only — Tika model downloads, runtime image
     # fetches, etc. RFC1918 + ULA are excluded from `world` via the
     # CIDR-deny pattern. `world` covers public IPs / DNS-resolvable

kubernetes/apps/paperless/paperless.yaml

@@ -46,6 +46,44 @@ data:
   PAPERLESS_TIKA_ENABLED: "1"
   PAPERLESS_TIKA_ENDPOINT: "http://tika:9998"
   PAPERLESS_TIKA_GOTENBERG_ENDPOINT: "http://gotenberg:3000"
+  # AI suggestions against the cluster's own LLM (kubernetes/apps/llama-server).
+  # Nothing leaves the cluster: both endpoints are ClusterIP Services, so
+  # document text is never sent to a third party and there is no API key to
+  # rotate — llama-server has no authentication, and the ai namespace's network
+  # policy is what restricts who may reach it.
+  #
+  # CAVEAT, and it is a real one: paperless reads these from an
+  # ApplicationConfiguration row in the database and falls back to the
+  # environment only when that row is empty. A value set in the admin UI
+  # therefore overrides this ConfigMap silently. Configure AI in ONE place —
+  # here — and leave those fields untouched in the UI.
+  PAPERLESS_AI_ENABLED: "true"
+  PAPERLESS_AI_LLM_BACKEND: "openai-like"
+  PAPERLESS_AI_LLM_ENDPOINT: "http://llama-server.ai.svc.cluster.local:8080/v1"
+  # Must match --alias in kubernetes/apps/llama-server/deployment.yaml. The
+  # server ignores the field on the wire, but paperless sends it and the value
+  # is what appears in its logs.
+  PAPERLESS_AI_LLM_MODEL: "qwen3.6-35b-a3b"
+  # ClusterIP addresses are private, and paperless blocks non-public endpoints
+  # unless this is set. Default is already true; explicit because the whole
+  # integration silently stops working if it ever flips.
+  PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS: "true"
+  # Under llama-server's own 16384, leaving room for the response.
+  PAPERLESS_AI_LLM_CONTEXT_SIZE: "12288"
+  # The 120s default is too tight at ~11 tok/s: a classification is roughly
+  # 2-4k prompt tokens plus a second round trip for localisation.
+  PAPERLESS_AI_LLM_REQUEST_TIMEOUT: "300"
+  # Matched against Django's settings.LANGUAGES, so the region is required —
+  # "de" alone does not resolve. Without it the model returns German tags but
+  # English document types, which was reproducible against this endpoint.
+  PAPERLESS_AI_LLM_OUTPUT_LANGUAGE: "de-de"
+  # RAG embeddings from llama-embed. Its Qwen3-Embedding covers 100+ languages,
+  # where paperless's default all-MiniLM-L6-v2 is documented as suited to
+  # primarily English archives — the better fit for a German corpus.
+  PAPERLESS_AI_LLM_EMBEDDING_BACKEND: "openai-like"
+  PAPERLESS_AI_LLM_EMBEDDING_ENDPOINT: "http://llama-embed.ai.svc.cluster.local:8080/v1"
+  PAPERLESS_AI_LLM_EMBEDDING_MODEL: "qwen3-embedding-0.6b"
+  PAPERLESS_AI_LLM_EMBEDDING_CHUNK_SIZE: "1024"
 ---
 apiVersion: apps/v1
 kind: Deployment
@@ -58,6 +96,13 @@ metadata:
     # Reloader restarts paperless when paperless-secrets changes (e.g. after a
     # secret-key rotation). See kubernetes/infrastructure/openbao/rotation/paperless.yaml.
     secret.reloader.stakater.com/reload: paperless-secrets
+    # And when paperless-config changes. The ConfigMap is consumed with
+    # envFrom, and Kubernetes does not restart a pod when a ConfigMap it reads
+    # that way is updated — the running container keeps the environment it
+    # started with. Without this, a settings change applies cleanly in git and
+    # in the cluster while the application never sees it, which is how the AI
+    # settings landed with no effect at all.
+    configmap.reloader.stakater.com/reload: paperless-config
 spec:
   replicas: 1
   strategy:

kubernetes/infrastructure/network-policies/ai-ns.yaml

@@ -24,6 +24,16 @@ spec:
         - ports:
             - port: "8080"
               protocol: TCP
+    # Paperless calls both models for AI suggestions and RAG embeddings. The
+    # matching egress grant on its side is scoped to these two pods on :8080.
+    - fromEndpoints:
+        - matchLabels:
+            "k8s:io.kubernetes.pod.namespace": paperless
+            app.kubernetes.io/name: paperless
+      toPorts:
+        - ports:
+            - port: "8080"
+              protocol: TCP
     - fromEndpoints:
         - matchLabels:
             "k8s:io.kubernetes.pod.namespace": monitoring