---
name: register_obsidian_vault
kind: function
lang: py
domain: obsidian
version: "1.0.0"
purity: impure
signature: "def register_obsidian_vault(vault_path: str, open: bool = False, config_path: str = '') -> dict"
description: "Registra un vault en la app de escritorio Obsidian anadiendo su entrada a la clave 'vaults' de ~/.config/obsidian/obsidian.json. Opera sobre la config de la app, NO sobre el filesystem del vault. Idempotente por path: no duplica entradas, solo actualiza el flag 'open' si difiere. Genera id hex de 16 chars (secrets.token_hex(8)) y ts en epoch ms. Hace backup .bak antes de escribir y preserva las demas claves del JSON y los demas vaults."
tags: [obsidian, vault, register, config, desktop-app, obsidian-json]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["json", "os", "secrets", "shutil", "time"]
params:
  - name: vault_path
    desc: "ruta al directorio del vault; se normaliza a ruta absoluta antes de registrar"
  - name: open
    desc: "flag 'open' de la entrada (si Obsidian deberia abrirlo al arrancar); default False"
  - name: config_path
    desc: "ruta al obsidian.json de la app; vacio usa ~/.config/obsidian/obsidian.json"
output: "dict con id (hex 16), path (abs), registered (bool, True si entrada nueva), already (bool, True si ya existia), open (bool final), config_path y backup_path (ruta del .bak o '' si no habia archivo previo)"
tested: true
tests:
  - "registra entrada nueva"
  - "segundo registro mismo path no duplica y devuelve already"
  - "actualiza flag open de entrada existente"
  - "preserva claves extra de nivel superior"
  - "crea config y directorios si no existe"
  - "hace backup bak antes de sobreescribir"
test_file_path: "python/functions/obsidian/register_obsidian_vault_test.py"
file_path: "python/functions/obsidian/register_obsidian_vault.py"
---

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from obsidian import register_obsidian_vault

res = register_obsidian_vault(
    vault_path="/home/enmanuel/vaults/osint",
    open=True,
    config_path="",   # usa ~/.config/obsidian/obsidian.json
)
print(res["id"], res["registered"], res["already"])
# 3f9a1c0b7e2d4a86 True False   (primera vez)
# 3f9a1c0b7e2d4a86 False True   (segunda vez, ya registrado)
```

## Cuando usarla

Cuando quieras que la app de escritorio Obsidian "conozca" un vault y lo muestre en su selector de vaults (la pantalla de bienvenida / `Open another vault`). Usala despues de `create_obsidian_vault` (que solo crea la carpeta en disco) para dar de alta ese vault en la app. Es el paso previo natural a `open_obsidian_vault`.

## Gotchas

- **Escribe la config de la app** (I/O impuro) en `~/.config/obsidian/obsidian.json` y crea un backup `.bak` antes de sobreescribir. Si la entrada ya existe y nada cambia, NO reescribe ni genera backup.
- **NO crea la carpeta del vault**: solo registra la entrada. Si la ruta no existe en disco, Obsidian la mostrara pero no podra abrirla. Usa `create_obsidian_vault` para crear la carpeta.
- **Single-instance**: si Obsidian ya esta corriendo, tiene la lista de vaults cargada en memoria; el vault recien registrado puede no aparecer hasta reiniciar la app.
- Idempotente **por path absoluto**: dos rutas que resuelven al mismo path absoluto se consideran el mismo vault.
- Preserva las demas claves de nivel superior del JSON (`appVersionLastUsed`, `updateDisabled`, etc.) y los demas vaults; solo toca la entrada de este vault.
