Add CLAUDE.md, collection scaffold, and verified odin access docs #1

Merged
luckberg merged 2 commits from docs/repo-scaffold-and-claude-md into main 2026-08-15 20:34:25 -04:00
Owner

Bootstraps this repo as a collection of independent script folders for the self-hosted environment, and documents how to reach odin.

What's here

  • CLAUDE.md — repo conventions, the odin stack, MemPalace usage, and working agreements for agents.
  • docs/odin-access.md — the access reference: Tailscale path, WebGUI/API endpoint, TLS caveat, and the Unraid GraphQL API.
  • _template/ — scaffold making the "self-contained collection" rule concrete. The bash entrypoint has strict mode, --dry-run, and a required-env guard; all four paths were tested.
  • mempalace.yaml — wing odin-scripts, mined and search-verified.

The core rule

Each script collection is a self-contained top-level folder owning its own docs, config, and dependencies. No shared/ or utils/ at the root — duplication is preferred over coupling, so a collection stays independently deletable.

Verified, not assumed

Everything in docs/odin-access.md was checked from this box:

  • Tailscale is the only path from dev to odin. dev is a VPS with a public IP, not a LAN machine.
  • The myunraid.net host is the canonical nginx vhost, not a cloud relay — DNS resolves it to the private 192.168.90.103, so traffic stays on the tailnet.
  • The bare IP 404s on /graphql, and plain HTTP 302-redirects to the myunraid host while stripping the x-api-key header.
  • GraphQL is live: unauthenticated POSTs return HTTP 200 with an UNAUTHENTICATED error body, so 200 must never be read as success.

One correction

unraid-docker-manager states no SSL ignore is needed. TLS verification fails from devca-certificates 20250419 can't chain Let's Encrypt intermediate YR1. The cert is genuine and the claim likely holds on odin itself, but curl needs -k here. Supplying the missing intermediate is preferable to making -k a habit.

Container-polling field behaviours (UPPERCASE state, /-prefixed names, PrefixedID ids, no isUpdateAvailable in 7.2) come from unraid-docker-manager, credited as the authoritative source.

Still open

Two gaps are marked ? in CLAUDE.md and were not guessed: the SSH login to odin, and where deployed scripts should live on the Unraid host.

No secrets are included — no API key exists on this box.

🤖 Generated with Claude Code

Bootstraps this repo as a collection of independent script folders for the self-hosted environment, and documents how to reach **odin**. ## What's here - **`CLAUDE.md`** — repo conventions, the odin stack, MemPalace usage, and working agreements for agents. - **`docs/odin-access.md`** — the access reference: Tailscale path, WebGUI/API endpoint, TLS caveat, and the Unraid GraphQL API. - **`_template/`** — scaffold making the "self-contained collection" rule concrete. The bash entrypoint has strict mode, `--dry-run`, and a required-env guard; all four paths were tested. - **`mempalace.yaml`** — wing `odin-scripts`, mined and search-verified. ## The core rule Each script collection is a self-contained top-level folder owning its own docs, config, and dependencies. No `shared/` or `utils/` at the root — duplication is preferred over coupling, so a collection stays independently deletable. ## Verified, not assumed Everything in `docs/odin-access.md` was checked from this box: - Tailscale is the **only** path from `dev` to odin. `dev` is a VPS with a public IP, not a LAN machine. - The `myunraid.net` host is the canonical nginx vhost, **not** a cloud relay — DNS resolves it to the private `192.168.90.103`, so traffic stays on the tailnet. - The bare IP 404s on `/graphql`, and plain HTTP 302-redirects to the myunraid host **while stripping the `x-api-key` header**. - GraphQL is live: unauthenticated POSTs return **HTTP 200** with an `UNAUTHENTICATED` error body, so 200 must never be read as success. ## One correction `unraid-docker-manager` states no SSL ignore is needed. TLS verification **fails from `dev`** — `ca-certificates 20250419` can't chain Let's Encrypt intermediate `YR1`. The cert is genuine and the claim likely holds on odin itself, but `curl` needs `-k` here. Supplying the missing intermediate is preferable to making `-k` a habit. Container-polling field behaviours (UPPERCASE `state`, `/`-prefixed `names`, `PrefixedID` ids, no `isUpdateAvailable` in 7.2) come from `unraid-docker-manager`, credited as the authoritative source. ## Still open Two gaps are marked `?` in `CLAUDE.md` and were **not** guessed: the SSH login to odin, and where deployed scripts should live on the Unraid host. No secrets are included — no API key exists on this box. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
luckberg added 2 commits 2026-08-15 20:33:56 -04:00
Establish this repo as a collection of independent script folders for the
self-hosted environment (odin, an Unraid host).

- CLAUDE.md: repo conventions, the odin stack, and MemPalace usage. The
  infrastructure facts are carried over from the FamilySync project, where
  they are documented and verified; the mapping of the name "odin" to that
  host is assumed and flagged for confirmation, along with the SSH/deploy
  gaps marked "?".
- Core rule: each collection is a self-contained top-level folder owning its
  own docs, config, and dependencies. No shared/ or utils/ at the root —
  duplication is preferred over coupling so a collection stays independently
  deletable.
- _template/: scaffold making that rule concrete. The bash entrypoint ships
  strict mode, --dry-run, and a required-env guard (all four paths tested).
- mempalace.yaml: wing "odin-scripts", set explicitly because basename
  auto-detection would produce the colliding wing "scripts". Tracked rather
  than gitignored so a fresh clone keeps the config; entities.json stays
  ignored.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Replace the assumed/unconfirmed environment notes with facts verified from
this box, and add docs/odin-access.md as the access reference.

Verified:
- Tailscale is the only path from dev to odin. dev (100.94.16.46) is a VPS
  with a public IP, not a LAN machine; odin is 100.101.253.105, and a subnet
  route puts 192.168.90.0/24 over tailscale0 at the same ~34ms RTT.
- The myunraid.net host is the canonical nginx vhost, not a cloud relay --
  DNS resolves it to the private 192.168.90.103, so traffic stays on the
  tailnet. The bare IP 404s on /graphql, and plain HTTP 302-redirects to the
  myunraid host while stripping the x-api-key header.
- GraphQL is live: unauthenticated POSTs return HTTP 200 with an
  UNAUTHENTICATED error body, so 200 must never be read as success.

Corrects unraid-docker-manager's claim that no SSL ignore is needed: TLS
verification fails from dev because ca-certificates 20250419 cannot chain
Let's Encrypt intermediate YR1. The cert is genuine and the claim likely
holds on odin itself, but curl needs -k here.

Container-polling field behaviours (UPPERCASE state, /-prefixed names,
PrefixedID ids, no isUpdateAvailable in 7.2) are carried over from
unraid-docker-manager, which is credited as the authoritative source.

No API key is present on this box; .env.unraid-api is gitignored there and
absent from the clone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
luckberg merged commit 4260951546 into main 2026-08-15 20:34:25 -04:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: luckberg/scripts#1