scripts/CLAUDE.md

scripts

Operational scripts for Luc's self-hosted environment. Each script collection is an independent, self-documenting folder at the repo root. There is no shared runtime, no build step, and no top-level package manifest — this is a repo of standalone tools, not an application.

---

The one hard rule: collections are self-contained

Every script collection lives in its own top-level folder and carries all of its own documentation, configuration, and dependencies. A collection must be understandable, runnable, and deletable on its own.

scripts/
├── CLAUDE.md              # this file — repo-wide context
├── README.md              # human-facing index of collections
├── _template/             # scaffold for a new collection (leading _ = not a collection)
└── <collection>/
    ├── README.md          # REQUIRED — what it does, prerequisites, usage
    ├── CLAUDE.md          # OPTIONAL — agent context, only if non-obvious
    ├── .env.example       # REQUIRED if the collection reads secrets
    ├── bin/               # executable entrypoints (chmod +x, shebang)
    ├── lib/               # sourced helpers, not directly executable
    └── docs/              # anything longer than the README warrants

Do not create shared/, common/, or utils/ at the repo root. If two collections need the same helper, copy it. Duplication across collections is explicitly preferred over coupling — a collection that depends on a sibling is no longer independently deletable, and these scripts get deployed to different places at different times.

Folders prefixed with _ are repo infrastructure, not collections.

Adding a collection

Copy _template/ to the new name, fill in its README, and add one line to the root README.md index. That is the whole process.

---

The environment

⚠ Confirm the gaps marked ? below, then delete this warning. The infrastructure facts are carried over from the FamilySync project, where they are documented and verified. Only the mapping of the name odin to that host is assumed — the name appears in no memory, transcript, or config on this box.

odin — the Unraid server; the single host everything self-hosted runs on. Verified characteristics:

Aspect	Detail
Host OS	Unraid
Container runtime	Docker + Docker Compose (stacks defined per-app)
Database	MariaDB 11.x — PostgreSQL is not available, treat as a hard constraint
Cache / queue	Redis (available, used optionally)
Auth	Authelia — OIDC/OAuth2 provider for internal apps
Ingress	Pangolin/Newt tunnel — no open inbound ports
DNS	Split-DNS on bergerhouse.net; private IPs resolve internally
Git forge	Self-hosted Gitea/Forgejo at git.bergerhouse.net (user luckberg)
CI	Gitea Actions with a self-hosted runner
Mail / calendar	Fastmail (paid) — JMAP/CalDAV, the source of truth for calendars

Known service hostnames: git.bergerhouse.net, familysync.bergerhouse.net, familysync-dev.bergerhouse.net.

Not on odin: GitHub (gh is not installed — use tea for the Gitea forge), PostgreSQL, any cloud provider.

This box vs. odin

The machine this repo is edited on is dev — a separate workstation, not the server. Scripts written here usually target odin (over SSH, or by being deployed into a container/user-script on it). Never assume a script runs on the same host it was authored on: take the target as a parameter or read it from config.

? — SSH access method to odin (no ~/.ssh/config entry exists on this box yet), and where deployed scripts are expected to live on the Unraid host.

---

Prior context: MemPalace

Much of what is known about this environment lives in MemPalace, a local semantic memory store — not in this repo. Query it before asking Luc to re-explain something, and before assuming an infrastructure detail is undocumented.

Aspect	Detail
Version	mempalace v3.4.1, installed as a uv tool
Palace path	/home/luc/.mempalace/palace
Backend	ChromaDB (vector search) + SQLite (metadata); fully local, no API key
Access	MCP server (mempalace-mcp) → 19 mempalace_* tools; plus the mempalace CLI
Size	~32k drawers

Read the docs, don't guess the CLI. MemPalace ships its own instructions:

mempalace instructions <help|init|mine|search|status>

Structure is Wings → Rooms → Closets → Drawers — wings are projects/people, rooms are topics, closets are summaries, drawers are verbatim memories. Halls connect rooms within a wing; tunnels connect rooms across wings.

Existing wings: familysync (~21.6k), sessions (~10.6k — mined agent transcripts), wing_familysync.

This repo's wing

Initialized with mempalace init . --yes and mined with mempalace mine ..

• Wing: odin-scripts — set explicitly in mempalace.yaml, not auto-detected. Auto-detection uses the directory basename, and a wing called scripts would collide with any other corpus in a folder of that name.
• Rooms: environment, documentation, collections, general.
• Room routing matches keywords against the file path, so never use scripts as a room keyword here — it matches this repo's own path and swallows every file. (Learned the hard way; the comment in mempalace.yaml says so too.)
• mempalace.yaml and entities.json are gitignored — that is MemPalace's own convention (issue #185), applied by init.

Re-mine after adding a collection: mempalace mine . --agent claude. Mining is idempotent — already-filed files are skipped.

Practical notes:

• mempalace_search is semantic — the query field takes keywords only, max 250 chars. Put background in context, not in the query, or the embedding gets diluted.
• Filter with wing/room when you know where the answer lives; the sessions wing is raw transcript chunks and is noisy for factual lookups.
• BM25 scores of 0 with mid-range similarity means no lexical match — a bare-keyword search for a proper noun that returns only semantic neighbours is a negative result, not a weak positive. This is how the odin gap above was established.
• mempalace_kg_query hits the temporal knowledge graph for point-in-time facts; prefer it over search for "what is X currently" questions, and use kg_supersede rather than invalidate-then-add when a single-valued fact changes.
• Auto-save hooks are active: a Stop hook saves every 15 human messages, and a PreCompact hook force-saves before context compaction.

Complementary and separate from MemPalace:

• Per-project agent memory — ~/.claude/projects/<slug>/memory/*.md, indexed by that directory's MEMORY.md. This repo's is currently empty; FamilySync's holds the CI-gate, dev-stack, and Gitea-CI notes that much of this file's environment section derives from.
• Project docs on disk — ~/projects/familysync/CLAUDE.md and docs/ARCHITECTURE.md are the authoritative written source for the odin stack.

---

Conventions

These apply to every collection unless its own README documents a deliberate exception.

Shell

• #!/usr/bin/env bash and set -euo pipefail at the top of every bash entrypoint.
• Quote every expansion. Prefer [[ ]] over [ ].
• Scripts must be idempotent — safe to re-run. Assume cron or a retry will do so.
• Accept --dry-run for anything that mutates state, deletes, or sends. Default to the safe path when a flag is ambiguous.
• Log to stdout, errors to stderr. No log files unless the collection documents rotation.

Secrets

• Never commit secrets. Read them from the environment or a file path passed in.
• Every collection that needs secrets ships a .env.example with dummy values and a README line naming where the real values live.
• Note the FamilySync-side precedent: gitleaks runs as a blocking CI gate on that repo. Assume any secret committed here is treated the same way — as a leak to be rotated, not a mistake to be amended away.

Portability

• Target the interpreters actually present: bash, Python 3, Node 22. Check before adding a dependency on anything else.
• Unraid's userland is BusyBox-leaning in places — prefer POSIX-portable invocations of sed/awk/date over GNU-only flags when the script runs on the server.

---

Working agreements for Claude

• Scope changes to one collection. A request about collection X should not touch collection Y. If it must, say so explicitly rather than doing it quietly.
• Update the collection's README in the same change as the code. Docs living beside the script is the point of this repo's layout; a code change that leaves its README stale defeats it.
• Don't invent infrastructure. If a script needs a host, path, port, or credential that isn't documented above, ask — do not guess a plausible value. Wrong infra assumptions in an ops script fail in production, not in review.
• Destructive operations need confirmation before they're run against odin, even when the script itself is finished and correct. Writing the script is not authorization to execute it.