---
description: Set up the obsidian-vault-kb skill (vault path, mode, minimal permissions whitelist)
argument-hint: [vault-path] [mode]
---

Set up the `obsidian-vault-kb` skill end to end. As part of the
`obsidian-vault-kb` plugin, this command is automatically namespaced by
Claude Code and invoked as `/obsidian-vault-kb:setup` — no manual filename
prefixing needed. Follow these steps in order.

## 1. Determine the skill's install directory

This plugin's `skills/obsidian-vault-kb/` is a symlink into the repo's
tool-neutral `skills/obsidian-vault-kb/` directory (the single source of
truth for `SKILL.md`, `scripts/`, and `references/`, shared across all
vendor adapters in this repo). Resolve it to its real, absolute,
symlink-free path:

```bash
realpath <plugin-dir>/skills/obsidian-vault-kb
```

This resolved path is `<SKILL_DIR>` for the rest of this setup — you'll
need it exactly for step 4. Use the real path (not the symlink path) so the
permissions whitelisted in step 4 keep working even if this plugin
directory is relocated relative to the shared `skills/` directory.

## 2. Gather vault path and mode

If `$ARGUMENTS` contains a vault path and/or mode, use those directly.
Otherwise ask the user:

1. Absolute path to the Obsidian vault (if there's more than one vault, ask
   for a short name per vault too).
2. Mode: `read-only`, `append`, or `maintain` (as defined in SKILL.md —
   explain briefly if the user is unsure which to pick).

Validate the path exists and is a directory before continuing:

```bash
test -d "<vault-path>" && echo OK || echo "MISSING"
```

If missing, ask the user to correct it before proceeding.

## 3. Write the skill configuration

The config path is tool-neutral (not Claude-specific), so this same file
would be reused if another Agent-Skills-compatible tool ran this skill:

```bash
mkdir -p ~/.agent-skills/obsidian-vault-kb
cat > ~/.agent-skills/obsidian-vault-kb/config.json << 'EOF'
{
  "vaults": [
    {"name": "<short-name>", "path": "<absolute-vault-path>"}
  ],
  "mode": "<read-only|append|maintain>"
}
EOF
cat ~/.agent-skills/obsidian-vault-kb/config.json
```

Confirm the written content with the user.

## 4. Generate and merge the minimal permissions whitelist

Read `permissions-whitelist.template.json` (next to this plugin's
`plugin.json`, i.e. `<plugin-dir>/permissions-whitelist.template.json`). It
whitelists exactly three commands, each pinned to its full absolute path —
no generic `Bash(find:*)`, `Bash(rg:*)`, `Bash(cat:*)`, etc., since those
would allow reading anywhere on the filesystem rather than just the vault:

- `Bash(<SKILL_DIR>/scripts/vault_index.sh:*)`
- `Bash(<SKILL_DIR>/scripts/vault_search.sh:*)`
- `Bash(<SKILL_DIR>/scripts/vault_backlinks.sh:*)`
- `Read(~/.agent-skills/obsidian-vault-kb/config.json)`

These three scripts resolve the vault path only from
`~/.agent-skills/obsidian-vault-kb/config.json` and refuse to operate on any
path outside it (see their source), so whitelisting them by exact path does
not grant broader filesystem access — not even to other files in the same
`scripts/` directory, since the wildcard is per-script-file, not per-folder.

Steps:

1. Replace every `<SKILL_DIR>` placeholder in the template with the real,
   symlink-resolved absolute path from step 1.
2. Locate the target settings file: prefer the project-level
   `.claude/settings.json` if a project is open, otherwise the user-level
   `~/.claude/settings.json`. Ask the user which one they want if unclear.
3. If the target file doesn't exist yet, create it containing just the
   substituted `permissions.allow` array.
4. If it exists, read it first and merge: add only entries from the
   substituted array that aren't already present in the target file's
   `permissions.allow` array. Don't duplicate entries, don't remove or
   overwrite unrelated existing permissions in the file.
5. Show the user exactly what was added (the four entries above with the
   real path filled in) before writing, so they can see precisely what
   they're approving.

Do **not** add anything beyond these four entries. In particular, do not
whitelist writing to the vault or to the config file — those keep prompting
for confirmation every time, by design, in `append`/`maintain` mode.

## 5. Make the helper scripts executable

```bash
chmod +x <SKILL_DIR>/scripts/vault_index.sh <SKILL_DIR>/scripts/vault_search.sh <SKILL_DIR>/scripts/vault_backlinks.sh
```

Note this modifies the shared `skills/obsidian-vault-kb/scripts/` files in
the repo (via the resolved real path), not a plugin-local copy — that's
expected, since the symlink means there is only one copy on disk.

## 6. Confirm and offer a test run

Summarize to the user:
- Vault path(s) and mode that were configured
- The exact four permission entries that were added, and where (project vs.
  user settings)
- That nothing else was whitelisted — every other command, and any write
  into the vault, still prompts for confirmation

Then offer to run `<SKILL_DIR>/scripts/vault_index.sh` as a quick sanity
check, if the user wants to see it working right away.