docs: separate per-machine setup from project guidance

CLAUDE.md and AGENTS.md are checked in, so they read identically on every machine —
but they asserted which machine you were on, where the deployment lived, and what was
running locally. All 38 lines of CLAUDE.md except the AGENTS.md import were one
person's fleet: hostnames, a Tailnet name, a LAN IP, a WSL2 quirk.

Three tiers now:

  - AGENTS.md keeps the generic principle — a stopped local stack does not mean
    Chronicle is unavailable, check before claiming unverified, do not start a
    duplicate deployment, mutations need the user's say-so — and names no host.
  - CLAUDE.md says where per-machine detail belongs and nothing else.
  - CLAUDE.local.md (new .gitignore entry) holds the fleet specifics.

It also stated the deployment host "will not have uncommitted local changes", which
is false — that checkout carries 22 modified files, and planning a pull around the
claim would have been wrong.

Three hardcoded personal LAN addresses went with it. The worst was a CLI default in
shipped code: extras/asr-services/client.py dialled 192.168.0.110 for anyone who ran
it without --asr-url; it now defaults to localhost and reads $ASR_URL. The screenshots
skill and a vault-sync comment used the same address as illustration and now use
placeholders.

Author: AnkushMalaker

.gitignore

@@ -103,6 +103,10 @@ certs/*.pem
 docs/plans/
 docs/research/
 
+# Per-user, per-machine agent guidance (fleet hostnames, LAN addresses).
+# Project-wide guidance belongs in AGENTS.md / CLAUDE.md, which are checked in.
+CLAUDE.local.md
+
 # Legacy per-service SSL (kept for cleanup)
 extras/speaker-recognition/ssl/*
 backends/advanced/ssl/*

AGENTS.md

@@ -15,29 +15,34 @@ This supports a comprehensive web dashboard for management.
 
 ## Live Deployment Location
 
-The normal live Chronicle deployment is hosted on the Tailnet machine **`kraken`**. Run
-`hostname` before acting on this section — this file is checked in and reads the same on
-every machine, including Kraken itself, where the deployment is *local* and there is no
-remote host to reach. On any other machine a stopped or unconfigured local stack does
-not mean Chronicle is unavailable.
+A Chronicle deployment often runs on a **different machine** from the checkout you are
+working in — commonly a home server reached over a Tailnet. A stopped or unconfigured
+local stack therefore does not mean Chronicle is unavailable.
+
+This file is checked in and reads the same everywhere, so it deliberately names no
+host. Run `hostname` first, then read `CLAUDE.local.md` (gitignored, per-user) for the
+addresses that apply to the machine you are on — including the case where the checkout
+you are in *is* the deployment, and everything is local.
 
 For read-only checks of the running application (health checks, API inspection, or
 browser/screenshot verification):
 
-1. Try `https://kraken.parrot-census.ts.net` first. Use HTTPS; plain HTTP redirects.
-2. If that name is unavailable, inspect the current Tailscale mesh with
-   `tailscale status --json` and resolve the online peer whose `HostName` is `Kraken`
-   **and whose `OS` is `linux`** — Kraken runs under WSL2, so the Windows host
-   advertises the same hostname and answers pings while serving no Chronicle.
-   Prefer its returned `DNSName`; use its current Tailscale IP only as a temporary
-   fallback. Do not persist a `100.x` address because it may change.
+1. Use the deployment address from `CLAUDE.local.md`, if there is one. Prefer HTTPS;
+   plain HTTP usually redirects. A self-signed or internal-CA cert needs `curl -k`.
+2. Otherwise inspect the current Tailscale mesh with `tailscale status --json` and
+   resolve the online peer serving Chronicle. Match on `OS` as well as `HostName` — a
+   host running under WSL2 advertises the same hostname from both the Windows host and
+   the Linux guest, and only the guest serves anything. Prefer the returned `DNSName`;
+   use a Tailscale IP only as a temporary fallback, and never persist a `100.x` address
+   because it may change.
 3. If the host is reachable but the Chronicle endpoint is unclear, use the repository's
    `discovery.py`/minidisc support to discover the `chronicle-backend` service on the
    Tailnet.
 
-Do not start a duplicate local deployment merely to inspect the live application.
-Remote deployment, restarts, or other mutations on Kraken still require the user's
-request to change or deploy the running system.
+Do not assume a remote deployment's checkout is clean or matches `origin` — check
+`git status` there before pulling. Do not start a duplicate local deployment merely to
+inspect the live application. Remote deployment, restarts, or other mutations still
+require the user's request to change or deploy the running system.
 
 ## Initial Setup & Configuration
 

CLAUDE.md

@@ -2,37 +2,13 @@
 
 @AGENTS.md
 
-## Verifying against a running backend
+## Machine- and deployment-specific guidance
 
-**First work out which machine you are on — this file is checked in, so it reads the
-same on every one of them.** Run `hostname`:
+This file is checked in, so it reads the same on every machine and must not assert
+which one you are on, where the live deployment is, or what is running locally.
 
-| hostname | what it is | how to verify |
-|---|---|---|
-| `rainbow` | Ankush's dev workstation (CachyOS). Usually **no** Chronicle stack running. | Reach Kraken over the network, as below. |
-| `Kraken` | The live deployment (Ubuntu 24.04 under WSL2). The stack is running **locally**. | Check it locally — `podman ps`, `curl localhost:8000/health`. Do **not** go looking for a remote Kraken; you are it. |
-
-Anything below about reaching Kraken applies when you are *not* on Kraken. Do not
-describe a machine as macOS unless `uname -s` actually says `Darwin`.
-
-If there is no Chronicle stack on the machine you are on, that does not mean you
-cannot verify your work. The live deployment runs on **`kraken`** and is reachable
-from `rainbow` without any tunnel:
-
-- `https://kraken.parrot-census.ts.net` (Tailnet, preferred)
-- `https://192.168.0.110/` over LAN — self-signed cert, so use `curl -k`. Caddy on
-  `:443` fronts the **vite dev server**, and the backend is on `:8000`.
-
-Before reporting something as "not verified because nothing is running locally",
-check Kraken first. See AGENTS.md → "Live Deployment Location" for the full
-resolution order.
-
-Note that Kraken runs in WSL2, so **two** Tailscale peers answer to the hostname
-`Kraken` — the Linux guest (which runs Chronicle) and the Windows host. When
-resolving it from `tailscale status --json`, take the one whose `OS` is `linux`.
-
-Kraken runs *deployed* code from `~/workspaces/friend-lite` on that host, so it will
-not have uncommitted local changes. To exercise new backend code end-to-end, stand up
-the pieces you need locally (a `podman run` Mongo plus the FastAPI app is usually
-enough) rather than deploying to Kraken — deploying touches a live system and needs
-Ankush's say-so first.
+Those belong in `CLAUDE.local.md` (gitignored, per-user, loaded automatically when
+present). If you need the deployment address, hostnames, or credentials for the
+environment you are in, read that file — and if it is absent, ask rather than
+assuming a stopped local stack means Chronicle is unavailable. See AGENTS.md →
+"Live Deployment Location".

backends/advanced/src/advanced_omi_backend/routers/modules/vault_sync_routes.py

@@ -32,7 +32,7 @@
 SYNCTHING_URL = os.getenv("VAULT_SYNC_SYNCTHING_URL", "http://vault-syncthing:8384")
 SYNCTHING_API_KEY = os.getenv("VAULT_SYNC_API_KEY", "")
 # Externally reachable sync address(es) handed to the Mac — comma-separated, e.g.
-# "tcp://my-host.ts.net:22000,tcp://192.168.0.110:22000"; the client dials each
+# "tcp://my-host.ts.net:22000,tcp://10.0.0.5:22000"; the client dials each
 # until one connects (Tailnet when remote, LAN IP when a device has no Tailscale).
 # Empty -> the Mac relies on Syncthing's own discovery/relays to find the server.
 SYNCTHING_ADDRESS = os.getenv("VAULT_SYNC_ADDRESS", "")

extras/asr-services/client.py

@@ -7,6 +7,7 @@
 import argparse
 import asyncio
 import logging
+import os
 from pathlib import Path
 
 from easy_audio_interfaces.audio_interfaces import ResamplingBlock
@@ -319,8 +320,8 @@ async def main():
     parser.add_argument(
         "--asr-url",
         type=str,
-        default="tcp://192.168.0.110:8765",
-        help="ASR service URL (default: %(default)s)",
+        default=os.getenv("ASR_URL") or "tcp://127.0.0.1:8765",
+        help="ASR service URL, or set ASR_URL (default: %(default)s)",
     )
     parser.add_argument(
         "-v",

skills/screenshots/SKILL.md

@@ -52,12 +52,12 @@ uv run --with playwright python skills/screenshots/scripts/capture_dashboard.py
 
 For public pages, omit `--authenticate`. Use `--backend-url`, `--env-file`, and `--output-dir` when the deployment differs. It rejects login redirects and blank pages rather than saving misleading screenshots.
 
-For a same-origin HTTPS proxy such as Chronicle's LAN deployment, point both URLs at the proxy and allow its development certificate:
+For a same-origin HTTPS proxy such as a LAN deployment behind Caddy, point both URLs at the proxy and allow its development certificate (substitute your own host — see your local agent config for the deployment address):
 
 ```bash
 uv run --with playwright python skills/screenshots/scripts/capture_dashboard.py \
-  --base-url https://192.168.0.110 \
-  --backend-url https://192.168.0.110 \
+  --base-url https://<deployment-host> \
+  --backend-url https://<deployment-host> \
   --ignore-https-errors \
   --authenticate \
   --route conversation=/conversations/<conversation-id>