obsidian-agent-cli 0.1.0__py3-none-any.whl

obsidian_agent_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: obsidian-agent-cli
+Version: 0.1.0
+Summary: Full-featured CLI for Obsidian — manage notes, canvases, Excalidraw, Kanban, periodic notes, git, tasks, and more.
+Author-email: ProxyLand <proxylandllc@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: python-dotenv>=1.0
+
+# obsidian-agent-cli
+
+A full-featured command-line interface for [Obsidian](https://obsidian.md/) — manage your vault, capture knowledge, build canvases, and run plugin commands, all from the terminal or from an AI agent.
+
+Works with any AI coding assistant (Claude Code, Codex, Gemini CLI, etc.) via the included `obsidian_skill.md`.
+
+---
+
+## How It Works: Vault Structure
+
+The CLI is designed around a clean separation of concerns inside your vault:
+
+```
+MyVault/                        ← your Obsidian vault root
+├── .obsidian/
+│
+├── AI Workspace/               ← the AI agent's dedicated folder (managed by this CLI)
+│   ├── registry.json           #   project registry
+│   ├── my-project/             #   per-project knowledge
+│   │   └── knowledge-log.md
+│   └── Teaching Notes/         #   reference notes written by the agent
+│
+├── Your Notes/                 ← your folders — the AI never touches these
+├── Projects/                   ← yours
+└── Journal/                    ← yours
+```
+
+**The AI only operates inside `AI Workspace/`.** Every note, canvas, log, and registry file it creates lives there. Your own folders are completely untouched unless you explicitly pass their paths to a command.
+
+> 💡 **Recommended setup:** Create a dedicated Obsidian vault just for this — don't drop it into an existing vault you already use heavily. A fresh vault keeps things clean. Then `AI Workspace/` is one subfolder inside it, and any other top-level folders you create are entirely yours.
+
+The `AI Workspace` folder name is just the default — rename it to anything you like:
+```bash
+obsidian config set workspace_path "My AI Zone"
+```
+
+---
+
+## Features
+
+| Command group | What it does |
+|---------------|-------------|
+| `note` | Create, read, update, patch, delete notes — including surgical heading-level edits |
+| `search` | Full-text search and Dataview DQL queries |
+| `active` | Read/write the note currently open in Obsidian |
+| `periodic` | Daily, weekly, monthly notes — read, write, patch, navigate |
+| `workspace` | AI workspace project registry and knowledge log |
+| `canvas` | Build and manage Obsidian canvas files from JSON specs |
+| `excalidraw` | Build Excalidraw diagrams from JSON specs |
+| `kanban` | Create and manage Kanban boards |
+| `vault` | Find notes by glob pattern, move/rename files |
+| `tags` | Rename tags across the entire vault |
+| `batch` | Bulk frontmatter edits and find-and-replace |
+| `export` | Bundle notes into a single markdown file |
+| `teach` | Write reference/teaching notes into the vault |
+| `git` | Obsidian Git plugin commands |
+| `tasks` | Tasks plugin — add and list tasks with emoji markers |
+| `template` | Templater plugin commands |
+| `lint` | Obsidian Linter commands |
+| `quickadd` | QuickAdd plugin — open modal or run a choice |
+| `refactor` | Rename, extract headings, merge notes |
+| `mover` | Auto Note Mover — check and trigger rules |
+| `meta` | Metadata Menu — get/set frontmatter fields |
+| `core` | Core Obsidian UI — palette, graph, settings, splits |
+| `uri` | Obsidian URI scheme — works without Obsidian open |
+| `status` | REST API health check |
+| `config` | View and update CLI configuration |
+| `commands` | List and run any Obsidian command by ID |
+
+**All commands output JSON.** Every command returns a single JSON object — parse it, pipe it, or feed it to an AI agent.
+
+**Dual-mode transport.** Commands try the Obsidian REST API first. If Obsidian isn't running, most commands fall back to the vault filesystem directly.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- [Obsidian](https://obsidian.md/) desktop app
+- [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) community plugin (installed and enabled inside Obsidian)
+
+---
+
+## Installation
+
+```bash
+pip install obsidian-agent-cli
+```
+
+Then run the setup wizard:
+
+```bash
+obsidian config init
+```
+
+You'll be prompted for:
+- Your vault path (e.g. `/home/yourname/Documents/MyVault`)
+- Your workspace folder name (default: `AI Workspace`)
+- The REST API URL (default: `http://127.0.0.1:27123`)
+- Your Local REST API key (copy from Obsidian → Settings → Local REST API)
+
+### Verify it works
+
+With Obsidian open:
+```bash
+obsidian status
+```
+
+You should see:
+```json
+{"ok": true, "versions": {"obsidian": "1.x.x"}, "transport": "api"}
+```
+
+---
+
+## Quick Start
+
+```bash
+# Create a note
+obsidian note create "Projects/my-app/arch.md" --content "# Architecture"
+
+# Read it back
+obsidian note read "Projects/my-app/arch.md"
+
+# Search across vault
+obsidian search simple "authentication"
+
+# Register a project for AI knowledge tracking
+obsidian workspace project register my-app
+
+# Log a discovery
+obsidian workspace log my-app "Auth uses RS256 JWTs. Token expiry is 15 min."
+
+# Read back everything the agent knows about this project
+obsidian workspace recall my-app
+
+# Build a canvas overview
+obsidian canvas build "my-app-overview" --spec '{
+  "nodes": [
+    {"type": "text", "text": "# My App"},
+    {"type": "file", "file": "Projects/my-app/arch.md"}
+  ],
+  "edges": [
+    {"from": 0, "to": 1, "label": "documented in", "color": "4"}
+  ]
+}'
+
+# Sync vault with git
+obsidian git sync -m "feat: update project notes"
+```
+
+---
+
+## AI Agent Integration
+
+Drop `obsidian_skill.md` into any project root. Your AI agent (Claude Code, Codex, Gemini CLI, etc.) will automatically:
+
+1. **Register new projects** on first encounter
+2. **Recall prior knowledge** at the start of every session
+3. **Log architectural discoveries** and decisions as they happen
+4. **Build visual canvases** and **write teaching notes** when asked
+
+See [docs/SKILL_SETUP.md](docs/SKILL_SETUP.md) for details.
+
+---
+
+## Configuration
+
+Config is stored in `~/.obsidian-cli/config.json`. You can edit it with `obsidian config`:
+
+```bash
+obsidian config show                              # view current config
+obsidian config set vault_path /path/to/vault    # update vault path
+obsidian config set workspace_path "MyWorkspace"  # rename workspace folder
+obsidian config set api_key YOUR_KEY             # update API key
+obsidian config init                             # re-run setup wizard
+```
+
+---
+
+## Documentation
+
+- [Installation Guide](docs/INSTALL.md)
+- [Usage Guide](docs/USAGE.md)
+- [AI Skill Setup](docs/SKILL_SETUP.md)
+
+---
+
+## Plugin Commands
+
+Many command groups require optional Obsidian plugins:
+
+| Plugin | Required by |
+|--------|------------|
+| [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) | Everything (core dependency) |
+| [Dataview](https://github.com/blacksmithgu/obsidian-dataview) | `search advanced`, `note backlinks`, `note by-tag`, `note recent`, `note orphans`, `note links` |
+| [Obsidian Git](https://github.com/denolehov/obsidian-git) | `git` commands |
+| [Tasks](https://github.com/obsidian-tasks-group/obsidian-tasks) | `tasks ui`, `tasks toggle` |
+| [Templater](https://github.com/SilentVoid13/Templater) | `template` commands |
+| [Linter](https://github.com/platers/obsidian-linter) | `lint` commands |
+| [QuickAdd](https://github.com/chhoumann/quickadd) | `quickadd` commands |
+| [Auto Note Mover](https://github.com/farux/obsidian-auto-note-mover) | `mover` commands |
+| [Metadata Menu](https://github.com/mdelobelle/metadatamenu) | `meta` commands |
+| [Excalidraw](https://github.com/zsviczian/obsidian-excalidraw-plugin) | `excalidraw` commands |
+| [Kanban](https://github.com/mgmeyers/obsidian-kanban) | `kanban archive` |
+
+Commands that don't require a plugin work directly on the filesystem and don't need Obsidian to be open.
+
+---
+
+## License
+
+MIT

obsidian_agent_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+obsidian_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+obsidian_cli/canvas_builder.py,sha256=-miff5IgiBVlwRlxSeRxuwIOzv_Q5tTeRqVwr9CgZDs,4893
+obsidian_cli/config.py,sha256=Rtcamg6sNSqmm9AAmLdfKT_QI4Cv88WcpyvsF73lgZw,1295
+obsidian_cli/excalidraw_builder.py,sha256=dwKhEBWaafRdNyFhtmJEfR5VdsOmsZFIvvOweg6Qb4I,7521
+obsidian_cli/kanban_builder.py,sha256=pEtDdrS2AuPmJeky1mYxGzYSpGhCGIJrFgd7A_tlp0w,2175
+obsidian_cli/main.py,sha256=V4evkeg03WLhxtb0pnVB1RdUpy_7KncrI4xKb0gG1l0,1847
+obsidian_cli/registry.py,sha256=v-Ab4SWgugU5uDpbgpB-iUKetj_roprMaGbmm-3QHsM,3965
+obsidian_cli/transport.py,sha256=nIawcdZ0lld6jvAe2fSQhainSZrhbLnAKSIChk8IA30,21178
+obsidian_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+obsidian_cli/commands/active.py,sha256=hgsUluF9hOLBD1G-g0V0CvFWr5NmPhX5mbX9eOCkkec,2135
+obsidian_cli/commands/batch_cmd.py,sha256=QgVzQismwidjtEpJ-n_ZKb5fi9Q1M6ZfJegkd5O4eHk,3184
+obsidian_cli/commands/canvas.py,sha256=ac6miYVPK5zFRjOeS6nGcqMlsx85eo6wqncI6_RnpbE,4353
+obsidian_cli/commands/config_cmd.py,sha256=9FuuHwVJFq8z_KUj6JdcY4YvbmzQs4d9VgkaTbCPvN4,1880
+obsidian_cli/commands/core_cmd.py,sha256=Yu-8hN6oITuECPdXGXCuUIlpQN1feaBUGln7l5Gaj_8,2128
+obsidian_cli/commands/excalidraw.py,sha256=_WNrimXyC7w73g1w9sVdUUqAkrcJilnrYZKGvaSZCMk,5152
+obsidian_cli/commands/export_cmd.py,sha256=CCKcGAHi4AFbQV6pxiTI4kv48ZG-48PsbwYivpO8tgY,1481
+obsidian_cli/commands/git_cmd.py,sha256=iHP-kEYSCFsSR0J8ZTW9HB3hs8rwjWjAh0cvDBEvUC4,2975
+obsidian_cli/commands/kanban.py,sha256=17Y2TAhqnn82URX2R1MYXNqgmBSuNGK3SSnBvfvEvCE,3061
+obsidian_cli/commands/lint_cmd.py,sha256=ebt1HvSAtxknJ4ojC1LEnl-T7UJhpc_T08NDkVPkArQ,966
+obsidian_cli/commands/meta_cmd.py,sha256=jpFQoeGfMVUArNEECaa8E5QNdqcxqpnecCqkqtKulms,3243
+obsidian_cli/commands/mover_cmd.py,sha256=JDEPhEAS35GGlPlWQgnGvuS9oOGbxKONvpfN28eopZc,2426
+obsidian_cli/commands/note.py,sha256=WzIP5Sm2mKXeOkITnX7w71k-U3ytn63Y-aOhE4JmxII,5450
+obsidian_cli/commands/periodic.py,sha256=d4-qnSNWAmpU_5NdVZVoVETzvvvhoJ-6uHRwbx7Kx9k,4293
+obsidian_cli/commands/quickadd_cmd.py,sha256=Fdh4m68mTGROEQLPlhGrj_3h7HUTRK4lV8GhwerMpjU,2507
+obsidian_cli/commands/refactor_cmd.py,sha256=9Z8D1m5_C-WkPE3SqMd92YZcfWM_7yHZX1v87e8t4uk,2684
+obsidian_cli/commands/run.py,sha256=rKHdsHn9V6bGpZTwtV2CvEt6NLKW4qBHmbiN9cQKBfg,540
+obsidian_cli/commands/search.py,sha256=Ou_YOPmac6mNvF_jGUEVzQbhpN6je3nRn9kBrZN3oHE,923
+obsidian_cli/commands/status_cmd.py,sha256=xaOlPtyPhLCAv0L7xnA5BpkmKZLuLvqijXGPtiZ8scY,321
+obsidian_cli/commands/tags_cmd.py,sha256=8XPPWNr6wRxFfErMVyL4ndix7O1-x1E_TMrbkWupncY,641
+obsidian_cli/commands/tasks_cmd.py,sha256=SniqchZPEqdRjau7UixdzFq26MqJ2Mfs37E8taupDVo,4504
+obsidian_cli/commands/teach.py,sha256=3E6exT8TWBOHIguz4EkaLhE5hAME2OVBE6dsFvsJ260,1200
+obsidian_cli/commands/template_cmd.py,sha256=fl4cu5zcQ5yUsZCLtQh8Tm53U0zMyWJ7f_mFx1Zh-c0,1248
+obsidian_cli/commands/uri.py,sha256=G7YGYQDMqH2vFSku1YtrgcTzvVe1iiUlhXst6-_49rU,2080
+obsidian_cli/commands/vault_cmd.py,sha256=o8_UJduvNcpAwtifuOjt1uHXGubEMvBgXvbmHAStY30,1199
+obsidian_cli/commands/workspace_cmd.py,sha256=Yucns8_mryLs4ZthlrvJMMnSYoL5l_gMDLcmN0EkXXg,1383
+obsidian_agent_cli-0.1.0.dist-info/METADATA,sha256=Blc5Hcquxflf0v2puIAncungZviIF_g8Zcv_d5sSAQo,8287
+obsidian_agent_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+obsidian_agent_cli-0.1.0.dist-info/entry_points.txt,sha256=ccvrN5KUHV5lF2Pr2b6g7wvP5NUkSUrPo9hzUJUm7GA,51
+obsidian_agent_cli-0.1.0.dist-info/top_level.txt,sha256=-RydWe8GVCQoTjjHwhLxteKqKfdnbZ1He0_jOP_wP10,13
+obsidian_agent_cli-0.1.0.dist-info/RECORD,,

obsidian_agent_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

obsidian_agent_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+obsidian = obsidian_cli.main:cli

obsidian_agent_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+obsidian_cli

obsidian_cli/canvas_builder.py

@@ -0,0 +1,127 @@
+import json
+import uuid
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex[:16]
+
+
+def _grid_position(index: int, columns: int = 3,
+                   cell_w: int = 300, cell_h: int = 200,
+                   gap: int = 50) -> tuple[int, int]:
+    col = index % columns
+    row = index // columns
+    return col * (cell_w + gap), row * (cell_h + gap)
+
+
+class CanvasBuilder:
+    def __init__(self):
+        self._nodes: list[dict] = []
+        self._edges: list[dict] = []
+
+    def add_text_node(self, text: str, color: str = "",
+                      width: int = 250, height: int = 100) -> str:
+        node_id = _new_id()
+        x, y = _grid_position(len(self._nodes))
+        node = {"id": node_id, "type": "text", "text": text,
+                 "x": x, "y": y, "width": width, "height": height}
+        if color:
+            node["color"] = color
+        self._nodes.append(node)
+        return node_id
+
+    def add_file_node(self, file_path: str, subpath: str = "",
+                      color: str = "", width: int = 400, height: int = 300) -> str:
+        node_id = _new_id()
+        x, y = _grid_position(len(self._nodes))
+        node = {"id": node_id, "type": "file", "file": file_path,
+                 "x": x, "y": y, "width": width, "height": height}
+        if subpath:
+            node["subpath"] = subpath
+        if color:
+            node["color"] = color
+        self._nodes.append(node)
+        return node_id
+
+    def add_link_node(self, url: str, color: str = "",
+                      width: int = 400, height: int = 300) -> str:
+        node_id = _new_id()
+        x, y = _grid_position(len(self._nodes))
+        node = {"id": node_id, "type": "link", "url": url,
+                 "x": x, "y": y, "width": width, "height": height}
+        if color:
+            node["color"] = color
+        self._nodes.append(node)
+        return node_id
+
+    def add_group_node(self, label: str = "", background: str = "",
+                       background_style: str = "cover",
+                       color: str = "", width: int = 600, height: int = 400) -> str:
+        node_id = _new_id()
+        x, y = _grid_position(len(self._nodes))
+        node = {"id": node_id, "type": "group",
+                 "x": x, "y": y, "width": width, "height": height}
+        if label:
+            node["label"] = label
+        if background:
+            node["background"] = background
+            node["backgroundStyle"] = background_style
+        if color:
+            node["color"] = color
+        self._nodes.append(node)
+        return node_id
+
+    def add_edge(self, from_id: str, to_id: str,
+                 label: str = "", color: str = "",
+                 from_side: str = "right", to_side: str = "left",
+                 from_end: str = "none", to_end: str = "arrow") -> str:
+        edge_id = _new_id()
+        edge = {"id": edge_id, "fromNode": from_id, "toNode": to_id,
+                 "fromSide": from_side, "toSide": to_side,
+                 "fromEnd": from_end, "toEnd": to_end}
+        if label:
+            edge["label"] = label
+        if color:
+            edge["color"] = color
+        self._edges.append(edge)
+        return edge_id
+
+    def build(self) -> dict:
+        return {"nodes": list(self._nodes), "edges": list(self._edges)}
+
+    def to_json(self) -> str:
+        return json.dumps(self.build(), indent=2)
+
+    @classmethod
+    def from_spec(cls, spec: dict) -> "CanvasBuilder":
+        cb = cls()
+        index_to_id: dict[int, str] = {}
+        for i, node_spec in enumerate(spec.get("nodes", [])):
+            t = node_spec.get("type", "text")
+            color = node_spec.get("color", "")
+            if t == "text":
+                nid = cb.add_text_node(node_spec.get("text", ""), color=color)
+            elif t == "file":
+                nid = cb.add_file_node(node_spec.get("file", ""),
+                                       subpath=node_spec.get("subpath", ""),
+                                       color=color)
+            elif t == "link":
+                nid = cb.add_link_node(node_spec.get("url", ""), color=color)
+            elif t == "group":
+                nid = cb.add_group_node(
+                    label=node_spec.get("label", ""),
+                    background=node_spec.get("background", ""),
+                    background_style=node_spec.get("backgroundStyle", "cover"),
+                    color=color,
+                )
+            else:
+                nid = cb.add_text_node(str(node_spec), color=color)
+            index_to_id[i] = nid
+        for edge_spec in spec.get("edges", []):
+            from_id = index_to_id.get(edge_spec.get("from"))
+            to_id = index_to_id.get(edge_spec.get("to"))
+            if from_id and to_id:
+                cb.add_edge(from_id, to_id,
+                            label=edge_spec.get("label", ""),
+                            color=edge_spec.get("color", ""))
+        return cb

obsidian_cli/commands/active.py

@@ -0,0 +1,74 @@
+import json
+import click
+from ..config import load_config
+from ..transport import Transport
+
+
+@click.group()
+def active():
+    """Operations on the currently active note in Obsidian."""
+
+
+@active.command()
+def read():
+    """Read content of the active note."""
+    cfg = load_config()
+    t = Transport(cfg)
+    result = t.get_active()
+    click.echo(json.dumps(result))
+
+
+@active.command()
+def meta():
+    """Read frontmatter, tags, and stat of the active note."""
+    cfg = load_config()
+    t = Transport(cfg)
+    result = t.get_active_meta()
+    click.echo(json.dumps(result))
+
+
+@active.command()
+@click.argument("content")
+def write(content):
+    """Overwrite the active note."""
+    cfg = load_config()
+    t = Transport(cfg)
+    result = t.write_active(content)
+    click.echo(json.dumps(result))
+
+
+@active.command("append")
+@click.argument("content")
+def append_cmd(content):
+    """Append content to the active note."""
+    cfg = load_config()
+    t = Transport(cfg)
+    result = t.append_active(content)
+    click.echo(json.dumps(result))
+
+
+@active.command("patch")
+@click.argument("content")
+@click.option("--operation", default="append", type=click.Choice(["append", "prepend", "replace"]))
+@click.option("--target-type", default="heading", type=click.Choice(["heading", "block", "frontmatter"]))
+@click.option("--target", required=True)
+@click.option("--create-if-missing", is_flag=True, default=False)
+@click.option("--apply-if-preexists", is_flag=True, default=False)
+@click.option("--trim-whitespace", is_flag=True, default=False)
+def patch_cmd(content, operation, target_type, target,
+              create_if_missing, apply_if_preexists, trim_whitespace):
+    """Patch a section of the active note."""
+    cfg = load_config()
+    t = Transport(cfg)
+    result = t.patch_active(content, operation, target_type, target,
+                            create_if_missing, apply_if_preexists, trim_whitespace)
+    click.echo(json.dumps(result))
+
+
+@active.command()
+def delete():
+    """Delete the active note."""
+    cfg = load_config()
+    t = Transport(cfg)
+    result = t.delete_active()
+    click.echo(json.dumps(result))

obsidian_cli/commands/batch_cmd.py

@@ -0,0 +1,91 @@
+import json
+import re
+from pathlib import Path
+import click
+from ..config import load_config
+from ..transport import Transport
+
+
+def _iter_notes(vault_path: str, folder: str = "", pattern: str = "**/*.md") -> list[str]:
+    vault = Path(vault_path)
+    base = vault / folder if folder else vault
+    return [
+        str(p.relative_to(vault)).replace("\\", "/")
+        for p in base.glob(pattern)
+        if ".obsidian" not in p.parts
+    ]
+
+
+@click.group("batch")
+def batch_cmd():
+    """Bulk operations across multiple notes."""
+
+
+@batch_cmd.command("frontmatter")
+@click.argument("field")
+@click.argument("value")
+@click.option("--folder", default="", help="Limit to this vault folder")
+@click.option("--pattern", default="**/*.md", help="Glob pattern for notes")
+@click.option("--dry-run", is_flag=True, default=False)
+def batch_frontmatter(field, value, folder, pattern, dry_run):
+    """Set a frontmatter field to VALUE in all matching notes."""
+    cfg = load_config()
+    t = Transport(cfg)
+    notes = _iter_notes(cfg.vault_path, folder, pattern)
+    changed = []
+    errors = []
+    for note_path in notes:
+        if dry_run:
+            changed.append(note_path)
+            continue
+        result = t.patch_file(note_path, value, "replace", "frontmatter", field,
+                              True, False, False)
+        if result.get("error"):
+            errors.append({"note": note_path, "message": result.get("message")})
+        else:
+            changed.append(note_path)
+    click.echo(json.dumps({
+        "field": field, "value": value,
+        "changed_count": len(changed), "changed": changed,
+        "error_count": len(errors), "errors": errors,
+        "dry_run": dry_run,
+    }))
+
+
+@batch_cmd.command("rename")
+@click.argument("search")
+@click.argument("replacement")
+@click.option("--folder", default="", help="Limit to this vault folder")
+@click.option("--pattern", default="**/*.md")
+@click.option("--regex", "use_regex", is_flag=True, default=False, help="Treat SEARCH as regex")
+@click.option("--dry-run", is_flag=True, default=False)
+def batch_rename(search, replacement, folder, pattern, use_regex, dry_run):
+    """Find-and-replace text across note contents."""
+    cfg = load_config()
+    vault = Path(cfg.vault_path)
+    notes = _iter_notes(cfg.vault_path, folder, pattern)
+    changed = []
+    skipped = []
+    re_search = re.compile(search) if use_regex else None
+    for rel in notes:
+        p = vault / rel
+        text = p.read_text(encoding="utf-8", errors="ignore")
+        if use_regex:
+            if not re_search.search(text):
+                skipped.append(rel)
+                continue
+            new_text = re_search.sub(replacement, text)
+        else:
+            if search not in text:
+                skipped.append(rel)
+                continue
+            new_text = text.replace(search, replacement)
+        changed.append(rel)
+        if not dry_run:
+            p.write_text(new_text, encoding="utf-8")
+    click.echo(json.dumps({
+        "search": search, "replacement": replacement,
+        "changed_count": len(changed), "changed": changed,
+        "skipped_count": len(skipped),
+        "dry_run": dry_run,
+    }))