hyperresearch 0.2.0__py3-none-any.whl

hyperresearch/__init__.py

@@ -0,0 +1,3 @@
+"""Hyperresearch — agent-driven research knowledge base."""
+
+__version__ = "0.2.0"

hyperresearch/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m hyperresearch`."""
+
+from hyperresearch.cli import app  # encoding fix runs in cli/__init__.py
+
+app()

hyperresearch/cli/__init__.py

@@ -0,0 +1,117 @@
+"""Hyperresearch CLI — main typer application."""
+
+import os
+import sys
+
+# Fix Windows console encoding — crawl4ai's rich logger uses Unicode chars that
+# crash on Windows cp1252 consoles. Reconfigure streams to UTF-8 at startup.
+if sys.platform == "win32":
+    os.environ["PYTHONIOENCODING"] = "utf-8"
+    os.environ["PYTHONUTF8"] = "1"
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name)
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+
+import typer
+
+from hyperresearch import __version__
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"hyperresearch v{__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="hyperresearch",
+    help="Agent-driven research knowledge base.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(False, "--version", "-V", callback=_version_callback, is_eager=True, help="Show version"),
+) -> None:
+    pass
+
+
+# Root-level commands
+from hyperresearch.cli.dedup import dedup as _dedup
+from hyperresearch.cli.fetch import fetch as _fetch
+from hyperresearch.cli.import_cmd import import_vault as _import
+from hyperresearch.cli.install import install as _install
+from hyperresearch.cli.main import init as _init
+from hyperresearch.cli.main import status as _status
+from hyperresearch.cli.main import sync as _sync
+from hyperresearch.cli.mcp_cmd import mcp as _mcp
+from hyperresearch.cli.note import note_show as _show
+from hyperresearch.cli.repair import repair as _repair
+from hyperresearch.cli.research import research as _research
+from hyperresearch.cli.search import search as _search
+from hyperresearch.cli.serve import serve as _serve
+from hyperresearch.cli.tag import tag_list as _tags
+from hyperresearch.cli.watch import watch as _watch
+
+app.command("install")(_install)
+
+from hyperresearch.cli.setup import setup as _setup
+
+app.command("setup")(_setup)
+app.command("init")(_init)
+app.command("status")(_status)
+app.command("sync")(_sync)
+app.command("search")(_search)
+app.command("fetch")(_fetch)
+
+from hyperresearch.cli.fetch_batch import fetch_batch as _fetch_batch
+
+app.command("fetch-batch")(_fetch_batch)
+app.command("research")(_research)
+app.command("tags")(_tags)
+app.command("show", hidden=True)(_show)
+app.command("dedup")(_dedup)
+app.command("import")(_import)
+app.command("repair")(_repair)
+app.command("watch")(_watch)
+app.command("serve")(_serve)
+app.command("mcp")(_mcp)
+
+# Sub-apps
+from hyperresearch.cli.batch import app as batch_app
+from hyperresearch.cli.config_cmd import app as config_app
+from hyperresearch.cli.export import app as export_app
+from hyperresearch.cli.git_cmd import app as git_app
+from hyperresearch.cli.graph import app as graph_app
+from hyperresearch.cli.index import app as index_app
+from hyperresearch.cli.lint import app as lint_app
+from hyperresearch.cli.note import app as note_app
+from hyperresearch.cli.tag import app as tag_app
+from hyperresearch.cli.template import app as template_app
+from hyperresearch.cli.topic import app as topic_app
+
+app.add_typer(note_app, name="note", help="Note CRUD operations.")
+app.add_typer(graph_app, name="graph", help="Knowledge graph and link analysis.")
+app.add_typer(index_app, name="index", help="Auto-generated index pages.")
+app.add_typer(lint_app, name="lint", help="Health-check the vault.")
+app.add_typer(export_app, name="export", help="Export notes.")
+app.add_typer(config_app, name="config", help="Configuration.")
+app.add_typer(topic_app, name="topic", help="Topic hierarchy.")
+app.add_typer(batch_app, name="batch", help="Bulk operations.")
+app.add_typer(template_app, name="template", help="Note templates.")
+app.add_typer(git_app, name="git", help="Git integration.")
+app.add_typer(tag_app, name="tag", help="Tag management.")
+
+from hyperresearch.cli.assets import app as assets_app
+from hyperresearch.cli.link import app as link_app
+from hyperresearch.cli.sources import app as sources_app
+
+app.add_typer(sources_app, name="sources", help="Fetched web sources.")
+app.add_typer(assets_app, name="assets", help="Downloaded images, screenshots, and media.")
+app.add_typer(link_app, name="link", help="Auto-discover and insert wiki-links.")

hyperresearch/cli/_output.py

@@ -0,0 +1,131 @@
+"""Dual-mode output: rich terminal for humans, JSON for LLM agents."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.tree import Tree
+
+from hyperresearch.models.output import Envelope
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def output(data: Any, *, json_mode: bool = False, **kwargs: Any) -> None:
+    """Output data in either JSON or rich terminal format."""
+    if json_mode:
+        _output_json(data)
+    else:
+        _output_rich(data, **kwargs)
+
+
+def _output_json(data: Any) -> None:
+    """Output as JSON. Uses sys.stdout with UTF-8 to avoid Windows encoding issues."""
+    import sys
+
+    if isinstance(data, Envelope) or hasattr(data, "model_dump_json"):
+        text = data.model_dump_json(indent=2, exclude_none=True)
+    else:
+        text = json.dumps(data, indent=2, default=str)
+
+    sys.stdout.buffer.write(text.encode("utf-8"))
+    sys.stdout.buffer.write(b"\n")
+    sys.stdout.buffer.flush()
+
+
+def _output_rich(data: Any, **kwargs: Any) -> None:
+    """Output in rich terminal format."""
+    if isinstance(data, Envelope):
+        if not data.ok:
+            err_console.print(f"[red bold]Error:[/] {data.error}")
+            raise typer.Exit(1)
+        _output_rich(data.data, **kwargs)
+        return
+
+    if isinstance(data, dict):
+        _print_dict(data, **kwargs)
+    elif isinstance(data, list):
+        _print_list(data, **kwargs)
+    elif isinstance(data, str):
+        console.print(data)
+    else:
+        console.print(str(data))
+
+
+def _print_dict(data: dict, **kwargs: Any) -> None:
+    """Pretty-print a dict."""
+    for key, value in data.items():
+        if isinstance(value, dict):
+            console.print(f"[bold]{key}:[/]")
+            _print_dict(value)
+        elif isinstance(value, list) and value and isinstance(value[0], dict):
+            console.print(f"\n[bold]{key}:[/]")
+            _print_list(value)
+        else:
+            console.print(f"  [dim]{key}:[/] {value}")
+
+
+def _print_list(data: list, **kwargs: Any) -> None:
+    """Pretty-print a list of items, as a table if they're dicts."""
+    if not data:
+        console.print("  [dim](none)[/]")
+        return
+
+    if isinstance(data[0], dict):
+        table = Table(show_header=True, header_style="bold")
+        cols = list(data[0].keys())
+        for col in cols:
+            table.add_column(col)
+        for item in data:
+            table.add_row(*(str(item.get(c, "")) for c in cols))
+        console.print(table)
+    else:
+        for item in data:
+            console.print(f"  - {item}")
+
+
+def print_note_summary(notes: list[dict], title: str = "Notes") -> None:
+    """Print a table of notes."""
+    table = Table(title=title, show_header=True, header_style="bold")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Title", style="white")
+    table.add_column("Status", style="yellow")
+    table.add_column("Tags", style="green")
+    table.add_column("Words", justify="right", style="dim")
+    for n in notes:
+        tags = ", ".join(n.get("tags", []))
+        table.add_row(
+            n.get("id", ""),
+            n.get("title", ""),
+            n.get("status", ""),
+            tags,
+            str(n.get("word_count", "")),
+        )
+    console.print(table)
+
+
+def print_vault_status(data: dict) -> None:
+    """Print vault status in a nice tree format."""
+    tree = Tree(f"[bold]{data.get('vault_name', 'Vault')}[/]")
+    notes = tree.add("[bold]Notes[/]")
+    nd = data.get("notes", {})
+    notes.add(f"Total: {nd.get('total', 0)}")
+    for status, count in nd.get("by_status", {}).items():
+        notes.add(f"{status}: {count}")
+
+    tags = tree.add("[bold]Tags[/]")
+    tags.add(f"Unique: {data.get('tags', {}).get('total_unique', 0)}")
+
+    graph = tree.add("[bold]Graph[/]")
+    gd = data.get("graph", {})
+    graph.add(f"Links: {gd.get('total_links', 0)}")
+    graph.add(f"Broken: {gd.get('broken_links', 0)}")
+    graph.add(f"Orphans: {gd.get('orphan_notes', 0)}")
+
+    tree.add(f"[dim]Words: {data.get('total_words', 0):,}[/]")
+    console.print(tree)

hyperresearch/cli/assets.py

@@ -0,0 +1,114 @@
+"""Assets CLI — list and view downloaded images, screenshots, and other media."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import error, success
+
+app = typer.Typer()
+
+
+@app.command("list")
+def assets_list(
+    note_id: str | None = typer.Option(None, "--note", "-n", help="Filter by note ID"),
+    asset_type: str | None = typer.Option(None, "--type", "-t", help="Filter by type: image|screenshot|pdf"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+    """List downloaded assets (images, screenshots, PDFs)."""
+    from hyperresearch.core.vault import Vault, VaultError
+
+    try:
+        vault = Vault.discover()
+    except VaultError as e:
+        if json_output:
+            output(error(str(e), "NO_VAULT"), json_mode=True)
+        else:
+            console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1)
+
+    vault.auto_sync()
+    conn = vault.db
+
+    query = "SELECT * FROM assets WHERE 1=1"
+    params: list = []
+    if note_id:
+        query += " AND note_id = ?"
+        params.append(note_id)
+    if asset_type:
+        query += " AND type = ?"
+        params.append(asset_type)
+    query += " ORDER BY created_at DESC"
+
+    rows = conn.execute(query, params).fetchall()
+    assets = [
+        {
+            "id": row["id"],
+            "note_id": row["note_id"],
+            "type": row["type"],
+            "filename": row["filename"],
+            "url": row["url"],
+            "alt_text": row["alt_text"],
+            "content_type": row["content_type"],
+            "size_bytes": row["size_bytes"],
+        }
+        for row in rows
+    ]
+
+    if json_output:
+        output(success(assets, count=len(assets), vault=str(vault.root)), json_mode=True)
+    else:
+        if not assets:
+            console.print("[dim]No assets found.[/]")
+            return
+        for a in assets:
+            size = f"{a['size_bytes'] / 1024:.0f}KB" if a["size_bytes"] else "?"
+            alt = f" — {a['alt_text'][:60]}" if a["alt_text"] else ""
+            console.print(
+                f"  [{a['type']}] {a['note_id']}: {a['filename']} ({size}){alt}"
+            )
+        console.print(f"\n[dim]{len(assets)} assets total[/]")
+
+
+@app.command("path")
+def asset_path(
+    note_id: str = typer.Argument(..., help="Note ID"),
+    asset_type: str = typer.Option("screenshot", "--type", "-t", help="Asset type: screenshot|image"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+    """Get the file path for a note's asset (for viewing with Read tool)."""
+    from hyperresearch.core.vault import Vault, VaultError
+
+    try:
+        vault = Vault.discover()
+    except VaultError as e:
+        if json_output:
+            output(error(str(e), "NO_VAULT"), json_mode=True)
+        else:
+            console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1)
+
+    conn = vault.db
+    rows = conn.execute(
+        "SELECT filename, alt_text, size_bytes FROM assets WHERE note_id = ? AND type = ? ORDER BY id",
+        (note_id, asset_type),
+    ).fetchall()
+
+    if not rows:
+        if json_output:
+            output(error(f"No {asset_type} assets for note '{note_id}'", "NOT_FOUND"), json_mode=True)
+        else:
+            console.print(f"[yellow]No {asset_type} assets for note '{note_id}'[/]")
+        raise typer.Exit(1)
+
+    paths = [
+        {"path": row["filename"], "alt_text": row["alt_text"], "size_bytes": row["size_bytes"]}
+        for row in rows
+    ]
+
+    if json_output:
+        output(success(paths, count=len(paths), vault=str(vault.root)), json_mode=True)
+    else:
+        for p in paths:
+            console.print(p["path"])

hyperresearch/cli/batch.py

@@ -0,0 +1,301 @@
+"""Batch operations — modify multiple notes at once."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import error, success
+
+VALID_STATUSES = {"draft", "review", "evergreen", "stale", "deprecated", "archive"}
+
+
+def _discover_vault(json_output: bool):
+    """Discover vault with proper error handling."""
+    from hyperresearch.core.vault import Vault, VaultError
+    try:
+        return Vault.discover()
+    except VaultError as e:
+        if json_output:
+            output(error(str(e), "NO_VAULT"), json_mode=True)
+        else:
+            console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1)
+
+app = typer.Typer()
+
+
+def _get_matching_notes(vault, status=None, tag=None, parent=None, note_type=None) -> list[dict]:
+    """Find notes matching the given filters."""
+    clauses = ["n.type NOT IN ('index')"]
+    params: list = []
+
+    if status:
+        clauses.append("n.status = ?")
+        params.append(status)
+    if tag:
+        clauses.append("n.id IN (SELECT note_id FROM tags WHERE tag = ?)")
+        params.append(tag.lower())
+    if parent:
+        clauses.append("(n.parent = ? OR n.parent LIKE ?)")
+        params.append(parent)
+        params.append(parent + "/%")
+    if note_type:
+        clauses.append("n.type = ?")
+        params.append(note_type)
+
+    where = " AND ".join(clauses)
+    rows = vault.db.execute(
+        f"SELECT n.id, n.path, n.title FROM notes n WHERE {where} ORDER BY n.title",
+        params,
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def _batch_update_files(vault, notes: list[dict], updates: dict) -> tuple[list[str], list[dict]]:
+    """Update frontmatter on multiple files. Returns (modified_ids, errors)."""
+    modified = []
+    errors = []
+    for n in notes:
+        try:
+            _update_file_frontmatter(vault.root, n["path"], updates)
+            modified.append(n["id"])
+        except Exception as e:
+            errors.append({"id": n["id"], "path": n["path"], "error": str(e)})
+    # Sync after all modifications
+    if modified:
+        from hyperresearch.core.sync import compute_sync_plan, execute_sync
+        plan = compute_sync_plan(vault, force=True)
+        execute_sync(vault, plan)
+    return modified, errors
+
+
+def _update_file_frontmatter(vault_root: Path, rel_path: str, updates: dict) -> None:
+    """Read a note file, patch its frontmatter, write it back."""
+    from hyperresearch.core.frontmatter import parse_frontmatter, serialize_frontmatter
+
+    file_path = vault_root / rel_path
+    content = file_path.read_text(encoding="utf-8-sig")
+    meta, body = parse_frontmatter(content)
+
+    for key, value in updates.items():
+        if key == "add_tag":
+            if value.lower() not in meta.tags:
+                meta.tags.append(value.lower())
+        elif key == "remove_tag":
+            meta.tags = [t for t in meta.tags if t != value.lower()]
+        elif hasattr(meta, key):
+            setattr(meta, key, value)
+
+    meta.updated = datetime.now(UTC)
+    new_content = serialize_frontmatter(meta) + "\n" + body
+    file_path.write_text(new_content, encoding="utf-8")
+
+
+# --- Tag operations ---
+
+@app.command("tag-add")
+def batch_tag_add(
+    tag: str = typer.Argument(..., help="Tag to add"),
+    status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),
+    filter_tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by existing tag"),
+    parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+    """Add a tag to matching notes."""
+    vault = _discover_vault(json_output)
+    vault.auto_sync()
+    notes = _get_matching_notes(vault, status=status, tag=filter_tag, parent=parent)
+
+    if dry_run:
+        data = {"action": "tag-add", "tag": tag, "would_modify": [n["id"] for n in notes]}
+        if json_output:
+            output(success(data, count=len(notes), vault=str(vault.root)), json_mode=True)
+        else:
+            console.print(f"[bold]Would add tag '{tag}' to {len(notes)} notes:[/]")
+            for n in notes:
+                console.print(f"  [cyan]{n['id']}[/] — {n['title']}")
+        return
+
+    for n in notes:
+        _update_file_frontmatter(vault.root, n["path"], {"add_tag": tag})
+
+    from hyperresearch.core.sync import compute_sync_plan, execute_sync
+    plan = compute_sync_plan(vault, force=True)
+    execute_sync(vault, plan)
+
+    if json_output:
+        output(success({"action": "tag-add", "tag": tag, "modified": [n["id"] for n in notes]},
+                        count=len(notes), vault=str(vault.root)), json_mode=True)
+    else:
+        console.print(f"[green]Added tag '{tag}' to {len(notes)} notes.[/]")
+
+
+@app.command("tag-remove")
+def batch_tag_remove(
+    tag: str = typer.Argument(..., help="Tag to remove"),
+    status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),
+    filter_tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by existing tag"),
+    parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+    """Remove a tag from matching notes."""
+    vault = _discover_vault(json_output)
+    vault.auto_sync()
+    notes = _get_matching_notes(vault, status=status, tag=filter_tag or tag, parent=parent)
+
+    if dry_run:
+        data = {"action": "tag-remove", "tag": tag, "would_modify": [n["id"] for n in notes]}
+        if json_output:
+            output(success(data, count=len(notes), vault=str(vault.root)), json_mode=True)
+        else:
+            console.print(f"[bold]Would remove tag '{tag}' from {len(notes)} notes:[/]")
+            for n in notes:
+                console.print(f"  [cyan]{n['id']}[/] — {n['title']}")
+        return
+
+    for n in notes:
+        _update_file_frontmatter(vault.root, n["path"], {"remove_tag": tag})
+
+    from hyperresearch.core.sync import compute_sync_plan, execute_sync
+    plan = compute_sync_plan(vault, force=True)
+    execute_sync(vault, plan)
+
+    if json_output:
+        output(success({"action": "tag-remove", "tag": tag, "modified": [n["id"] for n in notes]},
+                        count=len(notes), vault=str(vault.root)), json_mode=True)
+    else:
+        console.print(f"[green]Removed tag '{tag}' from {len(notes)} notes.[/]")
+
+
+# --- Status operations ---
+
+@app.command("set-status")
+def batch_set_status(
+    new_status: str = typer.Argument(..., help="New status: draft|review|evergreen|stale|deprecated|archive"),
+    status: str | None = typer.Option(None, "--status", "-s", help="Filter by current status"),
+    tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),
+    parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+    """Set status on matching notes."""
+    if new_status not in VALID_STATUSES:
+        msg = f"Invalid status '{new_status}'. Valid: {', '.join(sorted(VALID_STATUSES))}"
+        if json_output:
+            output(error(msg, "INVALID_STATUS"), json_mode=True)
+        else:
+            console.print(f"[red]{msg}[/]")
+        raise typer.Exit(1)
+
+    vault = _discover_vault(json_output)
+    vault.auto_sync()
+    notes = _get_matching_notes(vault, status=status, tag=tag, parent=parent)
+
+    if dry_run:
+        if json_output:
+            output(success({"action": "set-status", "status": new_status,
+                            "would_modify": [n["id"] for n in notes]},
+                           count=len(notes), vault=str(vault.root)), json_mode=True)
+        else:
+            console.print(f"[bold]Would set status '{new_status}' on {len(notes)} notes.[/]")
+        return
+
+    for n in notes:
+        _update_file_frontmatter(vault.root, n["path"], {"status": new_status})
+
+    from hyperresearch.core.sync import compute_sync_plan, execute_sync
+    plan = compute_sync_plan(vault, force=True)
+    execute_sync(vault, plan)
+
+    if json_output:
+        output(success({"action": "set-status", "status": new_status,
+                        "modified": [n["id"] for n in notes]},
+                       count=len(notes), vault=str(vault.root)), json_mode=True)
+    else:
+        console.print(f"[green]Set status '{new_status}' on {len(notes)} notes.[/]")
+
+
+# --- Deprecate ---
+
+@app.command("deprecate")
+def batch_deprecate(
+    status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),
+    tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),
+    parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+    """Mark matching notes as deprecated."""
+    vault = _discover_vault(json_output)
+    vault.auto_sync()
+    notes = _get_matching_notes(vault, status=status, tag=tag, parent=parent)
+
+    if dry_run:
+        if json_output:
+            output(success({"action": "deprecate",
+                            "would_modify": [n["id"] for n in notes]},
+                           count=len(notes), vault=str(vault.root)), json_mode=True)
+        else:
+            console.print(f"[bold]Would deprecate {len(notes)} notes.[/]")
+        return
+
+    updates = {"status": "deprecated", "deprecated": True}
+
+    for n in notes:
+        _update_file_frontmatter(vault.root, n["path"], updates)
+
+    from hyperresearch.core.sync import compute_sync_plan, execute_sync
+    plan = compute_sync_plan(vault, force=True)
+    execute_sync(vault, plan)
+
+    if json_output:
+        output(success({"action": "deprecate", "modified": [n["id"] for n in notes]},
+                       count=len(notes), vault=str(vault.root)), json_mode=True)
+    else:
+        console.print(f"[green]Deprecated {len(notes)} notes.[/]")
+
+
+# --- Parent ---
+
+@app.command("set-parent")
+def batch_set_parent(
+    new_parent: str = typer.Argument(..., help="New parent topic (e.g. ml/deep-learning)"),
+    status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),
+    tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),
+    parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by current parent"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+    """Set parent topic on matching notes."""
+    vault = _discover_vault(json_output)
+    vault.auto_sync()
+    notes = _get_matching_notes(vault, status=status, tag=tag, parent=parent)
+
+    if dry_run:
+        if json_output:
+            output(success({"action": "set-parent", "parent": new_parent,
+                            "would_modify": [n["id"] for n in notes]},
+                           count=len(notes), vault=str(vault.root)), json_mode=True)
+        else:
+            console.print(f"[bold]Would set parent '{new_parent}' on {len(notes)} notes.[/]")
+        return
+
+    for n in notes:
+        _update_file_frontmatter(vault.root, n["path"], {"parent": new_parent})
+
+    from hyperresearch.core.sync import compute_sync_plan, execute_sync
+    plan = compute_sync_plan(vault, force=True)
+    execute_sync(vault, plan)
+
+    if json_output:
+        output(success({"action": "set-parent", "parent": new_parent,
+                        "modified": [n["id"] for n in notes]},
+                       count=len(notes), vault=str(vault.root)), json_mode=True)
+    else:
+        console.print(f"[green]Set parent '{new_parent}' on {len(notes)} notes.[/]")