homelabstack/.claude/skills/vault/SKILL.md

name, description

name	description
vault	Read and write notes in ginnoir's self-hosted Obsidian vault (CouchDB obsidian-livesync backend at obsidian.ginnoir.com). Use when loading persistent context for a session, saving new context, writing a note, or querying vault contents. The vault is the canonical persistent-context store across Claude sessions.

vault

Obsidian vault backed by CouchDB (obsidian-livesync) at obsidian.ginnoir.com.

Credentials

Endpoint : https://obsidian.ginnoir.com
DB       : obsidian
User     : admin
Password : couchdb_obs_p4ss_7x9k   (also in stacks/notes/stack.env)

Document format

Each note is a CouchDB document:

Field	Meaning
_id	Vault-relative path, e.g. claude/Context.md or Projects/homelab.md
data	Raw markdown content
type	"plain" for regular notes
ctime/mtime	Unix ms timestamps
size	Byte length of data

Slashes in _id must be URL-encoded as %2F in requests.

Read all notes

ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/_all_docs?include_docs=true"'

Returns JSON with rows[].doc.data = markdown for each note.

Read one note

# e.g. claude/Context.md
ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/claude%2FContext.md"'

Write / update a note

Shell escaping inside SSH is treacherous with JSON. The reliable pattern is:

1. Write JSON to /tmp/note.json on valhalla
2. docker cp it into the container
3. curl -d @/tmp/note.json from inside the container

# Step 1 — get current _rev
$rev = (ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/claude%2FContext.md"' | python -c "import sys,json; print(json.load(sys.stdin)['_rev'])")

# Step 2 — write JSON to valhalla /tmp
$json = @{_rev=$rev; data="# My Note`n`nContent"; type="plain"; ctime=0; mtime=0; size=10} | ConvertTo-Json
$json | ssh ginnoir@valhalla "cat > /tmp/note.json"

# Step 3 — copy to container and PUT
ssh -o BatchMode=yes ginnoir@valhalla '
  docker cp /tmp/note.json couchdb:/tmp/note.json
  docker exec couchdb curl -sf -X PUT \
    "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/claude%2FContext.md" \
    -H "Content-Type: application/json" -d @/tmp/note.json
'

Load context at session start

ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/claude%2FContext.md"' | python3 -c "import sys,json; print(json.load(sys.stdin)['data'])"

Key notes

Path	Purpose
claude/Context.md	Claude's persistent context: ongoing projects, preferences, session notes
Home.md	Vault index / root

Notes on valhalla Python

Running python3 on the valhalla host cannot resolve localhost (DNS issue in SSH env). Always use docker exec couchdb curl (CouchDB's own container) to hit the API — it resolves localhost fine internally.