Added git-manager, updated READMEs

2026-08-04 10:45:25 +02:00
parent c774df7ad7
commit e485d33f00
13 changed files with 830 additions and 72 deletions
@@ -0,0 +1,103 @@
+# obsidian-vault-kb
+
+Turns an Obsidian vault — a folder of Markdown notes with frontmatter,
+`#tags`, and `[[wikilinks]]` — into a knowledge base Claude can search and
+reason over. Works with any vault, on any topic: homelab documentation,
+project notes, research, whatever you keep in Obsidian.
+
+## What it does
+
+- **Reads your vault's own structure** rather than imposing one: your
+  folders become topical categories, your tags and frontmatter become
+  filters, your wikilinks let Claude follow related notes (backlinks) the
+  same way you would clicking through the graph.
+- **Answers grounded in what's actually in your notes.** If the vault
+  doesn't have an answer, Claude says so instead of guessing, and keeps
+  general knowledge clearly separate from what came from your vault.
+- **Optionally writes back**, depending on the mode you choose at setup —
+  from strictly read-only, to appending new dated notes, to actively
+  updating existing ones.
+
+## Setup
+
+After installing the plugin:
+
+```
+/obsidian-vault-kb:setup
+```
+
+This will ask you for:
+
+1. **The vault path(s).** You can register more than one vault (e.g. a
+   personal one and a work one) and refer to them by name.
+2. **A mode:**
+   - `read-only` — Claude can search and read, never write anything.
+   - `append` — Claude can also file new findings as new, dated notes.
+     Existing notes are never touched.
+   - `maintain` — Claude can also update existing notes directly (e.g. add
+     a dated "Update" section, change a status field).
+
+It also whitelists three narrow, read-only helper scripts (see below) so
+searching your vault doesn't require a permission prompt on every single
+`find`/`grep` call.
+
+## Usage
+
+You don't need to invoke anything explicitly — just ask Claude things like:
+
+- "What did I write about the Ceph cluster rebuild?"
+- "Check my notes for how I set up mTLS on Postfix."
+- "Any open items in my homelab notes related to DNS?"
+
+Claude recognizes references to "my notes", "my vault", "my docs", etc.
+and searches automatically. Under the hood it uses three scripts:
+
+- `vault_index.sh` — folder structure, note counts, tags, index/MOC files
+- `vault_search.sh "<query>"` — full-text search, optionally scoped to a
+  subfolder
+- `vault_backlinks.sh "<note-name>"` — notes linking to a given note
+
+All three resolve the vault path only from
+`~/.agent-skills/obsidian-vault-kb/config.json` — they can't be pointed at
+a different directory than what you configured, which is what makes it
+safe to whitelist them without granting broader filesystem access.
+
+## Writing to your vault
+
+Only relevant in `append` or `maintain` mode:
+
+- **`append`** — new findings are filed as new notes (e.g.
+  `Notes/2026-08-04-dns-fix.md`), with frontmatter and wikilinks to related
+  topics. Existing files are never modified.
+- **`maintain`** — Claude may extend an existing note directly instead of
+  creating a new one, when that's the more natural place for the
+  information. You'll always see a summary of what's about to be written
+  before it happens.
+- Writing into the vault is never in the permissions whitelist, regardless
+  of mode — every write stays a normal, visible, confirmable action.
+
+## Multiple vaults
+
+Registered vaults live in `~/.agent-skills/obsidian-vault-kb/config.json`:
+
+```json
+{
+  "vaults": [
+    {"name": "homelab", "path": "/absolute/path/to/homelab-vault"},
+    {"name": "worldbuilding", "path": "/absolute/path/to/tangier-vault"}
+  ],
+  "mode": "append"
+}
+```
+
+If you only ever use one vault, you don't need to name it when asking
+Claude to search — it's used by default.
+
+## What's deliberately *not* included
+
+- No generic `Bash(find:*)`, `Bash(rg:*)`, `Bash(grep:*)`, or `Bash(cat:*)`
+  — those would allow reading anywhere on the filesystem, not just your
+  vault.
+- No auto-approved writes — not to notes, not to the config file.
+- Binary attachments (PDFs, images) inside the vault aren't read
+  automatically, only referenced, unless you ask for them specifically.