docs(vault): document Pokémon ROM Hacks vault section in skill
Adds the ROM Hacks folder tree to the vault structure reference so future sessions know where _Claude.md, Index.md, Play Queue, Bases/, and Platforms/ live without re-deriving it.
This commit is contained in:
ginnoir
@@ -1,112 +1,98 @@
|
|||||||
---
|
---
|
||||||
name: vault
|
name: vault
|
||||||
description: 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.
|
description: Read and write notes in ginnoir's self-hosted Obsidian vault via the Obsidian MCP server. 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
|
# vault
|
||||||
|
|
||||||
Obsidian vault backed by CouchDB (obsidian-livesync) at `obsidian.ginnoir.com`.
|
Obsidian vault accessed via the **`mcp__obsidian__*` MCP tools**. Do not attempt to connect to CouchDB directly — use MCP only.
|
||||||
|
|
||||||
## Credentials
|
The MCP server is configured in `~/.mcp.json` and is available in every Claude Code session. If the tools are listed as deferred, load them with `ToolSearch` before calling.
|
||||||
|
|
||||||
```
|
## Core tools
|
||||||
Endpoint : http://admin:couchdb_obs_p4ss_7x9k@localhost:5984 (via docker exec couchdb)
|
|
||||||
DB : obsidian
|
|
||||||
External : https://obsidian.ginnoir.com (also in stacks/notes/stack.env)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Document format (confirmed from live vault)
|
| Tool | Use |
|
||||||
|
|---|---|
|
||||||
obsidian-livesync uses a **two-level structure**:
|
| `mcp__obsidian__vault_list` | List files/dirs in a directory (omit path for vault root) |
|
||||||
|
| `mcp__obsidian__vault_read` | Read a file's full content + metadata (tags, frontmatter, links, backlinks) |
|
||||||
**File doc** — `_id` is the vault-relative path (e.g. `testing.md`, `claude/Context.md`):
|
| `mcp__obsidian__vault_write` | Create or overwrite a file |
|
||||||
```json
|
| `mcp__obsidian__vault_patch` | Append or patch a section without a full rewrite |
|
||||||
{
|
| `mcp__obsidian__vault_delete` | Delete a file |
|
||||||
"_id": "testing.md",
|
| `mcp__obsidian__vault_move` | Move or rename a file |
|
||||||
"path": "testing.md",
|
| `mcp__obsidian__search_simple` | Full-text search across the vault |
|
||||||
"type": "plain",
|
| `mcp__obsidian__search_query` | Advanced query search |
|
||||||
"children": ["h:1w5waerza6mc9"],
|
| `mcp__obsidian__tag_list` | List all tags |
|
||||||
"ctime": 1780735543814,
|
|
||||||
"mtime": 1780735679684,
|
|
||||||
"size": 14,
|
|
||||||
"eden": {}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Leaf/chunk doc** — `_id` is `h:<short-hash>`, holds the actual content:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"_id": "h:1w5waerza6mc9",
|
|
||||||
"data": "this is a test",
|
|
||||||
"type": "leaf"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Content lives in leaf docs. `children[]` lists chunk IDs in order (concatenate for large notes).
|
|
||||||
Slashes in paths must be URL-encoded as `%2F` in requests.
|
|
||||||
|
|
||||||
## Read all notes (list)
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
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"'
|
|
||||||
```
|
|
||||||
|
|
||||||
File docs: `type == "plain"`, `_id` does not start with `h:` or `obsydian_`.
|
|
||||||
|
|
||||||
## Read one note's content
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
# 1. Get file doc — find chunk IDs in children[]
|
|
||||||
ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/testing.md"'
|
|
||||||
|
|
||||||
# 2. Fetch chunk — content is in .data
|
|
||||||
ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/h%3A1w5waerza6mc9"'
|
|
||||||
```
|
|
||||||
|
|
||||||
## Write a new note
|
|
||||||
|
|
||||||
Write the leaf first, then the file doc. Use a fixed chunk ID so you can update it later.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ssh -o BatchMode=yes ginnoir@valhalla '
|
|
||||||
B="http://admin:couchdb_obs_p4ss_7x9k@localhost:5984"
|
|
||||||
NOW=$(date +%s%3N)
|
|
||||||
CHUNK="h:claude_ctx_1"
|
|
||||||
CONTENT="# My Note\n\nContent here."
|
|
||||||
|
|
||||||
docker exec couchdb curl -sf -X PUT "$B/obsidian/$CHUNK" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d "{\"data\":\"$CONTENT\",\"type\":\"leaf\"}"
|
|
||||||
|
|
||||||
docker exec couchdb curl -sf -X PUT "$B/obsidian/claude%2FContext.md" \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d "{\"path\":\"claude/Context.md\",\"type\":\"plain\",\"children\":[\"$CHUNK\"],\"ctime\":$NOW,\"mtime\":$NOW,\"size\":${#CONTENT},\"eden\":{}}"
|
|
||||||
'
|
|
||||||
```
|
|
||||||
|
|
||||||
## Update an existing note
|
|
||||||
|
|
||||||
Fetch `_rev` for both the file doc and chunk doc, then re-PUT both with `_rev` included.
|
|
||||||
|
|
||||||
For complex content (markdown with quotes/newlines), write JSON to `/tmp/` on valhalla, `docker cp` into container, and `curl -d @/tmp/file.json` — avoids shell escaping.
|
|
||||||
|
|
||||||
## Load context at session start
|
## Load context at session start
|
||||||
|
|
||||||
```powershell
|
```
|
||||||
# Get all file docs and their chunk content
|
1. mcp__obsidian__vault_read path="claude/Context.md"
|
||||||
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"' | python -c "
|
2. Follow [[wikilinks]] to read specific notes as needed
|
||||||
import sys, json
|
|
||||||
d = json.load(sys.stdin)
|
|
||||||
chunks = {r['id']: r['doc']['data'] for r in d['rows'] if r['id'].startswith('h:')}
|
|
||||||
for r in d['rows']:
|
|
||||||
doc = r['doc']
|
|
||||||
if doc.get('type') == 'plain' and not doc.get('deleted'):
|
|
||||||
content = ''.join(chunks.get(c, '') for c in doc.get('children', []))
|
|
||||||
print(f'=== {doc[\"_id\"]} ===')
|
|
||||||
print(content)
|
|
||||||
"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Notes on valhalla Python
|
`claude/Context.md` is the master index. It links to all other context notes under `claude/`.
|
||||||
|
|
||||||
`python3` on the valhalla *host* cannot resolve `localhost` (DNS issue in SSH env). Always use `docker exec couchdb curl` — the container resolves localhost fine. On the Windows Claude Code host, use `python` (not `python3`).
|
## Read a note
|
||||||
|
|
||||||
|
```
|
||||||
|
mcp__obsidian__vault_read path="claude/Homelab.md"
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns: `content` (full markdown), `tags`, `frontmatter`, `links`, `backlinks`, `stat`.
|
||||||
|
|
||||||
|
To read only a section:
|
||||||
|
```
|
||||||
|
mcp__obsidian__vault_read path="claude/Services.md" targetType="heading" target="BookStack"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Write a note
|
||||||
|
|
||||||
|
```
|
||||||
|
mcp__obsidian__vault_write path="claude/MyNote.md" content="# Title\n\nContent here."
|
||||||
|
```
|
||||||
|
|
||||||
|
Creates parent directories automatically. Overwrites without warning.
|
||||||
|
|
||||||
|
## Append to a note
|
||||||
|
|
||||||
|
```
|
||||||
|
mcp__obsidian__vault_patch path="claude/Context.md" ...
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `vault_patch` when adding a section to an existing note to avoid rewriting the whole file.
|
||||||
|
|
||||||
|
## Search the vault
|
||||||
|
|
||||||
|
```
|
||||||
|
mcp__obsidian__search_simple query="portainer env vars"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Vault structure
|
||||||
|
|
||||||
|
```
|
||||||
|
claude/
|
||||||
|
Context.md — master index, session start guide, quick nav
|
||||||
|
Homelab.md — topology, stacks, networks, paths
|
||||||
|
Deploy.md — deployment channels
|
||||||
|
SSH.md — SSH ops, container management
|
||||||
|
Portainer.md — env interpolation gotcha, new stack registration
|
||||||
|
Services.md — per-service quirks (BookStack, Caddy, secrets policy)
|
||||||
|
ROM Library.md — RomM, igir, Pokémon romhacks, EmuDeck tree
|
||||||
|
Monitoring.md — Uptime Kuma v2 socket technique
|
||||||
|
Vault.md — this stack's infrastructure, MCP access
|
||||||
|
testing.md — original connectivity test note
|
||||||
|
Pokémon ROM Hacks/
|
||||||
|
_Claude.md — ROM hack vault ops: schema, update patterns, new-hack checklist
|
||||||
|
Index.md — all 75 hacks directory (Dataview + static)
|
||||||
|
Play Queue.md — play tracking dashboard
|
||||||
|
Hacks/ — 75 notes, one per hack
|
||||||
|
Bases/ — per-base MOCs (FireRed / Emerald / Crystal / Ruby / NDS)
|
||||||
|
Platforms/ — per-system MOCs (GBA / GBC / GB / NDS)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Load tool schemas (if deferred)
|
||||||
|
|
||||||
|
If `mcp__obsidian__vault_read` is not yet callable, run:
|
||||||
|
```
|
||||||
|
ToolSearch query="select:mcp__obsidian__vault_list,mcp__obsidian__vault_read,mcp__obsidian__vault_write"
|
||||||
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user