obsidian

docs/api.md

@@ -77,7 +77,9 @@ not registered. There is no HTML/RSS scraper fallback and no SearXNG.
 has `challenge: true`, finish the prompt in the Jarvis browser window and call
 the tool again. Private, loopback, and metadata URLs fail before Chromium
 starts. Shell HTTP (`curl`/`wget` over public hosts) remains blocked; use
-`browser` instead. Install the browser once with `npm run browser:install`. The
+`browser` instead. Install the browser once with `npm run browser:install`. That
+also unpacks uBlock Origin Lite and Dark Reader into the Jarvis Chromium
+profile and the helper loads them on the next start. The
 daemon looks up Node via `JARVIS_BROWSER_NODE` because `jarvisd` itself runs
 under Bare.
 

docs/obsidian.md

@@ -0,0 +1,82 @@
+# Obsidian agent vault
+
+Jarvis has an opt-in, native JavaScript filesystem bridge. It works with ordinary
+Markdown notes, frontmatter, wiki links, and attachments, including while Obsidian
+is closed. There is no REST server, plugin, API key, or new runtime dependency.
+Obsidian uses [local folders of Markdown files](https://obsidian.md/help/data-storage).
+
+## Setup
+
+1. Open Jarvis Settings → Obsidian.
+2. Enable the bridge. Choose an empty folder or enter an absolute path to a new
+   folder. A blank path uses `$XDG_DATA_HOME/jarvis/obsidian-agent`, normally
+   `~/.local/share/jarvis/obsidian-agent`.
+3. Optionally enable **Use vault for agent memory**. Press **Apply**.
+4. Press **Initialize vault**, then **Verify access**. Verification performs an
+   actual temporary write/read/delete in the vault and separately in `memory/`
+   when memory access is enabled. Refresh shows applied configuration and access.
+5. In Obsidian, select **Open folder as vault** and register that folder once.
+   The settings **Folder** button locates it; **Obsidian** uses the official
+   [open URI](https://obsidian.md/help/uri) after registration. Obsidian installation
+   and registration are separate from filesystem verification.
+
+Both switches default to false. Opening settings, starting the daemon, and
+reading status never initialize a vault. Initialization rejects nonempty personal
+vaults. A Jarvis ownership marker is required for subsequent access. Apply resets
+conversation context when these settings change, without restarting the daemon.
+Disabling the bridge preserves the vault and removes its tool from the agent.
+
+## Agent operations
+
+The `obsidian` tool supports `status`, `list`, `read`, `write`, `mkdir`, `move`,
+`delete`, `trash`, `restore`, `search`, and `memory_search`. All paths are relative
+to the agent vault. Write notes as `.md`; frontmatter and links are preserved as
+raw Markdown. Binary attachments use `encoding: "base64"` for read/write.
+
+Read a file first to obtain its SHA-256 `revision`. Replacement, move, and delete
+require that revision, rejecting stale edits. New files omit it. Writes use a
+sibling temporary file and rename. Moves reject existing destinations and do not
+automatically rewrite links; the agent can search and edit referencing notes.
+Deleting files moves them into `.trash` with their original path and deletion
+time. Restore takes `trashId`, optionally a new `destination`, and never overwrites
+an existing file. Folder deletion only removes empty folders; organize folder
+contents by moving individual files. There is no permanent-delete tool.
+
+When memory is enabled, the agent uses `memory/*.md` and `memory_search` for new
+durable memory instead of the built-in memory tools. Existing workspace memory
+remains as legacy context; there is no automatic migration, synchronization, or
+bulk disclosure to the vault. Settings can browse files, search notes/memory, and
+read selected Markdown. Turning memory off hides and rejects `memory/` paths and
+their trash records through the bridge. Other workspace files and broader file
+access permissions remain governed by the existing agent settings.
+
+Hidden files, `.obsidian` configuration/plugin code, symlinks, hardlinks, traversal,
+and special files are excluded from agent operations. The bridge does not execute
+note contents. This is a dedicated-vault boundary, not an OS sandbox against
+another process running as the same user. Avoid concurrent automated writers:
+revision checks detect edits made before the check, not every possible filesystem
+race with another application.
+
+Files are limited to 2 MiB per bridge operation. Listings stop at 10,000 visited
+entries or 32 levels. Search scans Markdown, up to 32 MiB and 50 matches, and
+reports truncation. Larger attachments can remain in the vault but cannot be
+read or managed through this bounded bridge.
+
+## Configuration and verification
+
+`config.json` fields: `obsidianEnabled` (false), `obsidianVaultPath` (empty string),
+`obsidianMemoryEnabled` (false). GNOME preferences and Control Center share the
+same catalog and page. Changes are applied through `ReloadSettings`.
+
+D-Bus `io.qvac.Jarvis.Session.ObsidianAction(s) → s` accepts a JSON tool action and
+returns JSON. Settings additionally use `initialize` and `verify`. Initialization
+is intentionally unavailable as an agent tool. `GetRuntimeStatus` includes an
+`obsidian` status object. Errors propagate as D-Bus errors.
+
+Run:
+
+```sh
+node --test --experimental-test-isolation=none test/obsidian.test.js test/settings.test.js
+bash packaging/bare-launch.sh packaging/bare-run.js scripts/smoke-obsidian.js
+gjs -m scripts/smoke-settings-ui.js
+```

docs/settings.md

@@ -208,3 +208,11 @@ configuration and are not offered as presets in this change.
 
 Live audio quality, model downloads, and GPU support depend on the host and
 selected model; the automated schema checks do not establish those results.
+
+## Optional Obsidian vault
+
+The **Obsidian** page configures an agent-only vault, disabled by default. It
+includes folder selection, initialization, actual read/write and memory probes,
+note browsing/search, and opening the vault in Obsidian. See
+[Obsidian setup and bridge operations](obsidian.md). Applying these settings
+refreshes the agent session immediately; no service restart is required.