Skip to content

Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai

Initial commit: fork kasten as hyperresearch

Jordanc25137fb99f6
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..9b8b149
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.idea/
+*.db
+.hyperresearch/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..7a28c2e
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-04-07
+
+### Added
+
+- MCP server with 8 read-only tools (`pip install llm-kasten[mcp]`)
+- `kasten mcp` command (stdio transport for Claude Desktop, Cursor)
+- `kasten tags --min N` to filter out low-count tags
+- `kasten tag alias` and `kasten tag suggest` for tag management
+- `kasten note update` for single-note metadata changes
+- `kasten note new --body-file` to avoid shell escaping
+- `kasten note new` returns `existing_tags` in JSON to reduce tag noise
+- `kasten search` auto-includes note bodies in JSON mode
+- `kasten search --linked-from`, `--linked-to`, `--min-inbound` graph filters
+- `kasten repair --enrich` auto-fills missing tags and summaries
+- `kasten graph stub` creates stub notes for all broken links
+- `kasten serve` with interactive force-directed knowledge graph
+- `kasten dedup` for content similarity detection
+- Auto-inject docs into CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md
+- Temporal index pages: by-month, stale notes, most-linked
+- `-j` short flag for `--json` on every command
+- Alphanumeric search tokenization (mamba3 matches mamba 3)
+- Plural tag normalization during sync
+- Note lifecycle: draft, review, evergreen, stale, deprecated, archive
+- `missing-summary` and `singleton-tags` lint rules
+- Built-in note templates: concept, reference, guide, comparison, moc
+- Vintage cream/brown theme for web UI
+
+### Removed
+
+- External LLM dependencies (OpenAI, Anthropic, Ollama providers)
+- `kasten compile` and `kasten ask` commands (agents drive everything)
+- `kasten ingest` (file, web, pdf) -- agents write files directly
+- Semantic search and ranking modules (dead code)
+- `kasten promote` and `kasten diff` (redundant with repair and sync --dry-run)
+
+### Fixed
+
+- Wiki-link parser strips trailing backslash from shell escaping artifacts
+- URLs in `[[https://...]]` no longer treated as broken note references
+- Index generator deletes stale pages before regenerating
+- XSS protection in web UI
+- Ctrl+C works on Windows for `kasten serve`
+- FTS5 BM25 weights now read from config (were hardcoded)
+- Import writes to knowledge directory, not vault root
+- Batch operations validate status values and handle per-file errors
+
+## [0.1.0] - 2026-04-06
+
+Initial release.
+
+### Core
+
+- Markdown files with YAML frontmatter as source of truth
+- SQLite FTS5 full-text search with BM25 ranking and porter stemming
+- `[[wiki-link]]` parsing with backlink tracking and broken link detection
+- mtime + SHA-256 change detection with atomic transactions
+
+### CLI
+
+- `kasten init`, `status`, `sync`, `search`, `note` CRUD, `graph`, `lint`, `repair`
+- `kasten index build` auto-generated wiki pages
+- `kasten batch` bulk operations
+- `kasten export json` and `export vault`
+- `kasten import`, `watch`, `serve`, `git log`
+- `--json` on every command with consistent envelope format
+
+[0.2.0]: https://github.com/jordan-gibbs/llm-kasten/releases/tag/v0.2.0
+[0.1.0]: https://github.com/jordan-gibbs/llm-kasten/releases/tag/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..ea4a219
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,76 @@
+# Contributing to kasten
+
+Thank you for your interest in contributing.
+
+## Development setup
+
+```bash
+git clone https://github.com/jordan-gibbs/kasten.git
+cd kasten
+python -m venv .venv
+source .venv/bin/activate # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+All tests must pass before submitting a PR. The test suite runs in under 30 seconds.
+
+## Code style
+
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting:
+
+```bash
+ruff check src/
+ruff format src/
+```
+
+Configuration is in `pyproject.toml`. Line length is 100 characters.
+
+## Type checking
+
+```bash
+mypy src/kasten/
+```
+
+Strict mode is enabled in `pyproject.toml`.
+
+## Submitting changes
+
+1. Fork the repository.
+2. Create a branch from `main`.
+3. Make your changes with tests.
+4. Run `ruff check src/` and `python -m pytest tests/`.
+5. Open a pull request against `main`.
+
+Keep PRs focused on a single change. Include a clear description of what changed and why.
+
+## Reporting issues
+
+Open an issue at [github.com/jordan-gibbs/kasten/issues](https://github.com/jordan-gibbs/kasten/issues). Include:
+
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- kasten version (`kasten --version`)
+- Python version and OS
+
+## Architecture overview
+
+- `src/kasten/core/` -- vault management, sync engine, frontmatter parsing, SQLite schema
+- `src/kasten/cli/` -- typer CLI commands, output formatting
+- `src/kasten/search/` -- FTS5 search engine, filters, ranking
+- `src/kasten/models/` -- Pydantic models for notes, output envelopes
+- `src/kasten/graph/` -- link parsing (shared patterns)
+- `src/kasten/indexgen/` -- auto-generated index page builder
+- `src/kasten/ingest/` -- file, web, PDF ingestion
+- `src/kasten/compile/` -- LLM compilation pipeline
+- `src/kasten/llm/` -- provider abstraction (OpenAI, Anthropic, Ollama)
+- `src/kasten/serve/` -- lightweight web UI server
+- `tests/` -- pytest test suite
+
+The key design principle: markdown files are the source of truth, SQLite is a derived cache that can be rebuilt at any time with `kasten sync --force`.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..5edb3e9
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Gibbs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f32a337
--- /dev/null
+++ b/README.md
@@ -0,0 +1,9 @@
+# Hyperresearch
+
+Agent-driven research knowledge base. Browse, collect, and synthesize web sources into a searchable wiki with `[[wiki-links]]`, full-text search, and structured JSON output.
+
+```bash
+pip install hyperresearch
+hyperresearch init .
+hyperresearch search "query" -j
+```
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..6ba7674
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hyperresearch"
+version = "0.1.0"
+description = "Agent-driven research knowledge base. Browse, collect, and synthesize web sources into a searchable wiki."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{name = "Jordan Gibbs", email = "[email protected]"}]
+keywords = ["research", "knowledge-base", "wiki", "llm", "markdown", "cli", "agent", "zettelkasten"]
+classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Environment :: Console",
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: MIT License",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Programming Language :: Python :: 3.13",
+ "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = [
+ "typer>=0.9.0",
+ "rich>=13.0",
+ "pyyaml>=6.0",
+ "pydantic>=2.0",
+ "jinja2>=3.1",
+ "platformdirs>=4.0",
+]
+
+[project.optional-dependencies]
+crawl4ai = ["Crawl4AI>=0.4"]
+tavily = ["tavily-python>=0.5"]
+firecrawl = ["firecrawl>=1.0"]
+trafilatura = ["trafilatura>=2.0"]
+mcp = ["mcp>=1.6"]
+all = ["hyperresearch[crawl4ai,tavily,firecrawl,trafilatura,mcp]"]
+dev = [
+ "pytest>=7.4",
+ "pytest-cov>=4.1",
+ "ruff>=0.3",
+ "mypy>=1.8",
+]
+
+[project.scripts]
+hyperresearch = "hyperresearch.cli:app"
+hpr = "hyperresearch.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/jordan-gibbs/hyperresearch"
+Repository = "https://github.com/jordan-gibbs/hyperresearch"
+Issues = "https://github.com/jordan-gibbs/hyperresearch/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hyperresearch"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "RUF"]
+ignore = [
+ "E501",
+ "B008",
+ "B904",
+ "E402",
+ "N817",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q --strict-markers"
diff --git a/src/hyperresearch/__init__.py b/src/hyperresearch/__init__.py
new file mode 100644
index 0000000..a2e70f5
--- /dev/null
+++ b/src/hyperresearch/__init__.py
@@ -0,0 +1,3 @@
+"""Hyperresearch — agent-driven research knowledge base."""
+
+__version__ = "0.1.0"
diff --git a/src/hyperresearch/__main__.py b/src/hyperresearch/__main__.py
new file mode 100644
index 0000000..d357ec9
--- /dev/null
+++ b/src/hyperresearch/__main__.py
@@ -0,0 +1,5 @@
+"""Allow running as `python -m hyperresearch`."""
+
+from hyperresearch.cli import app
+
+app()
diff --git a/src/hyperresearch/cli/__init__.py b/src/hyperresearch/cli/__init__.py
new file mode 100644
index 0000000..e3aaa06
--- /dev/null
+++ b/src/hyperresearch/cli/__init__.py
@@ -0,0 +1,79 @@
+"""Hyperresearch CLI — main typer application."""
+
+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",
+)
+
+
+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.import_cmd import import_vault as _import
+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.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("init")(_init)
+app.command("status")(_status)
+app.command("sync")(_sync)
+app.command("search")(_search)
+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.")
diff --git a/src/hyperresearch/cli/_output.py b/src/hyperresearch/cli/_output.py
new file mode 100644
index 0000000..155d5c4
--- /dev/null
+++ b/src/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)
diff --git a/src/hyperresearch/cli/batch.py b/src/hyperresearch/cli/batch.py
new file mode 100644
index 0000000..289443c
--- /dev/null
+++ b/src/hyperresearch/cli/batch.py
@@ -0,0 +1,304 @@
+"""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 ---
+
+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.[/]")
+
+
[email protected]("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 ---
+
[email protected]("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 ---
+
[email protected]("deprecate")
+def batch_deprecate(
+ superseded_by: str | None = typer.Option(None, "--superseded-by", help="Note ID of replacement"),
+ 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", "superseded_by": superseded_by,
+ "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}
+ if superseded_by:
+ updates["superseded_by"] = superseded_by
+
+ 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 ---
+
[email protected]("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.[/]")
diff --git a/src/hyperresearch/cli/config_cmd.py b/src/hyperresearch/cli/config_cmd.py
new file mode 100644
index 0000000..9d46653
--- /dev/null
+++ b/src/hyperresearch/cli/config_cmd.py
@@ -0,0 +1,134 @@
+"""Configuration CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import success
+
+app = typer.Typer()
+
+
+def config_show(
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Display current vault configuration."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ config = vault.config
+
+ data = {
+ "vault_name": config.name,
+ "vault_path": str(vault.root),
+ "research_dir": config.research_dir,
+ "auto_sync": config.auto_sync,
+ "auto_build_index": config.auto_build_index,
+ "search_boost_evergreen": config.search_boost_evergreen,
+ "search_penalize_deprecated": config.search_penalize_deprecated,
+ }
+
+ if json_output:
+ output(success(data, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print("[bold]Vault Configuration[/]")
+ for k, v in data.items():
+ console.print(f" [dim]{k}:[/] {v}")
+
+
+def config_set(
+ key: str = typer.Argument(..., help="Config key (dot notation: vault.name)"),
+ value: str = typer.Argument(..., help="Config value"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Set a configuration value."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ config = vault.config
+
+ # Map dot-notation keys to config attributes
+ key_map = {
+ "vault.name": "name",
+ "vault.research_dir": "research_dir",
+ "search.boost_evergreen": "search_boost_evergreen",
+ "search.penalize_deprecated": "search_penalize_deprecated",
+ "sync.auto_sync": "auto_sync",
+ "index.auto_build": "auto_build_index",
+ }
+
+ attr = key_map.get(key)
+ if not attr:
+ console.print(f"[red]Unknown config key:[/] {key}")
+ console.print(f"[dim]Valid keys: {', '.join(key_map.keys())}[/]")
+ raise typer.Exit(1)
+
+ # Type coercion
+ if attr in ("auto_sync", "auto_build_index"):
+ value = value.lower() in ("true", "1", "yes")
+
+ setattr(config, attr, value)
+ config.save(vault.config_path)
+
+ if json_output:
+ output(success({"key": key, "value": value}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Set[/] {key} = {value}")
+
+
+def config_get(
+ key: str = typer.Argument(..., help="Config key"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Get a configuration value."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ config = vault.config
+
+ key_map = {
+ "vault.name": "name",
+ "vault.research_dir": "research_dir",
+ "search.boost_evergreen": "search_boost_evergreen",
+ "search.penalize_deprecated": "search_penalize_deprecated",
+ "sync.auto_sync": "auto_sync",
+ "index.auto_build": "auto_build_index",
+ }
+
+ attr = key_map.get(key)
+ if not attr:
+ console.print(f"[red]Unknown config key:[/] {key}")
+ raise typer.Exit(1)
+
+ value = getattr(config, attr)
+
+ if json_output:
+ output(success({"key": key, "value": value}, vault=str(vault.root)), json_mode=True)
+ else:
+ typer.echo(value)
+
+
[email protected]("agent-docs")
+def config_agent_docs(
+ agents: list[str] = typer.Option(["claude"], "--agents", "-a", help="Which files: claude|agents|gemini|copilot"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Update agent config files (CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md)."""
+ from hyperresearch.core.agent_docs import inject_agent_docs
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ modified = inject_agent_docs(vault.root, agents=agents)
+
+ if json_output:
+ output(success({"modified": modified}, vault=str(vault.root)), json_mode=True)
+ else:
+ if modified:
+ for m in modified:
+ console.print(f" [green]{m}[/]")
+ else:
+ console.print("[dim]Agent docs already up to date.[/]")
diff --git a/src/hyperresearch/cli/dedup.py b/src/hyperresearch/cli/dedup.py
new file mode 100644
index 0000000..e961dc7
--- /dev/null
+++ b/src/hyperresearch/cli/dedup.py
@@ -0,0 +1,93 @@
+"""Content deduplication — find near-duplicate notes."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.core.similarity import jaccard, shingle
+from hyperresearch.models.output import success
+
+
+def dedup(
+ threshold: float = typer.Option(0.6, "--threshold", "-t", help="Similarity threshold (0.0-1.0)"),
+ limit: int = typer.Option(20, "--limit", "-l", help="Max pairs to show"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Find near-duplicate notes by content similarity."""
+ from hyperresearch.core.vault import Vault, VaultError
+
+ try:
+ vault = Vault.discover()
+ except VaultError as e:
+ if json_output:
+ output({"ok": False, "error": str(e)}, json_mode=True)
+ else:
+ console.print(f"[red]Error:[/] {e}")
+ raise typer.Exit(1)
+
+ vault.auto_sync()
+
+ # Load all note content
+ rows = vault.db.execute(
+ "SELECT n.id, n.title, n.word_count, nc.body_plain "
+ "FROM notes n JOIN note_content nc ON n.id = nc.note_id "
+ "WHERE n.type NOT IN ('index') AND n.word_count > 20 "
+ "ORDER BY n.id"
+ ).fetchall()
+
+ if len(rows) < 2:
+ if json_output:
+ output(success({"pairs": [], "total_compared": 0}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print("[dim]Not enough notes to compare.[/]")
+ return
+
+ # Build shingle sets
+ notes = []
+ for row in rows:
+ shingles = shingle(row["body_plain"])
+ notes.append({
+ "id": row["id"],
+ "title": row["title"],
+ "word_count": row["word_count"],
+ "shingles": shingles,
+ })
+
+ # Compare all pairs
+ pairs = []
+ for i in range(len(notes)):
+ for j in range(i + 1, len(notes)):
+ sim = jaccard(notes[i]["shingles"], notes[j]["shingles"])
+ if sim >= threshold:
+ pairs.append({
+ "similarity": round(sim, 3),
+ "note_a": {"id": notes[i]["id"], "title": notes[i]["title"], "words": notes[i]["word_count"]},
+ "note_b": {"id": notes[j]["id"], "title": notes[j]["title"], "words": notes[j]["word_count"]},
+ })
+
+ pairs.sort(key=lambda p: p["similarity"], reverse=True)
+ pairs = pairs[:limit]
+
+ total_compared = len(notes) * (len(notes) - 1) // 2
+
+ if json_output:
+ output(
+ success({"pairs": pairs, "total_compared": total_compared, "threshold": threshold},
+ count=len(pairs), vault=str(vault.root)),
+ json_mode=True,
+ )
+ else:
+ if not pairs:
+ console.print(f"[green]No duplicates found (threshold {threshold:.0%}, compared {total_compared} pairs).[/]")
+ return
+
+ console.print(f"[bold]Similar notes (>{threshold:.0%}):[/]\n")
+ for p in pairs:
+ a, b = p["note_a"], p["note_b"]
+ console.print(
+ f" [bold]{p['similarity']:.0%}[/] | "
+ f"[cyan]{a['id']}[/] ({a['words']}w) "
+ f"<-> [cyan]{b['id']}[/] ({b['words']}w)"
+ )
+ console.print(f"\n[dim]Compared {total_compared} pairs.[/]")
diff --git a/src/hyperresearch/cli/export.py b/src/hyperresearch/cli/export.py
new file mode 100644
index 0000000..0c7b427
--- /dev/null
+++ b/src/hyperresearch/cli/export.py
@@ -0,0 +1,117 @@
+"""Export CLI commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import success
+
+app = typer.Typer()
+
+
+def export_json(
+ output_path: str | None = typer.Option(None, "--output", "-o", help="Output file path"),
+ pretty: bool = typer.Option(True, "--pretty/--compact", help="Pretty print"),
+ json_output: bool = typer.Option(False, "--json", help="JSON output for status"),
+) -> None:
+ """Export all notes as structured JSON."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ notes = []
+ for row in vault.db.execute(
+ "SELECT n.*, nc.body FROM notes n JOIN note_content nc ON n.id = nc.note_id ORDER BY n.title"
+ ):
+ tags = [r["tag"] for r in vault.db.execute("SELECT tag FROM tags WHERE note_id = ?", (row["id"],))]
+ notes.append({
+ "id": row["id"],
+ "title": row["title"],
+ "path": row["path"],
+ "status": row["status"],
+ "type": row["type"],
+ "tags": tags,
+ "created": row["created"],
+ "updated": row["updated"],
+ "word_count": row["word_count"],
+ "source": row["source"],
+ "parent": row["parent"],
+ "summary": row["summary"],
+ "body": row["body"],
+ })
+
+ out = Path(output_path) if output_path else vault.exports_dir / "vault.json"
+ out.parent.mkdir(parents=True, exist_ok=True)
+ indent = 2 if pretty else None
+ out.write_text(json.dumps(notes, indent=indent, default=str), encoding="utf-8")
+
+ if json_output:
+ output(success({"path": str(out), "count": len(notes)}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Exported {len(notes)} notes to:[/] {out}")
+
+
+def export_vault(
+ output_path: str = typer.Argument(..., help="Output directory"),
+ tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),
+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),
+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),
+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview what would be exported"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Export a subset of notes to another directory."""
+ import shutil
+
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ clauses = ["n.type NOT IN ('index')"]
+ params: list = []
+ if tag:
+ clauses.append("n.id IN (SELECT note_id FROM tags WHERE tag = ?)")
+ params.append(tag.lower())
+ if status:
+ clauses.append("n.status = ?")
+ params.append(status)
+ if parent:
+ clauses.append("(n.parent = ? OR n.parent LIKE ?)")
+ params.append(parent)
+ params.append(parent + "/%")
+
+ where = " AND ".join(clauses)
+ rows = vault.db.execute(f"SELECT id, path, title FROM notes n WHERE {where}", params).fetchall()
+
+ out_dir = Path(output_path).resolve()
+ exported = []
+ for row in rows:
+ src = vault.root / row["path"]
+ if not src.exists():
+ continue
+ dest = out_dir / row["path"]
+ exported.append({"id": row["id"], "path": row["path"]})
+ if not dry_run:
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(src, dest)
+
+ if json_output:
+ action = "would_export" if dry_run else "exported"
+ output(success({action: exported, "count": len(exported), "output_path": str(out_dir)},
+ count=len(exported), vault=str(vault.root)), json_mode=True)
+ else:
+ verb = "Would export" if dry_run else "Exported"
+ console.print(f"[green]{verb} {len(exported)} notes to:[/] {out_dir}")
+ for item in exported[:20]:
+ console.print(f" {item['path']}")
+ if len(exported) > 20:
+ console.print(f" [dim]...and {len(exported) - 20} more[/]")
+
+
diff --git a/src/hyperresearch/cli/git_cmd.py b/src/hyperresearch/cli/git_cmd.py
new file mode 100644
index 0000000..e8799fd
--- /dev/null
+++ b/src/hyperresearch/cli/git_cmd.py
@@ -0,0 +1,161 @@
+"""Git integration — changelog, blame, changed files."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import error, success
+
+app = typer.Typer()
+
+
+def _run_git(vault_root: Path, args: list[str]) -> tuple[int, str]:
+ """Run a git command and return (returncode, stdout)."""
+ result = subprocess.run(
+ ["git", *args],
+ capture_output=True,
+ text=True,
+ cwd=str(vault_root),
+ )
+ return result.returncode, result.stdout
+
+
+def git_log(
+ limit: int = typer.Option(20, "--limit", "-l", help="Max commits"),
+ since: str | None = typer.Option(None, "--since", help="Since date (YYYY-MM-DD)"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show notes changed in recent commits."""
+ 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)
+
+ # Use \x00 as delimiter to avoid pipe characters in commit messages
+ args = ["log", f"--max-count={limit}", "--name-only", "--pretty=format:%H%x00%s%x00%ai"]
+ if since:
+ args.append(f"--since={since}")
+ args.append("-- *.md")
+
+ rc, out = _run_git(vault.root, args)
+ if rc != 0:
+ if json_output:
+ output(error("Not a git repository", "NOT_GIT"), json_mode=True)
+ else:
+ console.print("[red]Not a git repository.[/]")
+ raise typer.Exit(1)
+
+ # Parse git log output
+ commits = []
+ current_commit = None
+ for line in out.strip().split("\n"):
+ if not line:
+ continue
+ if "\x00" in line and len(line.split("\x00")) >= 3:
+ parts = line.split("\x00", 2)
+ current_commit = {
+ "hash": parts[0][:8],
+ "message": parts[1],
+ "date": parts[2].strip()[:10],
+ "files": [],
+ }
+ commits.append(current_commit)
+ elif current_commit and line.endswith(".md"):
+ current_commit["files"].append(line.strip())
+
+ if json_output:
+ output(success(commits, count=len(commits), vault=str(vault.root)), json_mode=True)
+ else:
+ if not commits:
+ console.print("[dim]No commits found with .md changes.[/]")
+ return
+ for c in commits:
+ console.print(f"[dim]{c['date']}[/] [bold]{c['hash']}[/] {c['message']}")
+ for f in c["files"]:
+ console.print(f" [cyan]{f}[/]")
+
+
+def git_blame(
+ note_id: str = typer.Argument(..., help="Note ID"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show git blame for a note file."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()
+ if not row:
+ if json_output:
+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)
+ else:
+ console.print(f"[red]Not found:[/] {note_id}")
+ raise typer.Exit(1)
+
+ rc, out = _run_git(vault.root, ["blame", "--porcelain", row["path"]])
+ if rc != 0:
+ if json_output:
+ output(error("Git blame failed", "GIT_ERROR"), json_mode=True)
+ else:
+ console.print("[red]Git blame failed.[/]")
+ raise typer.Exit(1)
+
+ if json_output:
+ output(success({"note_id": note_id, "path": row["path"], "blame": out}, vault=str(vault.root)), json_mode=True)
+ else:
+ # Simplified blame output
+ _rc2, simple = _run_git(vault.root, ["blame", "--date=short", row["path"]])
+ console.print(simple)
+
+
+def git_changed(
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show notes with uncommitted changes."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+
+ rc, out = _run_git(vault.root, ["status", "--porcelain"])
+ if rc != 0:
+ if json_output:
+ output(error("Not a git repository", "NOT_GIT"), json_mode=True)
+ else:
+ console.print("[red]Not a git repository.[/]")
+ raise typer.Exit(1)
+
+ changes = []
+ for line in out.strip().split("\n"):
+ if not line:
+ continue
+ status_code = line[:2].strip()
+ file_path = line[3:].strip()
+ if file_path.endswith(".md"):
+ change_type = {"M": "modified", "A": "added", "D": "deleted", "?": "untracked"}.get(
+ status_code, status_code
+ )
+ changes.append({"status": change_type, "path": file_path})
+
+ if json_output:
+ output(success(changes, count=len(changes), vault=str(vault.root)), json_mode=True)
+ else:
+ if not changes:
+ console.print("[green]No uncommitted changes to .md files.[/]")
+ return
+ for c in changes:
+ style = {"modified": "yellow", "added": "green", "deleted": "red", "untracked": "dim"}.get(c["status"], "")
+ console.print(f" [{style}]{c['status']:10s}[/] {c['path']}")
diff --git a/src/hyperresearch/cli/graph.py b/src/hyperresearch/cli/graph.py
new file mode 100644
index 0000000..9a01d86
--- /dev/null
+++ b/src/hyperresearch/cli/graph.py
@@ -0,0 +1,286 @@
+"""Knowledge graph CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import success
+
+app = typer.Typer()
+
+
[email protected]("backlinks")
+def graph_backlinks(
+ note_id: str = typer.Argument(..., help="Note ID"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show what links TO this note."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute(
+ """
+ SELECT l.source_id, n.title as source_title, n.path as source_path,
+ l.line_number, l.context
+ FROM links l
+ JOIN notes n ON l.source_id = n.id
+ WHERE l.target_id = ?
+ ORDER BY n.title
+ """,
+ (note_id,),
+ ).fetchall()
+
+ backlinks = [
+ {
+ "source_id": r["source_id"],
+ "source_title": r["source_title"],
+ "source_path": r["source_path"],
+ "line_number": r["line_number"],
+ "context": r["context"],
+ }
+ for r in rows
+ ]
+
+ if json_output:
+ output(
+ success({"note_id": note_id, "backlinks": backlinks}, count=len(backlinks), vault=str(vault.root)),
+ json_mode=True,
+ )
+ else:
+ if not backlinks:
+ console.print(f"[dim]No backlinks to {note_id}[/]")
+ return
+ console.print(f"[bold]Backlinks to {note_id}:[/]")
+ for bl in backlinks:
+ console.print(
+ f" [cyan]{bl['source_id']}[/] — {bl['source_title']} "
+ f"[dim](line {bl['line_number']})[/]"
+ )
+
+
[email protected]("outlinks")
+def graph_outlinks(
+ note_id: str = typer.Argument(..., help="Note ID"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show what this note links TO."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute(
+ """
+ SELECT l.target_ref, l.target_id, n.title as target_title,
+ l.line_number, l.context
+ FROM links l
+ LEFT JOIN notes n ON l.target_id = n.id
+ WHERE l.source_id = ?
+ ORDER BY l.line_number
+ """,
+ (note_id,),
+ ).fetchall()
+
+ outlinks = [
+ {
+ "target_ref": r["target_ref"],
+ "target_id": r["target_id"],
+ "target_title": r["target_title"],
+ "line_number": r["line_number"],
+ "resolved": r["target_id"] is not None,
+ }
+ for r in rows
+ ]
+
+ if json_output:
+ output(
+ success({"note_id": note_id, "outlinks": outlinks}, count=len(outlinks), vault=str(vault.root)),
+ json_mode=True,
+ )
+ else:
+ if not outlinks:
+ console.print(f"[dim]No outgoing links from {note_id}[/]")
+ return
+ console.print(f"[bold]Links from {note_id}:[/]")
+ for ol in outlinks:
+ status = "[green]OK[/]" if ol["resolved"] else "[red]BROKEN[/]"
+ title = ol.get("target_title") or ol["target_ref"]
+ console.print(f" {status} [[{ol['target_ref']}]] → {title}")
+
+
+def graph_orphans(
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Find notes with no inbound or outbound links."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute("""
+ SELECT n.id, n.title, n.path, n.status
+ FROM notes n
+ WHERE n.type NOT IN ('index', 'raw')
+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)
+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)
+ ORDER BY n.title
+ """).fetchall()
+
+ orphans = [{"id": r["id"], "title": r["title"], "path": r["path"], "status": r["status"]} for r in rows]
+
+ if json_output:
+ output(success(orphans, count=len(orphans), vault=str(vault.root)), json_mode=True)
+ else:
+ if not orphans:
+ console.print("[green]No orphan notes.[/]")
+ return
+ console.print(f"[bold]Orphan notes ({len(orphans)}):[/]")
+ for o in orphans:
+ console.print(f" [cyan]{o['id']}[/] — {o['title']}")
+
+
+def graph_broken(
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Find broken [[links]] that don't resolve."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute("""
+ SELECT l.source_id, n.title as source_title, l.target_ref, l.line_number
+ FROM links l
+ JOIN notes n ON l.source_id = n.id
+ WHERE l.target_id IS NULL
+ ORDER BY n.title, l.line_number
+ """).fetchall()
+
+ broken = [
+ {
+ "source_id": r["source_id"],
+ "source_title": r["source_title"],
+ "target_ref": r["target_ref"],
+ "line_number": r["line_number"],
+ }
+ for r in rows
+ ]
+
+ if json_output:
+ output(success(broken, count=len(broken), vault=str(vault.root)), json_mode=True)
+ else:
+ if not broken:
+ console.print("[green]No broken links.[/]")
+ return
+ console.print(f"[bold red]Broken links ({len(broken)}):[/]")
+ for b in broken:
+ console.print(
+ f" [cyan]{b['source_id']}[/] line {b['line_number']}: "
+ f"[[{b['target_ref']}]]"
+ )
+
+
+def graph_stub(
+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview what would be created"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Create stub notes for all broken [[links]]."""
+ from hyperresearch.core.note import write_note
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute(
+ "SELECT DISTINCT l.target_ref FROM links l WHERE l.target_id IS NULL ORDER BY l.target_ref"
+ ).fetchall()
+
+ targets = [r["target_ref"] for r in rows]
+
+ if not targets:
+ if json_output:
+ output(success({"stubbed": [], "count": 0}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print("[green]No broken links to stub.[/]")
+ return
+
+ if dry_run:
+ if json_output:
+ output(success({"would_stub": targets, "count": len(targets)}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[bold]Would create {len(targets)} stub notes:[/]")
+ for t in targets:
+ console.print(f" [cyan]{t}[/]")
+ return
+
+ created = []
+ for target in targets:
+ # Create a minimal stub note
+ title = target.replace("-", " ").replace("_", " ").title()
+ path = write_note(
+ vault.notes_dir,
+ title,
+ body=f"# {title}\n\n*Stub — created to resolve a broken link. Expand this note.*\n",
+ note_id=target,
+ status="draft",
+ summary=f"Stub for [[{target}]]",
+ )
+ created.append({"id": target, "title": title, "path": path.relative_to(vault.root).as_posix()})
+
+ # Sync to resolve the links
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+
+ if json_output:
+ output(success({"stubbed": created, "count": len(created)}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Created {len(created)} stub notes:[/]")
+ for c in created:
+ console.print(f" [cyan]{c['id']}[/] — {c['title']}")
+
+
+def graph_hubs(
+ limit: int = typer.Option(20, "--limit", "-l", help="Max results"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show most-linked-to notes."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute(
+ """
+ SELECT l.target_id, n.title, COUNT(*) as inbound
+ FROM links l
+ JOIN notes n ON l.target_id = n.id
+ WHERE l.target_id IS NOT NULL
+ GROUP BY l.target_id
+ ORDER BY inbound DESC
+ LIMIT ?
+ """,
+ (limit,),
+ ).fetchall()
+
+ hubs = [{"id": r["target_id"], "title": r["title"], "inbound_links": r["inbound"]} for r in rows]
+
+ if json_output:
+ output(success(hubs, count=len(hubs), vault=str(vault.root)), json_mode=True)
+ else:
+ from rich.table import Table
+
+ table = Table(title="Hub Notes", show_header=True, header_style="bold")
+ table.add_column("ID", style="cyan")
+ table.add_column("Title")
+ table.add_column("Inbound Links", justify="right", style="green")
+ for h in hubs:
+ table.add_row(h["id"], h["title"], str(h["inbound_links"]))
+ console.print(table)
diff --git a/src/hyperresearch/cli/import_cmd.py b/src/hyperresearch/cli/import_cmd.py
new file mode 100644
index 0000000..59a5334
--- /dev/null
+++ b/src/hyperresearch/cli/import_cmd.py
@@ -0,0 +1,85 @@
+"""Import notes from another vault or directory."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import error, success
+
+
+def import_vault(
+ source: str = typer.Argument(..., help="Source directory to import from"),
+ prefix: str = typer.Option("", "--prefix", "-p", help="Path prefix for imported notes (e.g. imported/ml)"),
+ dry_run: bool = typer.Option(False, "--dry-run", help="Preview what would be imported"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Import markdown notes from another directory into this vault."""
+ 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)
+
+ source_path = Path(source).resolve()
+ if not source_path.is_dir():
+ msg = f"Source directory not found: {source}"
+ if json_output:
+ output(error(msg, "NOT_FOUND"), json_mode=True)
+ else:
+ console.print(f"[red]{msg}[/]")
+ raise typer.Exit(1)
+
+ # Find all .md files in source
+ md_files = sorted(source_path.rglob("*.md"))
+ # Skip .hyperresearch/, templates/ etc. from source
+ skip_dirs = {".hyperresearch", ".git", ".venv", "node_modules", "templates"}
+ md_files = [
+ f for f in md_files
+ if not any(part in skip_dirs for part in f.relative_to(source_path).parts)
+ ]
+
+ if not md_files:
+ if json_output:
+ output(success({"imported": [], "count": 0}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print("[dim]No markdown files found in source.[/]")
+ return
+
+ imported = []
+ for src_file in md_files:
+ rel = src_file.relative_to(source_path).as_posix()
+ dest_rel = f"{prefix}/{rel}" if prefix else rel
+ # Write into research/notes/, not vault root
+ dest = vault.notes_dir / dest_rel
+
+ imported.append({"source": rel, "destination": dest_rel})
+
+ if not dry_run:
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(src_file, dest)
+
+ if not dry_run:
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+
+ if json_output:
+ action = "would_import" if dry_run else "imported"
+ output(success({action: imported, "count": len(imported)}, count=len(imported),
+ vault=str(vault.root)), json_mode=True)
+ else:
+ verb = "Would import" if dry_run else "Imported"
+ console.print(f"[green]{verb} {len(imported)} files:[/]")
+ for item in imported[:20]:
+ console.print(f" {item['source']} -> {item['destination']}")
+ if len(imported) > 20:
+ console.print(f" [dim]...and {len(imported) - 20} more[/]")
diff --git a/src/hyperresearch/cli/index.py b/src/hyperresearch/cli/index.py
new file mode 100644
index 0000000..be68aa2
--- /dev/null
+++ b/src/hyperresearch/cli/index.py
@@ -0,0 +1,77 @@
+"""Index generation CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import success
+
+app = typer.Typer()
+
+
+def index_build(
+ force: bool = typer.Option(False, "--force", "-f", help="Rebuild all indexes"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Regenerate all index pages."""
+ from hyperresearch.core.vault import Vault
+ from hyperresearch.indexgen.generator import IndexGenerator
+
+ vault = Vault.discover()
+ vault.auto_sync()
+ gen = IndexGenerator(vault)
+ built = gen.build_all()
+
+ if json_output:
+ output(success({"built": built}, count=len(built), vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Built {len(built)} index pages:[/]")
+ for p in built:
+ console.print(f" {p}")
+
+
+def index_list(
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show which index pages exist."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ index_dir = vault.index_dir
+ pages = sorted(p.name for p in index_dir.glob("*.md")) if index_dir.exists() else []
+
+ if json_output:
+ output(success(pages, count=len(pages), vault=str(vault.root)), json_mode=True)
+ else:
+ if not pages:
+ console.print("[dim]No index pages. Run 'hyperresearch index build'.[/]")
+ return
+ for p in pages:
+ console.print(f" [cyan]{p}[/]")
+
+
+def index_show(
+ name: str = typer.Argument(..., help="Index page name (e.g. _tags)"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Display a specific index page."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ fname = name if name.endswith(".md") else f"{name}.md"
+ path = vault.index_dir / fname
+ if not path.exists():
+ console.print(f"[red]Index page not found:[/] {fname}")
+ raise typer.Exit(1)
+
+ content = path.read_text(encoding="utf-8")
+ if json_output:
+ output(success({"name": name, "content": content}, vault=str(vault.root)), json_mode=True)
+ else:
+ from rich.markdown import Markdown
+
+ console.print(Markdown(content))
diff --git a/src/hyperresearch/cli/lint.py b/src/hyperresearch/cli/lint.py
new file mode 100644
index 0000000..d7a6404
--- /dev/null
+++ b/src/hyperresearch/cli/lint.py
@@ -0,0 +1,240 @@
+"""Lint / health-check CLI commands."""
+
+from __future__ import annotations
+
+from datetime import UTC
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import success
+
+app = typer.Typer(invoke_without_command=True)
+
+RULES = {
+ "missing-title": "Notes without a title",
+ "missing-tags": "Notes without any tags",
+ "missing-summary": "Notes without a summary",
+ "singleton-tags": "Tags used by only one note",
+ "broken-links": "Wiki-links that don't resolve",
+ "orphaned-notes": "Notes with no inbound or outbound links",
+ "duplicate-ids": "Multiple notes with the same ID",
+ "empty-notes": "Notes with no body content",
+ "stale-indexes": "Index pages that need rebuilding",
+ "expired-notes": "Notes past their expiry date",
+ "deprecated-no-successor": "Deprecated notes without a superseded_by link",
+ "stale-reviews": "Notes not reviewed in over 90 days",
+ "low-confidence": "Notes with confidence < 0.5",
+}
+
+
[email protected](invoke_without_command=True)
+def lint(
+ ctx: typer.Context,
+ fix: bool = typer.Option(False, "--fix", help="Auto-fix what's possible"),
+ rule: str | None = typer.Option(None, "--rule", "-r", help="Run specific rule only"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Health-check the vault."""
+ if ctx.invoked_subcommand is not None:
+ return
+
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+ conn = vault.db
+
+ issues: list[dict] = []
+
+ rules_to_run = [rule] if rule else list(RULES.keys())
+
+ if "missing-title" in rules_to_run:
+ for row in conn.execute("SELECT id, path FROM notes WHERE title = '' OR title = 'Untitled'"):
+ issues.append({
+ "rule": "missing-title",
+ "severity": "warning",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": "Note has no meaningful title.",
+ })
+
+ if "missing-tags" in rules_to_run:
+ for row in conn.execute(
+ "SELECT n.id, n.path FROM notes n "
+ "WHERE n.type NOT IN ('index','raw') "
+ "AND n.id NOT IN (SELECT DISTINCT note_id FROM tags)"
+ ):
+ issues.append({
+ "rule": "missing-tags",
+ "severity": "warning",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": "Note has no tags.",
+ })
+
+ if "missing-summary" in rules_to_run:
+ for row in conn.execute(
+ "SELECT n.id, n.path FROM notes n "
+ "WHERE n.type NOT IN ('index','raw') "
+ "AND (n.summary IS NULL OR LENGTH(TRIM(n.summary)) = 0)"
+ ):
+ issues.append({
+ "rule": "missing-summary",
+ "severity": "warning",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": "Note has no summary. Add one for better search and listings.",
+ })
+
+ if "singleton-tags" in rules_to_run:
+ for row in conn.execute(
+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag HAVING c = 1"
+ ):
+ issues.append({
+ "rule": "singleton-tags",
+ "severity": "info",
+ "note_id": row["tag"],
+ "message": f"Tag '{row['tag']}' is used by only 1 note. Consider merging.",
+ })
+
+ if "broken-links" in rules_to_run:
+ for row in conn.execute(
+ "SELECT l.source_id, n.path, l.target_ref, l.line_number "
+ "FROM links l JOIN notes n ON l.source_id = n.id "
+ "WHERE l.target_id IS NULL"
+ ):
+ issues.append({
+ "rule": "broken-links",
+ "severity": "warning",
+ "note_id": row["source_id"],
+ "note_path": row["path"],
+ "line": row["line_number"],
+ "message": f"Broken link: [[{row['target_ref']}]]",
+ })
+
+ if "orphaned-notes" in rules_to_run:
+ for row in conn.execute("""
+ SELECT n.id, n.path FROM notes n
+ WHERE n.type NOT IN ('index', 'raw')
+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)
+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)
+ """):
+ issues.append({
+ "rule": "orphaned-notes",
+ "severity": "info",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": "Note is orphaned (no links in or out).",
+ })
+
+ if "duplicate-ids" in rules_to_run:
+ for row in conn.execute(
+ "SELECT id, COUNT(*) as c FROM notes GROUP BY id HAVING c > 1"
+ ):
+ issues.append({
+ "rule": "duplicate-ids",
+ "severity": "error",
+ "note_id": row["id"],
+ "message": f"Duplicate ID found {row['c']} times.",
+ })
+
+ if "empty-notes" in rules_to_run:
+ for row in conn.execute(
+ "SELECT n.id, n.path FROM notes n "
+ "JOIN note_content nc ON n.id = nc.note_id "
+ "WHERE LENGTH(TRIM(nc.body)) < 10 AND n.type NOT IN ('index')"
+ ):
+ issues.append({
+ "rule": "empty-notes",
+ "severity": "info",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": "Note has little or no content.",
+ })
+
+ if "expired-notes" in rules_to_run:
+ from datetime import datetime
+ now_iso = datetime.now(UTC).isoformat()
+ for row in conn.execute(
+ "SELECT id, path, expires FROM notes WHERE expires IS NOT NULL AND expires < ?",
+ (now_iso,),
+ ):
+ issues.append({
+ "rule": "expired-notes",
+ "severity": "warning",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": f"Note expired on {row['expires']}. Review or update.",
+ })
+
+ if "deprecated-no-successor" in rules_to_run:
+ for row in conn.execute(
+ "SELECT id, path FROM notes "
+ "WHERE (deprecated = 1 OR status = 'deprecated') AND superseded_by IS NULL"
+ ):
+ issues.append({
+ "rule": "deprecated-no-successor",
+ "severity": "warning",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": "Deprecated but no superseded_by link. What replaces this?",
+ })
+
+ if "stale-reviews" in rules_to_run:
+ from datetime import datetime, timedelta
+ cutoff = (datetime.now(UTC) - timedelta(days=90)).isoformat()
+ for row in conn.execute(
+ "SELECT id, path, reviewed FROM notes "
+ "WHERE reviewed IS NOT NULL AND reviewed < ? AND status = 'evergreen'",
+ (cutoff,),
+ ):
+ issues.append({
+ "rule": "stale-reviews",
+ "severity": "info",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": f"Last reviewed {row['reviewed'][:10]}. Consider re-reviewing.",
+ })
+
+ if "low-confidence" in rules_to_run:
+ for row in conn.execute(
+ "SELECT id, path, confidence FROM notes "
+ "WHERE confidence IS NOT NULL AND confidence < 0.5 AND status != 'deprecated'"
+ ):
+ issues.append({
+ "rule": "low-confidence",
+ "severity": "info",
+ "note_id": row["id"],
+ "note_path": row["path"],
+ "message": f"Low confidence ({row['confidence']:.1%}). Verify or flag.",
+ })
+
+ summary = {
+ "errors": sum(1 for i in issues if i.get("severity") == "error"),
+ "warnings": sum(1 for i in issues if i.get("severity") == "warning"),
+ "info": sum(1 for i in issues if i.get("severity") == "info"),
+ "total": len(issues),
+ }
+
+ if json_output:
+ output(
+ success({"issues": issues, "summary": summary}, count=len(issues), vault=str(vault.root)),
+ json_mode=True,
+ )
+ else:
+ if not issues:
+ console.print("[green]Vault is healthy. No issues found.[/]")
+ return
+
+ severity_style = {"error": "red bold", "warning": "yellow", "info": "dim"}
+ for issue in issues:
+ style = severity_style.get(issue.get("severity", "info"), "dim")
+ loc = issue.get("note_path", issue.get("note_id", ""))
+ line = f" line {issue['line']}" if issue.get("line") else ""
+ console.print(f" [{style}]{issue['rule']}[/] {loc}{line}: {issue['message']}")
+
+ console.print(
+ f"\n[bold]Summary:[/] {summary['errors']} errors, "
+ f"{summary['warnings']} warnings, {summary['info']} info"
+ )
diff --git a/src/hyperresearch/cli/main.py b/src/hyperresearch/cli/main.py
new file mode 100644
index 0000000..e3f514e
--- /dev/null
+++ b/src/hyperresearch/cli/main.py
@@ -0,0 +1,170 @@
+"""Root-level commands: init, status, sync."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from hyperresearch.cli._output import console, output, print_vault_status
+from hyperresearch.models.output import error, success
+
+app = typer.Typer()
+
+
+def init(
+ path: str = typer.Argument(".", help="Path to initialize vault in"),
+ name: str = typer.Option("Research Base", "--name", "-n", help="Vault name"),
+ research_dir: str = typer.Option("research", "--dir", "-d", help="Research directory name"),
+ agents: list[str] = typer.Option(["claude"], "--agents", "-a", help="Agent config files: claude|agents|gemini|copilot"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Initialize a new hyperresearch vault."""
+ from hyperresearch.core.vault import Vault, VaultError
+
+ try:
+ vault = Vault.init(Path(path).resolve(), name=name, research_dir=research_dir, agents=agents)
+ data = {"vault_path": str(vault.root), "name": name}
+ if json_output:
+ output(success(data), json_mode=True)
+ else:
+ console.print(f"[green]Initialized vault:[/] {vault.root}")
+ except VaultError as e:
+ if json_output:
+ output(error(str(e), "VAULT_EXISTS"), json_mode=True)
+ else:
+ console.print(f"[red]Error:[/] {e}")
+ raise typer.Exit(1)
+
+
+def status(
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show vault health and statistics."""
+ 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
+
+ # Gather stats
+ total = conn.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]
+ by_status = {}
+ for row in conn.execute("SELECT status, COUNT(*) as c FROM notes GROUP BY status"):
+ by_status[row["status"]] = row["c"]
+ by_type = {}
+ for row in conn.execute("SELECT type, COUNT(*) as c FROM notes GROUP BY type"):
+ by_type[row["type"]] = row["c"]
+
+ tag_count = conn.execute("SELECT COUNT(DISTINCT tag) as c FROM tags").fetchone()["c"]
+ top_tags = []
+ for row in conn.execute(
+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag ORDER BY c DESC LIMIT 10"
+ ):
+ top_tags.append({"tag": row["tag"], "count": row["c"]})
+
+ total_links = conn.execute("SELECT COUNT(*) as c FROM links").fetchone()["c"]
+ broken = conn.execute(
+ "SELECT COUNT(*) as c FROM links WHERE target_id IS NULL"
+ ).fetchone()["c"]
+ orphans = conn.execute("""
+ SELECT COUNT(*) as c FROM notes n
+ WHERE n.type NOT IN ('index', 'raw')
+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)
+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)
+ """).fetchone()["c"]
+
+ total_words = conn.execute(
+ "SELECT COALESCE(SUM(word_count), 0) as c FROM notes"
+ ).fetchone()["c"]
+
+ last_sync = conn.execute(
+ "SELECT value FROM _meta WHERE key = 'last_sync'"
+ ).fetchone()
+ last_sync_val = last_sync["value"] if last_sync else "never"
+
+ data = {
+ "vault_name": vault.config.name,
+ "vault_path": str(vault.root),
+ "notes": {"total": total, "by_status": by_status, "by_type": by_type},
+ "tags": {"total_unique": tag_count, "top": top_tags},
+ "graph": {"total_links": total_links, "broken_links": broken, "orphan_notes": orphans},
+ "total_words": total_words,
+ "last_sync": last_sync_val,
+ }
+
+ if json_output:
+ output(success(data, vault=str(vault.root)), json_mode=True)
+ else:
+ print_vault_status(data)
+
+
+def sync(
+ force: bool = typer.Option(False, "--force", "-f", help="Full rescan ignoring mtime/hash"),
+ dry_run: bool = typer.Option(False, "--dry-run", help="Show what would change"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Sync database with markdown files on disk."""
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+ 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)
+
+ plan = compute_sync_plan(vault, force=force)
+
+ if dry_run:
+ data = {
+ "to_add": [str(p.relative_to(vault.root)) for p in plan.to_add],
+ "to_update": [str(p.relative_to(vault.root)) for p in plan.to_update],
+ "to_delete": plan.to_delete,
+ "unchanged": plan.unchanged,
+ }
+ if json_output:
+ output(success(data, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print("[bold]Sync plan:[/]")
+ console.print(f" Add: {len(plan.to_add)}")
+ console.print(f" Update: {len(plan.to_update)}")
+ console.print(f" Delete: {len(plan.to_delete)}")
+ console.print(f" Unchanged: {plan.unchanged}")
+ return
+
+ result = execute_sync(vault, plan)
+ data = {
+ "added": result.added,
+ "updated": result.updated,
+ "deleted": result.deleted,
+ "unchanged": result.unchanged,
+ "errors": result.errors,
+ "duration_ms": round(result.duration_ms, 1),
+ }
+
+ if json_output:
+ output(success(data, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(
+ f"[green]Synced:[/] +{result.added} ~{result.updated} "
+ f"-{result.deleted} ={result.unchanged} "
+ f"({result.duration_ms:.0f}ms)"
+ )
+ if result.errors:
+ for err in result.errors:
+ console.print(f" [red]Error:[/] {err['path']}: {err['error']}")
diff --git a/src/hyperresearch/cli/mcp_cmd.py b/src/hyperresearch/cli/mcp_cmd.py
new file mode 100644
index 0000000..8a8d25c
--- /dev/null
+++ b/src/hyperresearch/cli/mcp_cmd.py
@@ -0,0 +1,19 @@
+"""MCP server command — start the hyperresearch MCP server for agent integration."""
+
+from __future__ import annotations
+
+import sys
+
+
+def mcp() -> None:
+ """Start the MCP server (stdio transport) for Claude Desktop, Cursor, etc.
+
+ Requires: pip install hyperresearch[mcp]
+ """
+ try:
+ from hyperresearch.mcp.server import server
+ except ImportError:
+ print("MCP server requires: pip install hyperresearch[mcp]", file=sys.stderr)
+ sys.exit(1)
+
+ server.run()
diff --git a/src/hyperresearch/cli/note.py b/src/hyperresearch/cli/note.py
new file mode 100644
index 0000000..8e4aa40
--- /dev/null
+++ b/src/hyperresearch/cli/note.py
@@ -0,0 +1,490 @@
+"""Note CRUD CLI commands."""
+
+from __future__ import annotations
+
+from datetime import UTC
+
+import typer
+
+from hyperresearch.cli._output import console, output, print_note_summary
+from hyperresearch.models.output import error, success
+
+app = typer.Typer()
+
+
+def note_new(
+ title: str = typer.Argument(..., help="Note title"),
+ body_text: str | None = typer.Option(None, "--body", "-b", help="Note body content (markdown)"),
+ body_file: str | None = typer.Option(None, "--body-file", "-B", help="Read body from file path"),
+ body_stdin: bool = typer.Option(False, "--body-stdin", help="Read body from stdin"),
+ tags: list[str] = typer.Option([], "--tag", "-t", help="Tags"),
+ parent: str | None = typer.Option(None, "--parent", "-p", help="Parent topic"),
+ note_type: str = typer.Option("note", "--type", help="Note type"),
+ status: str = typer.Option("draft", "--status", "-s", help="Initial status"),
+ summary: str | None = typer.Option(None, "--summary", help="One-line summary"),
+ source: str | None = typer.Option(None, "--source", help="Source URL or path"),
+ confidence: float | None = typer.Option(None, "--confidence", help="Confidence 0.0-1.0"),
+ template: str | None = typer.Option(None, "--template", "-T", help="Template: note|concept|reference|guide|comparison|moc"),
+ edit: bool = typer.Option(False, "--edit", "-e", help="Open in $EDITOR"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Create a new note.
+
+ Body content: use --body for short text, --body-file for longer content
+ (avoids shell escaping), or --body-stdin to pipe it in.
+ """
+ import sys
+ from pathlib import Path as P
+
+ from hyperresearch.core.note import write_note
+ from hyperresearch.core.vault import Vault
+ from hyperresearch.models.note import slugify
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ # Determine body content
+ if body_file:
+ body = P(body_file).read_text(encoding="utf-8")
+ elif body_stdin:
+ body = sys.stdin.read()
+ elif body_text:
+ body = body_text
+ else:
+ body = f"# {title}\n\n"
+
+ nid = slugify(title)
+
+ # Check for duplicate before creating
+ similar = vault.db.execute(
+ "SELECT id, title FROM notes WHERE id = ? OR LOWER(title) = LOWER(?)",
+ (nid, title),
+ ).fetchall()
+ if similar:
+ existing = [{"id": r["id"], "title": r["title"]} for r in similar]
+ if json_output:
+ # Warn but still create — agent can decide
+ pass # Will include warning in response below
+ else:
+ for s in existing:
+ console.print(f"[yellow]Similar note exists:[/] {s['id']} — {s['title']}")
+
+ # Use template if specified
+ if template:
+ from hyperresearch.core.templates import get_template, render_template
+
+ tpl = get_template(template, vault.templates_dir)
+ if tpl:
+ rendered = render_template(tpl, title, nid, tags)
+ target_dir = vault.notes_dir
+ if parent:
+ target_dir = target_dir / slugify(parent)
+ target_dir.mkdir(parents=True, exist_ok=True)
+ file_path = target_dir / f"{nid}.md"
+ counter = 2
+ while file_path.exists():
+ file_path = target_dir / f"{nid}-{counter}.md"
+ nid = f"{nid}-{counter}"
+ counter += 1
+ file_path.write_text(rendered, encoding="utf-8")
+ path = file_path
+ else:
+ console.print(f"[yellow]Template '{template}' not found, using default.[/]")
+ path = write_note(vault.notes_dir, title, body=body, tags=tags, status=status,
+ note_type=note_type, parent=parent, summary=summary,
+ source=source)
+ else:
+ path = write_note(vault.notes_dir, title, body=body, tags=tags, status=status,
+ note_type=note_type, parent=parent, summary=summary,
+ source=source)
+
+ # Read back the note ID (may have been collision-adjusted)
+ from hyperresearch.core.note import read_note
+ note = read_note(path, vault.root)
+ nid = note.meta.id
+
+ rel = path.relative_to(vault.root).as_posix()
+
+ if json_output:
+ data = {"id": nid, "path": rel, "title": title}
+ if similar:
+ data["warning"] = f"Similar note already exists: {similar[0]['id']}"
+ data["similar"] = [{"id": r["id"], "title": r["title"]} for r in similar]
+ top_tags = vault.db.execute(
+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag ORDER BY c DESC LIMIT 30"
+ ).fetchall()
+ if top_tags:
+ data["existing_tags"] = [r["tag"] for r in top_tags]
+ output(success(data, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Created:[/] {rel}")
+
+ if edit:
+ import os
+ import subprocess
+
+ editor = os.environ.get("EDITOR", "vim")
+ subprocess.run([editor, str(path)])
+
+
+def note_show(
+ note_ids: list[str] = typer.Argument(..., help="Note ID(s) — pass multiple to read several at once"),
+ raw: bool = typer.Option(False, "--raw", "-r", help="Show raw markdown"),
+ meta: bool = typer.Option(False, "--meta", "-m", help="Show only frontmatter"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Display one or more notes. Pass multiple IDs for batch read."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ def _fetch_note(nid: str) -> dict | None:
+ row = vault.db.execute(
+ "SELECT n.*, nc.body FROM notes n JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?",
+ (nid,),
+ ).fetchone()
+ if not row:
+ return None
+ tag_list = vault.db.execute(
+ "SELECT GROUP_CONCAT(tag, ',') as tl FROM tags WHERE note_id = ?", (nid,)
+ ).fetchone()
+ tags = tag_list["tl"].split(",") if tag_list and tag_list["tl"] else []
+ data = {
+ "id": row["id"], "title": row["title"], "path": row["path"],
+ "status": row["status"], "type": row["type"], "tags": tags,
+ "created": row["created"], "updated": row["updated"],
+ "word_count": row["word_count"], "source": row["source"],
+ "parent": row["parent"], "summary": row["summary"],
+ }
+ if not meta:
+ data["body"] = row["body"]
+ return data
+
+ # Single note — original behavior
+ if len(note_ids) == 1:
+ note_id = note_ids[0]
+ if raw:
+ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()
+ if not row:
+ if json_output:
+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)
+ else:
+ console.print(f"[red]Note not found:[/] {note_id}")
+ raise typer.Exit(1)
+ console.print((vault.root / row["path"]).read_text(encoding="utf-8"))
+ return
+
+ data = _fetch_note(note_id)
+ if not data:
+ if json_output:
+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)
+ else:
+ console.print(f"[red]Note not found:[/] {note_id}")
+ raise typer.Exit(1)
+
+ if json_output:
+ output(success(data, vault=str(vault.root)), json_mode=True)
+ else:
+ if meta:
+ for k, v in data.items():
+ if v is not None:
+ console.print(f" [dim]{k}:[/] {v}")
+ else:
+ tags = data.get("tags", [])
+ console.print(f"[bold]{data['title']}[/] [dim]({data['id']})[/]")
+ console.print(f"[dim]Status: {data['status']} | Tags: {', '.join(tags)}[/]")
+ console.print()
+ from rich.markdown import Markdown
+ console.print(Markdown(data.get("body", "")))
+ return
+
+ # Multi-note — batch read
+ notes = []
+ not_found = []
+ for nid in note_ids:
+ data = _fetch_note(nid)
+ if data:
+ notes.append(data)
+ else:
+ not_found.append(nid)
+
+ if json_output:
+ result = {"notes": notes, "not_found": not_found}
+ output(success(result, count=len(notes), vault=str(vault.root)), json_mode=True)
+ else:
+ for data in notes:
+ tags = data.get("tags", [])
+ console.print(f"\n[bold]{data['title']}[/] [dim]({data['id']})[/]")
+ console.print(f"[dim]Status: {data['status']} | Tags: {', '.join(tags)}[/]")
+ if not meta:
+ console.print()
+ from rich.markdown import Markdown
+ console.print(Markdown(data.get("body", "")))
+ if not_found:
+ console.print(f"\n[red]Not found:[/] {', '.join(not_found)}")
+
+
+def note_list(
+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),
+ note_type: str | None = typer.Option(None, "--type", help="Filter by type"),
+ tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),
+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent"),
+ sort: str = typer.Option("updated", "--sort", help="Sort: created|updated|title|words"),
+ limit: int = typer.Option(20, "--limit", "-l", help="Max results"),
+ all_notes: bool = typer.Option(False, "--all", "-a", help="Return all notes (no limit)"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """List notes with optional filters."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ clauses = []
+ params: list = []
+
+ if status:
+ clauses.append("n.status = ?")
+ params.append(status)
+ if note_type:
+ clauses.append("n.type = ?")
+ params.append(note_type)
+ if parent:
+ clauses.append("n.parent = ?")
+ params.append(parent)
+ if tag:
+ clauses.append("n.id IN (SELECT note_id FROM tags WHERE tag = ?)")
+ params.append(tag.lower())
+
+ where = " AND ".join(clauses) if clauses else "1=1"
+
+ sort_map = {
+ "created": "n.created DESC",
+ "updated": "COALESCE(n.updated, n.created) DESC",
+ "title": "n.title ASC",
+ "words": "n.word_count DESC",
+ }
+ order = sort_map.get(sort, "COALESCE(n.updated, n.created) DESC")
+
+ effective_limit = 999999 if all_notes else limit
+ rows = vault.db.execute(
+ f"""SELECT n.*,
+ (SELECT GROUP_CONCAT(t.tag, ',') FROM tags t WHERE t.note_id = n.id) as tag_list
+ FROM notes n WHERE {where} ORDER BY {order} LIMIT ?""",
+ [*params, effective_limit],
+ ).fetchall()
+
+ notes = []
+ for row in rows:
+ tag_list = row["tag_list"].split(",") if row["tag_list"] else []
+ notes.append({
+ "id": row["id"],
+ "title": row["title"],
+ "path": row["path"],
+ "status": row["status"],
+ "type": row["type"],
+ "tags": tag_list,
+ "word_count": row["word_count"],
+ "summary": row["summary"],
+ "created": row["created"],
+ "updated": row["updated"],
+ })
+
+ if json_output:
+ output(
+ success(notes, count=len(notes), vault=str(vault.root)),
+ json_mode=True,
+ )
+ else:
+ print_note_summary(notes)
+
+
+def note_edit(
+ note_id: str = typer.Argument(..., help="Note ID to edit"),
+) -> None:
+ """Open a note in $EDITOR."""
+ import os
+ import subprocess
+
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()
+ if not row:
+ console.print(f"[red]Not found:[/] {note_id}")
+ raise typer.Exit(1)
+
+ file_path = vault.root / row["path"]
+ editor = os.environ.get("EDITOR", os.environ.get("VISUAL", "notepad" if os.name == "nt" else "vim"))
+ subprocess.run([editor, str(file_path)])
+
+
+def note_update(
+ note_id: str = typer.Argument(..., help="Note ID"),
+ set_status: str | None = typer.Option(None, "--status", "-s", help="Set status"),
+ add_tag: list[str] = typer.Option([], "--add-tag", help="Add tag(s)"),
+ remove_tag: list[str] = typer.Option([], "--remove-tag", help="Remove tag(s)"),
+ set_summary: str | None = typer.Option(None, "--summary", help="Set summary"),
+ set_parent: str | None = typer.Option(None, "--parent", "-p", help="Set parent topic"),
+ set_source: str | None = typer.Option(None, "--source", help="Set source URL/path"),
+ set_confidence: float | None = typer.Option(None, "--confidence", help="Set confidence 0.0-1.0"),
+ set_superseded_by: str | None = typer.Option(None, "--superseded-by", help="Mark as superseded"),
+ deprecate: bool = typer.Option(False, "--deprecate", help="Mark as deprecated"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Update frontmatter fields on a single note."""
+ from datetime import datetime
+
+ from hyperresearch.core.frontmatter import parse_frontmatter, serialize_frontmatter
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()
+ if not row:
+ if json_output:
+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)
+ else:
+ console.print(f"[red]Not found:[/] {note_id}")
+ raise typer.Exit(1)
+
+ file_path = vault.root / row["path"]
+ content = file_path.read_text(encoding="utf-8-sig")
+ meta, body = parse_frontmatter(content)
+
+ changed = []
+ if set_status:
+ meta.status = set_status
+ changed.append(f"status={set_status}")
+ for t in add_tag:
+ if t.lower() not in meta.tags:
+ meta.tags.append(t.lower())
+ changed.append(f"+tag:{t}")
+ for t in remove_tag:
+ if t.lower() in meta.tags:
+ meta.tags.remove(t.lower())
+ changed.append(f"-tag:{t}")
+ if set_summary is not None:
+ meta.summary = set_summary
+ changed.append("summary")
+ if set_parent is not None:
+ meta.parent = set_parent
+ changed.append(f"parent={set_parent}")
+ if set_source is not None:
+ meta.source = set_source
+ changed.append("source")
+ if set_confidence is not None:
+ meta.confidence = set_confidence
+ changed.append(f"confidence={set_confidence}")
+ if set_superseded_by is not None:
+ meta.superseded_by = set_superseded_by
+ changed.append(f"superseded_by={set_superseded_by}")
+ if deprecate:
+ meta.deprecated = True
+ meta.status = "deprecated"
+ changed.append("deprecated")
+
+ if not changed:
+ if json_output:
+ output(success({"id": note_id, "changed": []}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print("[dim]Nothing to update.[/]")
+ return
+
+ meta.updated = datetime.now(UTC)
+ new_content = serialize_frontmatter(meta) + "\n" + body
+ file_path.write_text(new_content, encoding="utf-8")
+
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+
+ if json_output:
+ output(success({"id": note_id, "changed": changed}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Updated {note_id}:[/] {', '.join(changed)}")
+
+
+def note_mv(
+ note_id: str = typer.Argument(..., help="Note ID to move"),
+ new_path: str = typer.Argument(..., help="New relative path (e.g. notes/python/renamed.md)"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Move/rename a note, updating all references."""
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()
+ if not row:
+ if json_output:
+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)
+ else:
+ console.print(f"[red]Not found:[/] {note_id}")
+ raise typer.Exit(1)
+
+ old_file = vault.root / row["path"]
+ new_file = vault.root / new_path
+
+ new_file.parent.mkdir(parents=True, exist_ok=True)
+ old_file.rename(new_file)
+
+ # Re-sync
+ plan = compute_sync_plan(vault, force=True)
+ execute_sync(vault, plan)
+
+ if json_output:
+ output(success({"old_path": row["path"], "new_path": new_path}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Moved:[/] {row['path']} → {new_path}")
+
+
+def note_rm(
+ note_id: str = typer.Argument(..., help="Note ID to delete"),
+ force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Delete a note."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ row = vault.db.execute("SELECT path FROM notes WHERE id = ?", (note_id,)).fetchone()
+ if not row:
+ if json_output:
+ output(error(f"Note not found: {note_id}", "NOT_FOUND"), json_mode=True)
+ else:
+ console.print(f"[red]Not found:[/] {note_id}")
+ raise typer.Exit(1)
+
+ file_path = vault.root / row["path"]
+ if not force and not json_output:
+ typer.confirm(f"Delete {row['path']}?", abort=True)
+
+ if file_path.exists():
+ file_path.unlink()
+
+ # Re-sync to update DB
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+
+ if json_output:
+ output(success({"deleted": note_id}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[red]Deleted:[/] {note_id}")
+
+
diff --git a/src/hyperresearch/cli/repair.py b/src/hyperresearch/cli/repair.py
new file mode 100644
index 0000000..b4e49c4
--- /dev/null
+++ b/src/hyperresearch/cli/repair.py
@@ -0,0 +1,254 @@
+"""Repair command — fix and rebuild everything in one shot."""
+
+from __future__ import annotations
+
+from datetime import UTC
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import error, success
+
+
+def repair(
+ stub_broken: bool = typer.Option(True, "--stub/--no-stub", help="Create stubs for broken links"),
+ enrich: bool = typer.Option(True, "--enrich/--no-enrich", help="Auto-tag and auto-summarize notes"),
+ promote_notes: bool = typer.Option(True, "--promote/--no-promote", help="Auto-promote qualifying notes"),
+ rebuild_index: bool = typer.Option(True, "--index/--no-index", help="Rebuild index pages"),
+ update_docs: bool = typer.Option(True, "--docs/--no-docs", help="Update CLAUDE.md/AGENTS.md"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Repair and rebuild the vault — full sync, fix broken links, promote notes, rebuild indexes."""
+ 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)
+
+ report: dict = {}
+
+ # Step 1: Force sync — rebuild DB from all files
+ if not json_output:
+ console.print("[bold]1/6 Syncing...[/]")
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+ plan = compute_sync_plan(vault, force=True)
+ result = execute_sync(vault, plan)
+ report["sync"] = {
+ "added": result.added, "updated": result.updated,
+ "deleted": result.deleted, "errors": len(result.errors),
+ }
+ if not json_output:
+ console.print(
+ f" +{result.added} ~{result.updated} -{result.deleted} "
+ f"({result.duration_ms:.0f}ms)"
+ )
+
+ # Step 2: Stub broken links
+ stubs_created = 0
+ if stub_broken:
+ if not json_output:
+ console.print("[bold]2/6 Stubbing broken links...[/]")
+ from hyperresearch.core.note import write_note
+ rows = vault.db.execute(
+ "SELECT DISTINCT target_ref FROM links WHERE target_id IS NULL"
+ ).fetchall()
+ for row in rows:
+ target = row["target_ref"]
+ title = target.replace("-", " ").replace("_", " ").title()
+ try:
+ write_note(
+ vault.notes_dir, title,
+ body=f"# {title}\n\n*Stub — created to resolve a broken link. Expand this note.*\n",
+ note_id=target, status="draft",
+ summary=f"Stub for [[{target}]]",
+ )
+ stubs_created += 1
+ except Exception:
+ pass
+ if stubs_created:
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+ report["stubs"] = stubs_created
+ if not json_output:
+ console.print(f" {stubs_created} stubs created")
+ else:
+ if not json_output:
+ console.print("[dim]2/6 Skipping stubs[/]")
+
+ # Step 3: Enrich — auto-tag and auto-summarize
+ enriched_count = 0
+ if enrich:
+ if not json_output:
+ console.print("[bold]3/6 Enriching metadata...[/]")
+ from datetime import datetime as _dt
+
+ from hyperresearch.core.enrich import auto_summary, auto_tag
+ from hyperresearch.core.frontmatter import parse_frontmatter as _parse_fm
+ from hyperresearch.core.frontmatter import serialize_frontmatter as _ser_fm
+
+ # Get existing tag vocabulary
+ tag_vocab = [
+ {"tag": r["tag"], "count": r["c"]}
+ for r in vault.db.execute("SELECT tag, COUNT(*) as c FROM tags GROUP BY tag ORDER BY c DESC")
+ ]
+
+ # Find notes missing tags or summary
+ deficient = vault.db.execute(
+ "SELECT n.id, n.path, n.summary FROM notes n "
+ "LEFT JOIN note_content nc ON n.id = nc.note_id "
+ "WHERE n.type NOT IN ('index', 'raw') AND ("
+ " n.id NOT IN (SELECT DISTINCT note_id FROM tags) OR "
+ " n.summary IS NULL OR LENGTH(TRIM(COALESCE(n.summary, ''))) = 0"
+ ")"
+ ).fetchall()
+
+ for row in deficient:
+ try:
+ fp = vault.root / row["path"]
+ meta, body = _parse_fm(fp.read_text(encoding="utf-8-sig"))
+ changed = False
+
+ # Auto-tag if no tags
+ if not meta.tags:
+ from hyperresearch.core.note import strip_markdown
+ body_plain = strip_markdown(body)
+ suggested = auto_tag(body_plain, tag_vocab)
+ if suggested:
+ meta.tags = suggested
+ changed = True
+
+ # Auto-summary if no summary
+ if not meta.summary or not meta.summary.strip():
+ suggested = auto_summary(body)
+ if suggested:
+ meta.summary = suggested
+ changed = True
+
+ if changed:
+ meta.updated = _dt.now(UTC)
+ fp.write_text(_ser_fm(meta) + "\n" + body, encoding="utf-8")
+ enriched_count += 1
+ except Exception:
+ pass
+
+ if enriched_count:
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+ report["enriched"] = enriched_count
+ if not json_output:
+ console.print(f" {enriched_count} notes enriched")
+ else:
+ if not json_output:
+ console.print("[dim]3/6 Skipping enrichment[/]")
+
+ # Step 4: Promote notes
+ promoted_count = 0
+ if promote_notes:
+ if not json_output:
+ console.print("[bold]4/6 Promoting notes...[/]")
+ from datetime import datetime
+
+ from hyperresearch.core.frontmatter import parse_frontmatter, serialize_frontmatter
+
+ # Draft -> Review
+ drafts = vault.db.execute("""
+ SELECT n.id, n.path FROM notes n
+ WHERE n.status = 'draft' AND n.type NOT IN ('index')
+ AND n.word_count >= 50
+ AND n.summary IS NOT NULL AND LENGTH(n.summary) > 0
+ AND n.id IN (SELECT note_id FROM tags)
+ """).fetchall()
+ for row in drafts:
+ try:
+ fp = vault.root / row["path"]
+ meta, body = parse_frontmatter(fp.read_text(encoding="utf-8-sig"))
+ meta.status = "review"
+ meta.updated = datetime.now(UTC)
+ fp.write_text(serialize_frontmatter(meta) + "\n" + body, encoding="utf-8")
+ promoted_count += 1
+ except Exception:
+ pass
+
+ # Review -> Evergreen
+ reviews = vault.db.execute("""
+ SELECT n.id, n.path FROM notes n
+ WHERE n.status = 'review' AND n.type NOT IN ('index')
+ AND n.word_count >= 100
+ AND (n.id IN (SELECT DISTINCT source_id FROM links)
+ OR n.id IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL))
+ """).fetchall()
+ for row in reviews:
+ try:
+ fp = vault.root / row["path"]
+ meta, body = parse_frontmatter(fp.read_text(encoding="utf-8-sig"))
+ meta.status = "evergreen"
+ meta.updated = datetime.now(UTC)
+ fp.write_text(serialize_frontmatter(meta) + "\n" + body, encoding="utf-8")
+ promoted_count += 1
+ except Exception:
+ pass
+
+ if promoted_count:
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+ report["promoted"] = promoted_count
+ if not json_output:
+ console.print(f" {promoted_count} notes promoted")
+ else:
+ if not json_output:
+ console.print("[dim]4/6 Skipping promotion[/]")
+
+ # Step 4: Rebuild indexes
+ if rebuild_index:
+ if not json_output:
+ console.print("[bold]5/6 Rebuilding indexes...[/]")
+ from hyperresearch.indexgen.generator import IndexGenerator
+ gen = IndexGenerator(vault)
+ built = gen.build_all()
+ # Sync the new index pages
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+ report["indexes"] = len(built)
+ if not json_output:
+ console.print(f" {len(built)} index pages built")
+ else:
+ if not json_output:
+ console.print("[dim]5/6 Skipping indexes[/]")
+
+ # Step 5: Update agent docs
+ if update_docs:
+ if not json_output:
+ console.print("[bold]6/6 Updating agent docs...[/]")
+ from hyperresearch.core.agent_docs import inject_agent_docs
+ modified = inject_agent_docs(vault.root)
+ report["agent_docs"] = modified
+ if not json_output:
+ if modified:
+ for m in modified:
+ console.print(f" {m}")
+ else:
+ console.print(" Already up to date")
+ else:
+ if not json_output:
+ console.print("[dim]6/6 Skipping agent docs[/]")
+
+ # Final lint summary
+ broken = vault.db.execute("SELECT COUNT(*) as c FROM links WHERE target_id IS NULL").fetchone()["c"]
+ orphans = vault.db.execute("""
+ SELECT COUNT(*) as c FROM notes n
+ WHERE n.type NOT IN ('index', 'raw')
+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)
+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)
+ """).fetchone()["c"]
+ total = vault.db.execute("SELECT COUNT(*) as c FROM notes WHERE type NOT IN ('index')").fetchone()["c"]
+ report["health"] = {"total_notes": total, "broken_links": broken, "orphans": orphans}
+
+ if json_output:
+ output(success(report, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"\n[bold]Done.[/] {total} notes, {broken} broken links, {orphans} orphans.")
diff --git a/src/hyperresearch/cli/search.py b/src/hyperresearch/cli/search.py
new file mode 100644
index 0000000..ea191dc
--- /dev/null
+++ b/src/hyperresearch/cli/search.py
@@ -0,0 +1,104 @@
+"""Search CLI — full-text search across all notes."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import error, success
+
+
+def search(
+ query: str = typer.Argument(..., help="Search query"),
+ tag: list[str] = typer.Option([], "--tag", "-t", help="Filter by tag (AND logic)"),
+ status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),
+ note_type: str | None = typer.Option(None, "--type", help="Filter by type"),
+ parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent topic"),
+ after: str | None = typer.Option(None, "--after", help="Created after date (YYYY-MM-DD)"),
+ before: str | None = typer.Option(None, "--before", help="Created before date (YYYY-MM-DD)"),
+ path_glob: str | None = typer.Option(None, "--path", help="Glob filter on path"),
+ min_words: int | None = typer.Option(None, "--min-words", help="Minimum word count"),
+ max_words: int | None = typer.Option(None, "--max-words", help="Maximum word count"),
+ linked_from: str | None = typer.Option(None, "--linked-from", help="Only notes linked FROM this note ID"),
+ linked_to: str | None = typer.Option(None, "--linked-to", help="Only notes that link TO this note ID"),
+ min_inbound: int | None = typer.Option(None, "--min-inbound", help="Minimum inbound link count"),
+ has_backlinks: bool = typer.Option(False, "--has-backlinks", help="Only notes with backlinks"),
+ include_body: bool = typer.Option(False, "--include-body", help="Include full note body (auto-enabled with --json)"),
+ no_body: bool = typer.Option(False, "--no-body", help="Disable auto body inclusion in JSON mode"),
+ limit: int = typer.Option(20, "--limit", "-l", help="Max results"),
+ offset: int = typer.Option(0, "--offset", help="Offset for pagination"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Full-text search across all notes."""
+ from hyperresearch.core.vault import Vault, VaultError
+ from hyperresearch.search.filters import SearchFilters
+ from hyperresearch.search.fts import search_fts
+
+ 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()
+
+ filters = SearchFilters(
+ tags=tag or None,
+ status=status,
+ note_type=note_type,
+ parent=parent,
+ after=after,
+ before=before,
+ path_glob=path_glob,
+ min_words=min_words,
+ max_words=max_words,
+ linked_from=linked_from,
+ linked_to=linked_to,
+ min_inbound=min_inbound,
+ has_backlinks=has_backlinks or None,
+ )
+
+ ranking = {
+ "title_weight": vault.config.search_title_weight,
+ "body_weight": vault.config.search_body_weight,
+ "tags_weight": vault.config.search_tags_weight,
+ "aliases_weight": vault.config.search_aliases_weight,
+ "boost_evergreen": vault.config.search_boost_evergreen,
+ "penalize_deprecated": vault.config.search_penalize_deprecated,
+ "penalize_stale": vault.config.search_penalize_stale,
+ }
+ results = search_fts(vault.db, query, filters=filters, limit=limit, offset=offset, ranking=ranking)
+
+ # Auto-include body in JSON mode (agents almost always need it)
+ want_body = include_body or (json_output and not no_body)
+ if want_body and results:
+ for r in results:
+ row = vault.db.execute(
+ "SELECT body FROM note_content WHERE note_id = ?", (r["id"],)
+ ).fetchone()
+ r["body"] = row["body"] if row else ""
+
+ if json_output:
+ output(
+ success(
+ {"query": query, "results": results, "total": len(results)},
+ count=len(results),
+ vault=str(vault.root),
+ ),
+ json_mode=True,
+ )
+ else:
+ if not results:
+ console.print("[dim]No results found.[/]")
+ return
+ for r in results:
+ tags_str = ", ".join(r.get("tags", []))
+ console.print(
+ f" [cyan]{r['id']}[/] [bold]{r['title']}[/] "
+ f"[dim]({r['status']})[/] [green]{tags_str}[/]"
+ )
+ if r.get("snippet"):
+ console.print(f" [dim]{r['snippet'][:200]}[/]")
+ console.print()
diff --git a/src/hyperresearch/cli/serve.py b/src/hyperresearch/cli/serve.py
new file mode 100644
index 0000000..f7a98bb
--- /dev/null
+++ b/src/hyperresearch/cli/serve.py
@@ -0,0 +1,26 @@
+"""Serve CLI command — browse vault in a web browser."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console
+
+
+def serve(
+ port: int = typer.Option(8080, "--port", "-p", help="Port to serve on"),
+ open_browser: bool = typer.Option(False, "--open", "-o", help="Open browser automatically"),
+) -> None:
+ """Start a web server to browse the vault."""
+ from hyperresearch.core.vault import Vault, VaultError
+
+ try:
+ vault = Vault.discover()
+ except VaultError as e:
+ console.print(f"[red]Error:[/] {e}")
+ raise typer.Exit(1)
+
+ vault.auto_sync()
+
+ from hyperresearch.serve.server import run_server
+ run_server(vault, port=port, open_browser=open_browser)
diff --git a/src/hyperresearch/cli/tag.py b/src/hyperresearch/cli/tag.py
new file mode 100644
index 0000000..31652d9
--- /dev/null
+++ b/src/hyperresearch/cli/tag.py
@@ -0,0 +1,121 @@
+"""Tag management CLI — list, alias, suggest merges, clean."""
+
+from __future__ import annotations
+
+from difflib import SequenceMatcher
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import success
+
+app = typer.Typer()
+
+
+def tag_list(
+ min_count: int = typer.Option(1, "--min", "-m", help="Only show tags with N+ notes"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """List all tags with note counts."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+ rows = vault.db.execute(
+ "SELECT tag, COUNT(*) as count FROM tags GROUP BY tag HAVING count >= ? ORDER BY count DESC",
+ (min_count,),
+ ).fetchall()
+ tags = [{"tag": r["tag"], "count": r["count"]} for r in rows]
+
+ if json_output:
+ output(success(tags, count=len(tags), vault=str(vault.root)), json_mode=True)
+ else:
+ from rich.table import Table
+
+ table = Table(title="Tags", show_header=True, header_style="bold")
+ table.add_column("Tag", style="green")
+ table.add_column("Notes", justify="right")
+ for t in tags:
+ table.add_row(t["tag"], str(t["count"]))
+ console.print(table)
+
+
+def tag_alias(
+ from_tag: str = typer.Argument(..., help="Tag to alias (the variant)"),
+ to_tag: str = typer.Argument(..., help="Canonical tag to map to"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Create a tag alias. Notes with the variant tag will be indexed under the canonical tag."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.db.execute(
+ "INSERT OR REPLACE INTO tag_aliases (alias, canonical) VALUES (?, ?)",
+ (from_tag.lower(), to_tag.lower()),
+ )
+ vault.db.commit()
+
+ if json_output:
+ output(success({"alias": from_tag, "canonical": to_tag}, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Alias:[/] {from_tag} -> {to_tag}")
+ console.print("[dim]Run 'hyperresearch sync --force' to apply.[/]")
+
+
+def tag_suggest(
+ threshold: float = typer.Option(0.7, "--threshold", help="Similarity threshold"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Suggest tag merges based on string similarity."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute(
+ "SELECT tag, COUNT(*) as count FROM tags GROUP BY tag ORDER BY count DESC"
+ ).fetchall()
+ tags = [(r["tag"], r["count"]) for r in rows]
+
+ # Find similar tag pairs
+ suggestions = []
+ popular = [t for t in tags if t[1] >= 3]
+ singletons = [t for t in tags if t[1] == 1]
+
+ for stag, _scount in singletons:
+ for ptag, pcount in popular:
+ sim = SequenceMatcher(None, stag, ptag).ratio()
+ if sim >= threshold and stag != ptag:
+ suggestions.append({
+ "singleton": stag,
+ "suggested_canonical": ptag,
+ "similarity": round(sim, 2),
+ "canonical_count": pcount,
+ })
+ break # Best match
+
+ # Also catch simple plurals
+ tag_set = {t[0] for t in tags}
+ for stag, _sc in singletons:
+ if stag.endswith("s") and stag[:-1] in tag_set and stag not in [s["singleton"] for s in suggestions]:
+ suggestions.append({"singleton": stag, "suggested_canonical": stag[:-1],
+ "similarity": 0.95, "canonical_count": next((c for t, c in tags if t == stag[:-1]), 0)})
+
+ suggestions.sort(key=lambda s: s["similarity"], reverse=True)
+
+ if json_output:
+ output(success(suggestions, count=len(suggestions), vault=str(vault.root)), json_mode=True)
+ else:
+ if not suggestions:
+ console.print("[dim]No merge suggestions found.[/]")
+ return
+ console.print(f"[bold]Suggested merges ({len(suggestions)}):[/]\n")
+ for s in suggestions[:30]:
+ console.print(
+ f" {s['singleton']:30s} -> {s['suggested_canonical']:20s} "
+ f"({s['similarity']:.0%} similar, {s['canonical_count']} notes)"
+ )
+ console.print("\n[dim]Apply with: hyperresearch tag alias <from> <to>[/]")
diff --git a/src/hyperresearch/cli/template.py b/src/hyperresearch/cli/template.py
new file mode 100644
index 0000000..bd8a0db
--- /dev/null
+++ b/src/hyperresearch/cli/template.py
@@ -0,0 +1,58 @@
+"""Template CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import success
+
+app = typer.Typer()
+
+
+def template_list(
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """List available note templates."""
+ from hyperresearch.core.templates import list_templates
+ from hyperresearch.core.vault import Vault, VaultError
+
+ try:
+ vault = Vault.discover()
+ templates = list_templates(vault.templates_dir)
+ except VaultError:
+ templates = list_templates()
+
+ if json_output:
+ output(success(templates, count=len(templates)), json_mode=True)
+ else:
+ from rich.table import Table
+
+ table = Table(title="Templates", show_header=True, header_style="bold")
+ table.add_column("Name", style="cyan")
+ table.add_column("Source", style="dim")
+ for t in templates:
+ table.add_row(t["name"], t["source"])
+ console.print(table)
+
+
+def template_show(
+ name: str = typer.Argument(..., help="Template name"),
+) -> None:
+ """Preview a template."""
+ from hyperresearch.core.templates import get_template
+ from hyperresearch.core.vault import Vault, VaultError
+
+ try:
+ vault = Vault.discover()
+ tpl = get_template(name, vault.templates_dir)
+ except VaultError:
+ tpl = get_template(name)
+
+ if not tpl:
+ console.print(f"[red]Template not found:[/] {name}")
+ raise typer.Exit(1)
+
+ console.print(tpl)
diff --git a/src/hyperresearch/cli/topic.py b/src/hyperresearch/cli/topic.py
new file mode 100644
index 0000000..56dd683
--- /dev/null
+++ b/src/hyperresearch/cli/topic.py
@@ -0,0 +1,163 @@
+"""Topic tree CLI commands — hierarchical parent navigation."""
+
+from __future__ import annotations
+
+import typer
+
+from hyperresearch.cli._output import console, output
+from hyperresearch.models.output import success
+
+app = typer.Typer()
+
+
+def topic_tree(
+ depth: int = typer.Option(0, "--depth", "-d", help="Max depth (0=unlimited)"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show the full topic hierarchy as a tree."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute(
+ "SELECT parent, COUNT(*) as count FROM notes "
+ "WHERE parent IS NOT NULL AND type NOT IN ('index') "
+ "GROUP BY parent ORDER BY parent"
+ ).fetchall()
+
+ # Collect all unique topic paths and their counts
+ topics = {}
+ for row in rows:
+ path = row["parent"]
+ topics[path] = row["count"]
+ # Add ancestor paths with 0 count if missing
+ parts = path.split("/")
+ for i in range(1, len(parts)):
+ ancestor = "/".join(parts[:i])
+ if ancestor not in topics:
+ topics[ancestor] = 0
+
+ if json_output:
+ data = [{"topic": k, "direct_notes": v} for k, v in sorted(topics.items())]
+ output(success(data, count=len(data), vault=str(vault.root)), json_mode=True)
+ else:
+ if not topics:
+ console.print("[dim]No topics found. Set 'parent' in note frontmatter.[/]")
+ return
+
+ from rich.tree import Tree
+
+ root = Tree("[bold]Topics[/]")
+ _build_rich_tree(root, topics, depth)
+ console.print(root)
+
+
+def _build_rich_tree(parent_node, topics: dict, max_depth: int, prefix: str = "", current_depth: int = 0):
+ """Recursively build a Rich tree from topic paths."""
+ if max_depth > 0 and current_depth >= max_depth:
+ return
+
+ # Find direct children at this level
+ children: dict[str, int] = {}
+ for path, count in sorted(topics.items()):
+ if prefix:
+ if not path.startswith(prefix + "/"):
+ continue
+ remainder = path[len(prefix) + 1:]
+ else:
+ remainder = path
+
+ if "/" not in remainder:
+ children[remainder] = count
+
+ for child_name, count in sorted(children.items()):
+ full_path = f"{prefix}/{child_name}" if prefix else child_name
+ # Count all notes under this subtree
+ subtree_count = sum(v for k, v in topics.items() if k == full_path or k.startswith(full_path + "/"))
+ label = f"[cyan]{child_name}[/]"
+ if count > 0:
+ label += f" ({count} notes)"
+ if subtree_count > count:
+ label += f" [dim]({subtree_count} total)[/]"
+ child_node = parent_node.add(label)
+ _build_rich_tree(child_node, topics, max_depth, full_path, current_depth + 1)
+
+
+def topic_list(
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Flat list of all topics with note counts."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ rows = vault.db.execute(
+ "SELECT parent, COUNT(*) as count FROM notes "
+ "WHERE parent IS NOT NULL AND type NOT IN ('index') "
+ "GROUP BY parent ORDER BY count DESC"
+ ).fetchall()
+
+ topics = [{"topic": r["parent"], "count": r["count"]} for r in rows]
+
+ if json_output:
+ output(success(topics, count=len(topics), vault=str(vault.root)), json_mode=True)
+ else:
+ from rich.table import Table
+
+ table = Table(title="Topics", show_header=True, header_style="bold")
+ table.add_column("Topic", style="cyan")
+ table.add_column("Notes", justify="right")
+ for t in topics:
+ table.add_row(t["topic"], str(t["count"]))
+ console.print(table)
+
+
+def topic_show(
+ topic: str = typer.Argument(..., help="Topic path (e.g. ml/deep-learning)"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Show all notes under a topic (including subtopics)."""
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ vault.auto_sync()
+
+ # Match exact and subtopics
+ rows = vault.db.execute(
+ """SELECT n.id, n.title, n.parent, n.status, n.word_count, n.summary,
+ (SELECT GROUP_CONCAT(t.tag, ',') FROM tags t WHERE t.note_id = n.id) as tag_list
+ FROM notes n
+ WHERE (n.parent = ? OR n.parent LIKE ?)
+ AND n.type NOT IN ('index')
+ ORDER BY n.parent, n.title""",
+ (topic, topic + "/%"),
+ ).fetchall()
+
+ notes = []
+ for row in rows:
+ tag_list = row["tag_list"].split(",") if row["tag_list"] else []
+ notes.append({
+ "id": row["id"],
+ "title": row["title"],
+ "parent": row["parent"],
+ "status": row["status"],
+ "tags": tag_list,
+ "word_count": row["word_count"],
+ "summary": row["summary"],
+ })
+
+ if json_output:
+ output(success({"topic": topic, "notes": notes}, count=len(notes), vault=str(vault.root)), json_mode=True)
+ else:
+ if not notes:
+ console.print(f"[dim]No notes under topic '{topic}'[/]")
+ return
+ console.print(f"[bold]Topic: {topic}[/] ({len(notes)} notes)\n")
+ for n in notes:
+ summary = f" — {n['summary']}" if n["summary"] else ""
+ console.print(f" [cyan]{n['id']}[/] {n['title']}{summary} [dim]`{n['status']}`[/]")
diff --git a/src/hyperresearch/cli/watch.py b/src/hyperresearch/cli/watch.py
new file mode 100644
index 0000000..9c3bf86
--- /dev/null
+++ b/src/hyperresearch/cli/watch.py
@@ -0,0 +1,113 @@
+"""Watch mode — auto-sync on file changes."""
+
+from __future__ import annotations
+
+import time
+
+import typer
+
+from hyperresearch.cli._output import console
+
+
+def watch(
+ rebuild_index: bool = typer.Option(False, "--rebuild-index", "-i", help="Rebuild indexes after sync"),
+ run_lint: bool = typer.Option(False, "--lint", "-l", help="Run lint after sync"),
+) -> None:
+ """Watch for file changes and auto-sync."""
+ try:
+ from watchdog.events import FileSystemEvent, FileSystemEventHandler
+ from watchdog.observers import Observer
+ except ImportError:
+ console.print("[red]Watch mode requires: pip install hyperresearch[watch][/]")
+ raise typer.Exit(1)
+
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+ from hyperresearch.core.vault import Vault
+
+ vault = Vault.discover()
+ console.print(f"[bold]Watching:[/] {vault.root}")
+ console.print("[dim]Press Ctrl+C to stop.[/]\n")
+
+ class DebouncedHandler(FileSystemEventHandler):
+ def __init__(self):
+ self._pending = False
+ self._last_event = 0.0
+
+ def on_any_event(self, event: FileSystemEvent):
+ if not event.src_path.endswith(".md"):
+ return
+ # Skip .hyperresearch directory
+ if ".hyperresearch" in event.src_path:
+ return
+ self._pending = True
+ self._last_event = time.monotonic()
+
+ def check_and_sync(self) -> bool:
+ if not self._pending:
+ return False
+ # Debounce: wait 500ms after last event
+ if time.monotonic() - self._last_event < 0.5:
+ return False
+ self._pending = False
+
+ try:
+ plan = compute_sync_plan(vault)
+ if plan.to_add or plan.to_update or plan.to_delete:
+ result = execute_sync(vault, plan)
+ console.print(
+ f"[green]Synced:[/] +{result.added} ~{result.updated} "
+ f"-{result.deleted} ({result.duration_ms:.0f}ms)"
+ )
+ for err in result.errors:
+ console.print(f" [red]Error:[/] {err['path']}: {err['error']}")
+
+ if rebuild_index:
+ from hyperresearch.indexgen.generator import IndexGenerator
+ gen = IndexGenerator(vault)
+ built = gen.build_all()
+ # Re-sync to index the index pages
+ plan2 = compute_sync_plan(vault)
+ if plan2.to_add or plan2.to_update:
+ execute_sync(vault, plan2)
+ console.print(f" [dim]Rebuilt {len(built)} indexes[/]")
+
+ if run_lint:
+ _quick_lint(vault)
+
+ return True
+ except Exception as e:
+ console.print(f"[red]Sync error:[/] {e}")
+ return False
+
+ handler = DebouncedHandler()
+ observer = Observer()
+ observer.schedule(handler, str(vault.research_dir), recursive=True)
+ observer.start()
+
+ try:
+ while True:
+ handler.check_and_sync()
+ time.sleep(0.2)
+ except KeyboardInterrupt:
+ observer.stop()
+ console.print("\n[dim]Stopped watching.[/]")
+ observer.join()
+
+
+def _quick_lint(vault) -> None:
+ """Run a quick lint and print summary."""
+ conn = vault.db
+ broken = conn.execute("SELECT COUNT(*) as c FROM links WHERE target_id IS NULL").fetchone()["c"]
+ orphans = conn.execute("""
+ SELECT COUNT(*) as c FROM notes n
+ WHERE n.type NOT IN ('index', 'raw')
+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)
+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)
+ """).fetchone()["c"]
+ if broken or orphans:
+ parts = []
+ if broken:
+ parts.append(f"{broken} broken links")
+ if orphans:
+ parts.append(f"{orphans} orphans")
+ console.print(f" [yellow]Lint: {', '.join(parts)}[/]")
diff --git a/src/hyperresearch/core/__init__.py b/src/hyperresearch/core/__init__.py
new file mode 100644
index 0000000..4bbde6c
--- /dev/null
+++ b/src/hyperresearch/core/__init__.py
@@ -0,0 +1 @@
+"""Core vault operations."""
diff --git a/src/hyperresearch/core/agent_docs.py b/src/hyperresearch/core/agent_docs.py
new file mode 100644
index 0000000..f582f18
--- /dev/null
+++ b/src/hyperresearch/core/agent_docs.py
@@ -0,0 +1,158 @@
+"""Agent documentation integration — inject hyperresearch docs into agent config files.
+
+Supports: CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md
+By default on init, only creates CLAUDE.md. Others created via --agents flags
+or if the file already exists in the repo.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+HYPERRESEARCH_SECTION_MARKER = "<!-- hyperresearch:start -->"
+HYPERRESEARCH_SECTION_END = "<!-- hyperresearch:end -->"
+
+HYPERRESEARCH_BLURB = """\
+
+{marker}
+## Research Base (hyperresearch)
+
+This project uses hyperresearch as an agent-driven research knowledge base. The `research/` directory contains markdown notes collected from web sources and original research. Append `--json` to any command for structured output.
+
+### Search and read
+
+```bash
+hyperresearch search "query" --json # Full-text search
+hyperresearch search "query" --tag ml --json # Filter by tag, status, date, parent
+hyperresearch search "query" --include-body --json # Include full note bodies in results
+hyperresearch note show <id> --json # Read a note
+hyperresearch note show <id1> <id2> <id3> --json # Read multiple notes at once
+hyperresearch note list --json # List all notes with summaries
+```
+
+### Collect research
+
+When you find useful information via web search or browsing, save it as a note:
+
+```bash
+hyperresearch note new "Title" --tag t1 --body-file /tmp/content.md --source "https://..." --summary "One-liner" --json
+hyperresearch note update <id> --status evergreen --add-tag ml --summary "Updated" --json
+```
+
+**Always check the research base BEFORE searching the web** — the answer may already be here.
+
+### Knowledge graph and maintenance
+
+```bash
+hyperresearch graph backlinks <id> --json # What links TO this note
+hyperresearch graph hubs --json # Most linked-to notes
+hyperresearch graph broken --json # Broken [[links]]
+hyperresearch lint --json # Health check
+hyperresearch repair --json # Full rebuild + fix broken links + promote notes
+hyperresearch status --json # Vault overview
+```
+
+### Note quality requirements
+
+Every note MUST have:
+- At least one tag (`--tag`). REUSE existing tags from `hyperresearch tags -j` -- do not invent new ones unless necessary.
+- A summary (`--summary`). One sentence, under 120 characters.
+- A body with meaningful content (50+ words).
+- A source URL (`--source`) when the content comes from the web.
+- Use `--body-file` instead of `--body` to avoid shell escaping issues.
+
+Run `hyperresearch lint -j` to check quality, `hyperresearch repair -j` to auto-fix.
+
+### Key conventions
+
+- Notes live in `research/notes/` as markdown with YAML frontmatter
+- Link between notes with `[[note-id]]` syntax
+- After editing .md files directly, run `hyperresearch sync` to update the index
+- Statuses: draft -> review -> evergreen -> stale -> deprecated -> archive
+- Run `hyperresearch --help` for the full command list
+{end_marker}
+"""
+
+# Which files each agent flag creates
+AGENT_FILES = {
+ "claude": "CLAUDE.md",
+ "agents": "AGENTS.md",
+ "gemini": "GEMINI.md",
+ "copilot": ".github/copilot-instructions.md",
+}
+
+
+def inject_agent_docs(
+ vault_root: Path,
+ agents: list[str] | None = None,
+) -> list[str]:
+ """Inject hyperresearch docs into agent config files.
+
+ Args:
+ vault_root: The repo root.
+ agents: Which agent files to create. Default: ["claude"].
+ Options: "claude", "agents", "gemini", "copilot".
+ If a file already exists, it's always updated regardless of this list.
+ """
+ if agents is None:
+ agents = ["claude"]
+
+ blurb = HYPERRESEARCH_BLURB.format(marker=HYPERRESEARCH_SECTION_MARKER, end_marker=HYPERRESEARCH_SECTION_END)
+ modified = []
+
+ # Determine which files to handle
+ files_to_inject: list[tuple[Path, str]] = []
+
+ # CLAUDE.md
+ if "claude" in agents or (vault_root / "CLAUDE.md").exists():
+ files_to_inject.append((vault_root / "CLAUDE.md", "CLAUDE.md"))
+
+ # AGENTS.md — prefer uppercase, respect existing lowercase
+ if "agents" in agents or (vault_root / "AGENTS.md").exists() or (vault_root / "agents.md").exists():
+ if (vault_root / "agents.md").exists() and not (vault_root / "AGENTS.md").exists():
+ files_to_inject.append((vault_root / "agents.md", "agents.md"))
+ else:
+ files_to_inject.append((vault_root / "AGENTS.md", "AGENTS.md"))
+
+ # GEMINI.md
+ if "gemini" in agents or (vault_root / "GEMINI.md").exists():
+ files_to_inject.append((vault_root / "GEMINI.md", "GEMINI.md"))
+
+ # .github/copilot-instructions.md
+ copilot_path = vault_root / ".github" / "copilot-instructions.md"
+ if "copilot" in agents or copilot_path.exists():
+ files_to_inject.append((copilot_path, ".github/copilot-instructions.md"))
+
+ for filepath, filename in files_to_inject:
+ result = _inject_into_file(filepath, blurb, filename)
+ if result:
+ modified.append(result)
+
+ return modified
+
+
+def _inject_into_file(filepath: Path, blurb: str, filename: str) -> str | None:
+ """Inject the hyperresearch blurb into a single file. Returns action taken or None."""
+ if filepath.exists():
+ content = filepath.read_text(encoding="utf-8-sig")
+
+ if HYPERRESEARCH_SECTION_MARKER in content:
+ pattern = re.compile(
+ re.escape(HYPERRESEARCH_SECTION_MARKER) + r".*?" + re.escape(HYPERRESEARCH_SECTION_END),
+ re.DOTALL,
+ )
+ new_content = pattern.sub(blurb.strip(), content)
+ if new_content != content:
+ filepath.write_text(new_content, encoding="utf-8")
+ return f"{filename} (updated)"
+ return None
+ else:
+ separator = "\n\n" if not content.endswith("\n") else "\n"
+ filepath.write_text(content + separator + blurb.strip() + "\n", encoding="utf-8")
+ return f"{filename} (appended)"
+ else:
+ filepath.parent.mkdir(parents=True, exist_ok=True)
+ header = f"# {filepath.stem}\n"
+ filepath.write_text(header + blurb.strip() + "\n", encoding="utf-8")
+ return f"{filename} (created)"
diff --git a/src/hyperresearch/core/config.py b/src/hyperresearch/core/config.py
new file mode 100644
index 0000000..cdcaf14
--- /dev/null
+++ b/src/hyperresearch/core/config.py
@@ -0,0 +1,99 @@
+"""Vault configuration management (.hyperresearch/config.toml)."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class VaultConfig:
+ name: str = "Research Base"
+ default_status: str = "draft"
+ research_dir: str = "research"
+
+ # Search ranking
+ search_title_weight: float = 10.0
+ search_body_weight: float = 1.0
+ search_tags_weight: float = 5.0
+ search_aliases_weight: float = 3.0
+ search_boost_evergreen: float = 1.5
+ search_penalize_deprecated: float = 0.3
+ search_penalize_stale: float = 0.7
+
+ # Sync
+ auto_sync: bool = True
+ exclude_patterns: list[str] = field(
+ default_factory=lambda: [
+ ".hyperresearch/*", "exports/*", ".git/*", ".venv/*", "node_modules/*", "templates/*",
+ "CLAUDE.md", "AGENTS.md", "agents.md", "GEMINI.md", "README.md", "CHANGELOG.md",
+ ]
+ )
+
+ # Index
+ auto_build_index: bool = True
+ index_pages: list[str] = field(
+ default_factory=lambda: ["_index", "_tags", "_recent", "_orphans", "_stats"]
+ )
+
+ @classmethod
+ def load(cls, config_path: Path) -> VaultConfig:
+ if not config_path.exists():
+ return cls()
+ with open(config_path, "rb") as f:
+ data = tomllib.load(f)
+
+ vault = data.get("vault", {})
+ sync = data.get("sync", {})
+ index = data.get("index", {})
+ search = data.get("search", {})
+
+ return cls(
+ name=vault.get("name", cls.name),
+ default_status=vault.get("default_status", cls.default_status),
+ research_dir=vault.get("research_dir", cls.research_dir),
+ search_title_weight=search.get("title_weight", cls.search_title_weight),
+ search_body_weight=search.get("body_weight", cls.search_body_weight),
+ search_tags_weight=search.get("tags_weight", cls.search_tags_weight),
+ search_aliases_weight=search.get("aliases_weight", cls.search_aliases_weight),
+ search_boost_evergreen=search.get("boost_evergreen", cls.search_boost_evergreen),
+ search_penalize_deprecated=search.get("penalize_deprecated", cls.search_penalize_deprecated),
+ search_penalize_stale=search.get("penalize_stale", cls.search_penalize_stale),
+ auto_sync=sync.get("auto_sync", cls.auto_sync),
+ exclude_patterns=sync.get("exclude_patterns", cls().exclude_patterns),
+ auto_build_index=index.get("auto_build", cls.auto_build_index),
+ index_pages=index.get("pages", cls().index_pages),
+ )
+
+ @staticmethod
+ def _toml_array(items: list[str]) -> str:
+ quoted = ", ".join(f'"{item}"' for item in items)
+ return f"[{quoted}]"
+
+ def save(self, config_path: Path) -> None:
+ lines = [
+ "[vault]",
+ f'name = "{self.name}"',
+ f'default_status = "{self.default_status}"',
+ f'research_dir = "{self.research_dir}"',
+ "",
+ "[search]",
+ f"title_weight = {self.search_title_weight}",
+ f"body_weight = {self.search_body_weight}",
+ f"tags_weight = {self.search_tags_weight}",
+ f"aliases_weight = {self.search_aliases_weight}",
+ f"boost_evergreen = {self.search_boost_evergreen}",
+ f"penalize_deprecated = {self.search_penalize_deprecated}",
+ f"penalize_stale = {self.search_penalize_stale}",
+ "",
+ "[sync]",
+ f"auto_sync = {'true' if self.auto_sync else 'false'}",
+ f"exclude_patterns = {self._toml_array(self.exclude_patterns)}",
+ "",
+ "[index]",
+ f"auto_build = {'true' if self.auto_build_index else 'false'}",
+ f"pages = {self._toml_array(self.index_pages)}",
+ ]
+ config_path.parent.mkdir(parents=True, exist_ok=True)
+ config_path.write_text("\n".join(lines) + "\n")
diff --git a/src/hyperresearch/core/db.py b/src/hyperresearch/core/db.py
new file mode 100644
index 0000000..e122dd4
--- /dev/null
+++ b/src/hyperresearch/core/db.py
@@ -0,0 +1,138 @@
+"""SQLite database management — schema, connection, migrations."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+SCHEMA_VERSION = 2
+
+SCHEMA_SQL = """
+PRAGMA journal_mode=WAL;
+PRAGMA foreign_keys=ON;
+
+CREATE TABLE IF NOT EXISTS _meta (
+ key TEXT PRIMARY KEY,
+ value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS notes (
+ id TEXT PRIMARY KEY,
+ title TEXT NOT NULL,
+ path TEXT NOT NULL UNIQUE,
+ status TEXT NOT NULL DEFAULT 'draft'
+ CHECK (status IN ('draft','review','evergreen','stale','deprecated','archive')),
+ type TEXT NOT NULL DEFAULT 'note'
+ CHECK (type IN ('note','raw','index','moc')),
+ source TEXT,
+ parent TEXT,
+ confidence REAL,
+ superseded_by TEXT,
+ deprecated INTEGER NOT NULL DEFAULT 0,
+ reviewed TEXT,
+ expires TEXT,
+ llm_compiled INTEGER NOT NULL DEFAULT 0,
+ llm_model TEXT,
+ compile_source TEXT,
+ word_count INTEGER NOT NULL DEFAULT 0,
+ summary TEXT,
+ created TEXT NOT NULL,
+ updated TEXT,
+ file_mtime REAL NOT NULL,
+ content_hash TEXT NOT NULL,
+ synced_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_notes_status ON notes(status);
+CREATE INDEX IF NOT EXISTS idx_notes_type ON notes(type);
+CREATE INDEX IF NOT EXISTS idx_notes_parent ON notes(parent);
+CREATE INDEX IF NOT EXISTS idx_notes_created ON notes(created);
+CREATE INDEX IF NOT EXISTS idx_notes_updated ON notes(updated);
+CREATE INDEX IF NOT EXISTS idx_notes_word_count ON notes(word_count);
+CREATE INDEX IF NOT EXISTS idx_notes_status_type ON notes(status, type);
+CREATE INDEX IF NOT EXISTS idx_notes_parent_status ON notes(parent, status);
+
+CREATE TABLE IF NOT EXISTS note_content (
+ note_id TEXT PRIMARY KEY REFERENCES notes(id) ON DELETE CASCADE,
+ body TEXT NOT NULL,
+ body_plain TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tags (
+ note_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+ tag TEXT NOT NULL,
+ PRIMARY KEY (note_id, tag)
+);
+
+CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag);
+
+CREATE TABLE IF NOT EXISTS aliases (
+ note_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+ alias TEXT NOT NULL,
+ PRIMARY KEY (note_id, alias)
+);
+
+CREATE INDEX IF NOT EXISTS idx_aliases_alias ON aliases(alias COLLATE NOCASE);
+
+CREATE TABLE IF NOT EXISTS links (
+ source_id TEXT NOT NULL,
+ target_ref TEXT NOT NULL,
+ target_id TEXT,
+ line_number INTEGER NOT NULL DEFAULT 0,
+ context TEXT,
+ PRIMARY KEY (source_id, target_ref, line_number)
+);
+
+CREATE INDEX IF NOT EXISTS idx_links_target ON links(target_id);
+CREATE INDEX IF NOT EXISTS idx_links_source ON links(source_id);
+
+CREATE TABLE IF NOT EXISTS embeddings (
+ note_id TEXT PRIMARY KEY REFERENCES notes(id) ON DELETE CASCADE,
+ model TEXT NOT NULL,
+ dimensions INTEGER NOT NULL,
+ vector BLOB NOT NULL,
+ created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tag_aliases (
+ alias TEXT PRIMARY KEY,
+ canonical TEXT NOT NULL
+);
+
+"""
+
+FTS_SQL = """
+CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
+ id UNINDEXED,
+ title,
+ body_plain,
+ tags,
+ aliases,
+ tokenize='porter unicode61'
+);
+"""
+
+
+def get_connection(db_path: Path) -> sqlite3.Connection:
+ """Open a SQLite connection with WAL mode and FK enforcement."""
+ db_path.parent.mkdir(parents=True, exist_ok=True)
+ conn = sqlite3.connect(str(db_path))
+ conn.row_factory = sqlite3.Row
+ conn.execute("PRAGMA journal_mode=WAL")
+ conn.execute("PRAGMA foreign_keys=ON")
+ return conn
+
+
+def init_schema(conn: sqlite3.Connection) -> None:
+ """Create all tables if they don't exist, then run pending migrations."""
+ conn.executescript(SCHEMA_SQL)
+ conn.executescript(FTS_SQL)
+ conn.execute(
+ "INSERT OR IGNORE INTO _meta (key, value) VALUES ('schema_version', ?)",
+ (str(SCHEMA_VERSION),),
+ )
+ conn.commit()
+
+ # Run any pending migrations
+ from hyperresearch.core.migrations import migrate
+ migrate(conn, SCHEMA_VERSION)
diff --git a/src/hyperresearch/core/enrich.py b/src/hyperresearch/core/enrich.py
new file mode 100644
index 0000000..87ba706
--- /dev/null
+++ b/src/hyperresearch/core/enrich.py
@@ -0,0 +1,70 @@
+"""Auto-enrichment: keyword-based tagging and first-line summary extraction."""
+
+from __future__ import annotations
+
+import re
+
+
+def auto_tag(body_plain: str, existing_tags: list[dict]) -> list[str]:
+ """Suggest tags for a note based on keyword matching against existing tag vocabulary.
+
+ Args:
+ body_plain: Stripped plain text of the note body.
+ existing_tags: List of {"tag": str, "count": int} from the vault.
+
+ Returns:
+ List of suggested tag strings (max 5).
+ """
+ if not body_plain or not existing_tags:
+ return []
+
+ body_lower = body_plain.lower()
+ words = set(body_lower.split())
+
+ scored = []
+ for entry in existing_tags:
+ tag = entry["tag"]
+ count = entry["count"]
+ # Check if tag (or hyphenated parts) appear in body
+ tag_words = set(tag.replace("-", " ").split())
+ matches = tag_words & words
+ if matches:
+ # Score: fraction of tag words found * log popularity
+ import math
+ frac = len(matches) / len(tag_words)
+ score = frac * (1 + math.log(max(count, 1)))
+ scored.append((tag, score))
+
+ scored.sort(key=lambda x: x[1], reverse=True)
+ return [tag for tag, _ in scored[:5]]
+
+
+def auto_summary(body: str) -> str | None:
+ """Extract a summary from the first meaningful line of the body.
+
+ Skips headings, blank lines, and very short lines. Truncates to 120 chars.
+ """
+ for line in body.split("\n"):
+ stripped = line.strip()
+ # Skip headings, blank lines, short lines, frontmatter markers
+ if not stripped:
+ continue
+ if stripped.startswith("#"):
+ continue
+ if stripped.startswith("---"):
+ continue
+ if stripped.startswith("*Stub"):
+ continue
+ if len(stripped) < 25:
+ continue
+ # Strip markdown formatting
+ clean = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", stripped)
+ clean = re.sub(r"\[\[([^\]|]+)(?:\|[^\]]+)?\]\]", r"\1", clean)
+ clean = re.sub(r"[*_`]", "", clean)
+ clean = clean.strip()
+ if len(clean) < 25:
+ continue
+ if len(clean) > 120:
+ return clean[:117] + "..."
+ return clean
+ return None
diff --git a/src/hyperresearch/core/frontmatter.py b/src/hyperresearch/core/frontmatter.py
new file mode 100644
index 0000000..50b68dc
--- /dev/null
+++ b/src/hyperresearch/core/frontmatter.py
@@ -0,0 +1,55 @@
+"""YAML frontmatter parsing and serialization."""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+
+from hyperresearch.models.note import NoteMeta
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n?", re.DOTALL)
+
+
+def parse_frontmatter(content: str) -> tuple[NoteMeta, str]:
+ """Parse YAML frontmatter from markdown content.
+
+ Returns (metadata, body) where body is the content after frontmatter.
+ """
+ match = FRONTMATTER_RE.match(content)
+ if not match:
+ return NoteMeta(title="Untitled"), content
+
+ yaml_str = match.group(1)
+ body = content[match.end():]
+
+ data = yaml.safe_load(yaml_str) or {}
+ if not isinstance(data, dict):
+ return NoteMeta(title="Untitled"), content
+
+ # Handle missing title gracefully
+ if "title" not in data:
+ data["title"] = "Untitled"
+
+ meta = NoteMeta.model_validate(data)
+ return meta, body
+
+
+def serialize_frontmatter(meta: NoteMeta) -> str:
+ """Serialize NoteMeta to YAML frontmatter string."""
+ data = meta.model_dump(mode="json", exclude_none=True, exclude_defaults=False)
+ # Remove empty lists
+ for key in ("tags", "aliases"):
+ if key in data and not data[key]:
+ del data[key]
+ # Remove empty id
+ if "id" in data and not data["id"]:
+ del data["id"]
+
+ yaml_str = yaml.dump(data, default_flow_style=False, sort_keys=False, allow_unicode=True)
+ return f"---\n{yaml_str}---\n"
+
+
+def render_note(meta: NoteMeta, body: str) -> str:
+ """Render a full markdown note with frontmatter + body."""
+ return serialize_frontmatter(meta) + "\n" + body
diff --git a/src/hyperresearch/core/migrations.py b/src/hyperresearch/core/migrations.py
new file mode 100644
index 0000000..1748f25
--- /dev/null
+++ b/src/hyperresearch/core/migrations.py
@@ -0,0 +1,46 @@
+"""Schema migration system for hyperresearch SQLite databases."""
+
+from __future__ import annotations
+
+import sqlite3
+
+# Each migration is a SQL script that upgrades from version N-1 to N.
+# Migrations MUST be idempotent (safe to re-run).
+MIGRATIONS: dict[int, str] = {
+ 2: """
+CREATE TABLE IF NOT EXISTS tag_aliases (
+ alias TEXT PRIMARY KEY,
+ canonical TEXT NOT NULL
+);
+""",
+}
+
+
+def get_schema_version(conn: sqlite3.Connection) -> int:
+ try:
+ row = conn.execute("SELECT value FROM _meta WHERE key = 'schema_version'").fetchone()
+ return int(row[0] if isinstance(row, tuple) else row["value"]) if row else 0
+ except sqlite3.OperationalError:
+ return 0
+
+
+def migrate(conn: sqlite3.Connection, target_version: int) -> list[int]:
+ """Run pending migrations. Returns list of versions applied."""
+ current = get_schema_version(conn)
+ if current >= target_version:
+ return []
+
+ applied = []
+ for version in range(current + 1, target_version + 1):
+ sql = MIGRATIONS.get(version)
+ if sql:
+ conn.executescript(sql)
+ conn.execute(
+ "INSERT OR REPLACE INTO _meta (key, value) VALUES ('schema_version', ?)",
+ (str(version),),
+ )
+ applied.append(version)
+
+ if applied:
+ conn.commit()
+ return applied
diff --git a/src/hyperresearch/core/note.py b/src/hyperresearch/core/note.py
new file mode 100644
index 0000000..e3fc684
--- /dev/null
+++ b/src/hyperresearch/core/note.py
@@ -0,0 +1,112 @@
+"""Note file operations — read, write, list from disk."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+from hyperresearch.core.frontmatter import parse_frontmatter, render_note
+from hyperresearch.core.patterns import CODE_BLOCK_RE, INLINE_CODE_RE, WIKI_LINK_RE
+from hyperresearch.models.note import Note, NoteMeta, slugify
+
+
+def read_note(file_path: Path, vault_root: Path) -> Note:
+ """Read a markdown file and parse into a Note."""
+ raw_bytes = file_path.read_bytes()
+ content_hash = hashlib.sha256(raw_bytes).hexdigest()
+ content = raw_bytes.decode("utf-8-sig") # Handles BOM
+ meta, body = parse_frontmatter(content)
+
+ rel_path = file_path.relative_to(vault_root).as_posix()
+
+ # Derive ID from filename if not set in frontmatter
+ if not meta.id:
+ meta.id = slugify(file_path.stem)
+
+ # Extract outgoing wiki links
+ cleaned = CODE_BLOCK_RE.sub("", body)
+ cleaned = INLINE_CODE_RE.sub("", cleaned)
+ raw_links = (m.group(1).strip().rstrip("\\") for m in WIKI_LINK_RE.finditer(cleaned))
+ outgoing = list(dict.fromkeys(
+ ref for ref in raw_links
+ if ref and not ref.startswith(("http://", "https://", "ftp://", "mailto:"))
+ ))
+
+ # Word count (simple split)
+ word_count = len(body.split())
+
+ return Note(
+ meta=meta,
+ body=body,
+ path=rel_path,
+ content_hash=content_hash,
+ word_count=word_count,
+ outgoing_links=outgoing,
+ )
+
+
+def write_note(
+ notes_dir: Path,
+ title: str,
+ body: str = "",
+ *,
+ note_id: str | None = None,
+ tags: list[str] | None = None,
+ status: str = "draft",
+ note_type: str = "note",
+ parent: str | None = None,
+ source: str | None = None,
+ summary: str | None = None,
+) -> Path:
+ """Create a new note file on disk. Returns the file path.
+
+ Args:
+ notes_dir: The directory to write into (e.g. vault.notes_dir).
+ """
+ nid = note_id or slugify(title)
+ meta = NoteMeta(
+ title=title,
+ id=nid,
+ tags=tags or [],
+ status=status,
+ type=note_type,
+ parent=parent,
+ source=source,
+ summary=summary,
+ created=datetime.now(UTC),
+ )
+
+ # Determine output path, avoid collisions
+ target_dir = notes_dir
+ if parent:
+ target_dir = target_dir / slugify(parent)
+ target_dir.mkdir(parents=True, exist_ok=True)
+
+ file_path = target_dir / f"{nid}.md"
+ counter = 2
+ while file_path.exists():
+ file_path = target_dir / f"{nid}-{counter}.md"
+ meta.id = f"{nid}-{counter}"
+ counter += 1
+
+ content = render_note(meta, body)
+ file_path.write_text(content, encoding="utf-8")
+ return file_path
+
+
+def strip_markdown(text: str) -> str:
+ """Strip markdown formatting to plain text for FTS indexing."""
+ text = CODE_BLOCK_RE.sub("", text)
+ text = INLINE_CODE_RE.sub("", text)
+ text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)
+ text = re.sub(r"\*{1,3}([^*]+)\*{1,3}", r"\1", text)
+ text = re.sub(r"_{1,3}([^_]+)_{1,3}", r"\1", text)
+ text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+ text = re.sub(r"\[\[([^\]|]+)\|([^\]]+)\]\]", r"\2", text)
+ text = re.sub(r"\[\[([^\]]+)\]\]", r"\1", text)
+ text = re.sub(r"!\[([^\]]*)\]\([^)]+\)", r"\1", text)
+ text = re.sub(r"<[^>]+>", "", text)
+ text = re.sub(r"\s+", " ", text)
+ return text.strip()
diff --git a/src/hyperresearch/core/patterns.py b/src/hyperresearch/core/patterns.py
new file mode 100644
index 0000000..bd28465
--- /dev/null
+++ b/src/hyperresearch/core/patterns.py
@@ -0,0 +1,12 @@
+"""Shared regex patterns for wiki-link parsing."""
+
+from __future__ import annotations
+
+import re
+
+# Match [[target]] and [[target|display text]]
+WIKI_LINK_RE = re.compile(r"\[\[([^\]|]+)(?:\|[^\]]+)?\]\]")
+
+# Code block patterns for stripping before link extraction
+CODE_BLOCK_RE = re.compile(r"```.*?```", re.DOTALL)
+INLINE_CODE_RE = re.compile(r"`[^`]+`")
diff --git a/src/hyperresearch/core/similarity.py b/src/hyperresearch/core/similarity.py
new file mode 100644
index 0000000..8b4982e
--- /dev/null
+++ b/src/hyperresearch/core/similarity.py
@@ -0,0 +1,20 @@
+"""Content similarity — shingle-based Jaccard for dedup and create-time checks."""
+
+from __future__ import annotations
+
+
+def shingle(text: str, n: int = 3) -> set[str]:
+ """Extract word-level n-grams (shingles) from text."""
+ words = text.lower().split()
+ if len(words) < n:
+ return {" ".join(words)} if words else set()
+ return {" ".join(words[i : i + n]) for i in range(len(words) - n + 1)}
+
+
+def jaccard(a: set, b: set) -> float:
+ """Jaccard similarity between two sets."""
+ if not a or not b:
+ return 0.0
+ intersection = len(a & b)
+ union = len(a | b)
+ return intersection / union if union else 0.0
diff --git a/src/hyperresearch/core/sync.py b/src/hyperresearch/core/sync.py
new file mode 100644
index 0000000..f5f7c5a
--- /dev/null
+++ b/src/hyperresearch/core/sync.py
@@ -0,0 +1,314 @@
+"""File-to-DB sync engine — the bridge between markdown files and SQLite."""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from hyperresearch.core.note import read_note, strip_markdown
+from hyperresearch.core.patterns import CODE_BLOCK_RE, INLINE_CODE_RE, WIKI_LINK_RE
+
+
+@dataclass
+class SyncPlan:
+ to_add: list[Path] = field(default_factory=list)
+ to_update: list[Path] = field(default_factory=list)
+ to_delete: list[str] = field(default_factory=list) # relative paths
+ unchanged: int = 0
+
+
+@dataclass
+class SyncResult:
+ added: int = 0
+ updated: int = 0
+ deleted: int = 0
+ unchanged: int = 0
+ errors: list[dict] = field(default_factory=list)
+ duration_ms: float = 0
+
+
+def _should_exclude(rel_path: str, exclude_parts: list[str]) -> bool:
+ """Fast exclusion check — match on first path component."""
+ first = rel_path.split("/", 1)[0]
+ return first in exclude_parts
+
+
+def compute_sync_plan(vault, force: bool = False) -> SyncPlan:
+ """Compare disk state against DB state. Returns a plan."""
+ plan = SyncPlan()
+
+ # Only scan inside the research directory (notes/, index/)
+ # This avoids walking .git/, .venv/, src/, etc. entirely
+ kb_dir = vault.research_dir
+ if not kb_dir.exists():
+ return plan
+
+ disk_files: dict[str, float] = {}
+ for md_file in kb_dir.rglob("*.md"):
+ rel = md_file.relative_to(vault.root).as_posix()
+ disk_files[rel] = md_file.stat().st_mtime
+
+ # Load DB state — only catch "table not found" on fresh vaults
+ db_state: dict[str, tuple[float, str]] = {}
+ try:
+ for row in vault.db.execute("SELECT path, file_mtime, content_hash FROM notes"):
+ db_state[row["path"]] = (row["file_mtime"], row["content_hash"])
+ except sqlite3.OperationalError:
+ # Table doesn't exist yet (fresh vault before schema init)
+ pass
+
+ for rel_path, mtime in disk_files.items():
+ full_path = vault.root / rel_path
+ if rel_path not in db_state:
+ plan.to_add.append(full_path)
+ elif force or abs(mtime - db_state[rel_path][0]) > 0.001:
+ # mtime differs — verify with content hash (raw bytes)
+ current_hash = hashlib.sha256(full_path.read_bytes()).hexdigest()
+ if force or current_hash != db_state[rel_path][1]:
+ plan.to_update.append(full_path)
+ else:
+ plan.unchanged += 1
+ else:
+ plan.unchanged += 1
+
+ for db_path in db_state:
+ if db_path not in disk_files:
+ plan.to_delete.append(db_path)
+
+ return plan
+
+
+def execute_sync(vault, plan: SyncPlan) -> SyncResult:
+ """Execute the sync plan within a single transaction for atomicity."""
+ result = SyncResult(unchanged=plan.unchanged)
+ start = time.monotonic()
+ now_iso = datetime.now(UTC).isoformat()
+
+ conn = vault.db
+ conn.execute("BEGIN IMMEDIATE")
+
+ changed_ids: set[str] = set()
+
+ try:
+ # Process deletes
+ for rel_path in plan.to_delete:
+ try:
+ row = conn.execute("SELECT id FROM notes WHERE path = ?", (rel_path,)).fetchone()
+ if row:
+ _delete_note_from_db(conn, row["id"])
+ changed_ids.add(row["id"])
+ result.deleted += 1
+ except Exception as e:
+ result.errors.append({"path": rel_path, "error": str(e)})
+
+ # Process adds
+ for file_path in plan.to_add:
+ try:
+ note = read_note(file_path, vault.root)
+ _upsert_note_to_db(conn, note, now_iso, file_mtime=file_path.stat().st_mtime)
+ changed_ids.add(note.meta.id)
+ result.added += 1
+ except Exception as e:
+ result.errors.append({"path": str(file_path), "error": str(e)})
+
+ # Process updates
+ for file_path in plan.to_update:
+ try:
+ note = read_note(file_path, vault.root)
+ _upsert_note_to_db(conn, note, now_iso, file_mtime=file_path.stat().st_mtime)
+ changed_ids.add(note.meta.id)
+ result.updated += 1
+ except Exception as e:
+ result.errors.append({"path": str(file_path), "error": str(e)})
+
+ # Resolve links — only for changed notes' outgoing + incoming
+ _resolve_links_incremental(conn, changed_ids)
+
+ # Record sync timestamp
+ conn.execute(
+ "INSERT OR REPLACE INTO _meta (key, value) VALUES ('last_sync', ?)",
+ (now_iso,),
+ )
+ conn.commit()
+ except Exception:
+ conn.rollback()
+ raise
+
+ result.duration_ms = (time.monotonic() - start) * 1000
+ return result
+
+
+def _upsert_note_to_db(conn, note, synced_at: str, file_mtime: float = 0) -> None:
+ """Insert or update a note and all related tables using proper UPSERT."""
+ meta = note.meta
+ created_iso = meta.created.isoformat() if meta.created else synced_at
+ updated_iso = meta.updated.isoformat() if meta.updated else None
+
+ reviewed_iso = meta.reviewed.isoformat() if meta.reviewed else None
+ expires_iso = meta.expires.isoformat() if meta.expires else None
+
+ # Use INSERT ... ON CONFLICT to avoid CASCADE deletes from INSERT OR REPLACE
+ conn.execute(
+ """
+ INSERT INTO notes
+ (id, title, path, status, type, source, parent, confidence,
+ superseded_by, deprecated, reviewed, expires,
+ llm_compiled, llm_model, compile_source, word_count, summary,
+ created, updated, file_mtime, content_hash, synced_at)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT(id) DO UPDATE SET
+ title=excluded.title, path=excluded.path, status=excluded.status,
+ type=excluded.type, source=excluded.source, parent=excluded.parent,
+ confidence=excluded.confidence,
+ superseded_by=excluded.superseded_by, deprecated=excluded.deprecated,
+ reviewed=excluded.reviewed, expires=excluded.expires,
+ llm_compiled=excluded.llm_compiled,
+ llm_model=excluded.llm_model, compile_source=excluded.compile_source,
+ word_count=excluded.word_count, summary=excluded.summary,
+ created=excluded.created, updated=excluded.updated,
+ file_mtime=excluded.file_mtime, content_hash=excluded.content_hash,
+ synced_at=excluded.synced_at
+ """,
+ (
+ meta.id, meta.title, note.path, meta.status, meta.type,
+ meta.source, meta.parent, meta.confidence,
+ meta.superseded_by, 1 if meta.deprecated else 0,
+ reviewed_iso, expires_iso,
+ 1 if meta.llm_compiled else 0, meta.llm_model, meta.compile_source,
+ note.word_count, meta.summary, created_iso, updated_iso,
+ file_mtime, note.content_hash, synced_at,
+ ),
+ )
+
+ # Update tags — resolve aliases before writing
+ conn.execute("DELETE FROM tags WHERE note_id = ?", (meta.id,))
+ alias_map = {}
+ try:
+ for row in conn.execute("SELECT alias, canonical FROM tag_aliases"):
+ alias_map[row["alias"]] = row["canonical"]
+ except Exception:
+ pass
+ for tag in meta.tags:
+ resolved = alias_map.get(tag, tag)
+ # Auto-normalize plurals: "transformers" -> "transformer" if singular exists
+ if resolved.endswith("s") and len(resolved) > 3:
+ singular = resolved[:-1]
+ if singular in alias_map.values() or conn.execute(
+ "SELECT 1 FROM tags WHERE tag = ? LIMIT 1", (singular,)
+ ).fetchone():
+ resolved = singular
+ conn.execute("INSERT OR IGNORE INTO tags (note_id, tag) VALUES (?, ?)", (meta.id, resolved))
+
+ # Update aliases
+ conn.execute("DELETE FROM aliases WHERE note_id = ?", (meta.id,))
+ for alias in meta.aliases:
+ conn.execute("INSERT INTO aliases (note_id, alias) VALUES (?, ?)", (meta.id, alias))
+
+ # Update content (UPSERT)
+ body_plain = strip_markdown(note.body)
+ conn.execute(
+ """
+ INSERT INTO note_content (note_id, body, body_plain) VALUES (?, ?, ?)
+ ON CONFLICT(note_id) DO UPDATE SET body=excluded.body, body_plain=excluded.body_plain
+ """,
+ (meta.id, note.body, body_plain),
+ )
+
+ # Update FTS — delete then insert (FTS5 doesn't support ON CONFLICT)
+ conn.execute("DELETE FROM notes_fts WHERE id = ?", (meta.id,))
+ conn.execute(
+ "INSERT INTO notes_fts (id, title, body_plain, tags, aliases) VALUES (?, ?, ?, ?, ?)",
+ (meta.id, meta.title, body_plain, " ".join(meta.tags), " ".join(meta.aliases)),
+ )
+
+ # Update links — extract from original body (not stripped)
+ conn.execute("DELETE FROM links WHERE source_id = ?", (meta.id,))
+ cleaned = CODE_BLOCK_RE.sub("", note.body)
+ cleaned = INLINE_CODE_RE.sub("", cleaned)
+ for line_num, line in enumerate(cleaned.split("\n"), 1):
+ for m in WIKI_LINK_RE.finditer(line):
+ target_ref = m.group(1).strip().rstrip("\\") # Strip trailing backslash (shell escaping artifact)
+ # Skip URLs — they're not note references
+ if target_ref.startswith(("http://", "https://", "ftp://", "mailto:")):
+ continue
+ if not target_ref:
+ continue
+ conn.execute(
+ "INSERT OR IGNORE INTO links (source_id, target_ref, line_number, context) "
+ "VALUES (?, ?, ?, ?)",
+ (meta.id, target_ref, line_num, line.strip()[:200]),
+ )
+
+
+def _delete_note_from_db(conn, note_id: str) -> None:
+ """Delete a note and all related data (CASCADE handles child tables)."""
+ conn.execute("DELETE FROM notes_fts WHERE id = ?", (note_id,))
+ conn.execute("DELETE FROM links WHERE source_id = ?", (note_id,))
+ conn.execute("DELETE FROM notes WHERE id = ?", (note_id,))
+
+
+def _resolve_links_incremental(conn, changed_ids: set[str]) -> None:
+ """Resolve links incrementally — only for links affected by changed notes.
+
+ This handles two cases:
+ 1. Outgoing links from changed notes need resolution
+ 2. Unresolved links from ANY note might now resolve to a newly added note
+ """
+ if not changed_ids:
+ return
+
+ # Re-resolve outgoing links from changed notes
+ placeholders = ",".join("?" for _ in changed_ids)
+ ids = list(changed_ids)
+
+ # Reset target_id for links from changed notes
+ conn.execute(
+ f"UPDATE links SET target_id = NULL WHERE source_id IN ({placeholders})", ids
+ )
+
+ # Also reset links that pointed TO deleted/changed notes (they may have moved)
+ conn.execute(
+ f"UPDATE links SET target_id = NULL WHERE target_id IN ({placeholders})", ids
+ )
+
+ # Now resolve all currently-NULL links (which includes the ones we just reset
+ # plus any that were already broken and might now resolve)
+ _resolve_null_links(conn)
+
+
+def _resolve_null_links(conn) -> None:
+ """Resolve all links with target_id = NULL."""
+ # Exact ID match
+ conn.execute("""
+ UPDATE links SET target_id = (
+ SELECT n.id FROM notes n WHERE n.id = links.target_ref LIMIT 1
+ )
+ WHERE target_id IS NULL
+ """)
+ # Case-insensitive ID match
+ conn.execute("""
+ UPDATE links SET target_id = (
+ SELECT n.id FROM notes n WHERE LOWER(n.id) = LOWER(links.target_ref) LIMIT 1
+ )
+ WHERE target_id IS NULL
+ """)
+ # Alias match
+ conn.execute("""
+ UPDATE links SET target_id = (
+ SELECT a.note_id FROM aliases a
+ WHERE LOWER(a.alias) = LOWER(links.target_ref)
+ LIMIT 1
+ )
+ WHERE target_id IS NULL
+ """)
+ # Title match
+ conn.execute("""
+ UPDATE links SET target_id = (
+ SELECT n.id FROM notes n WHERE LOWER(n.title) = LOWER(links.target_ref) LIMIT 1
+ )
+ WHERE target_id IS NULL
+ """)
diff --git a/src/hyperresearch/core/templates.py b/src/hyperresearch/core/templates.py
new file mode 100644
index 0000000..98a6375
--- /dev/null
+++ b/src/hyperresearch/core/templates.py
@@ -0,0 +1,210 @@
+"""Built-in note templates."""
+
+from __future__ import annotations
+
+from datetime import UTC
+
+BUILTIN_TEMPLATES: dict[str, str] = {
+ "note": """\
+---
+title: "{{ title }}"
+id: "{{ id }}"
+tags: [{{ tags }}]
+status: draft
+type: note
+created: {{ created }}
+---
+
+# {{ title }}
+
+""",
+ "concept": """\
+---
+title: "{{ title }}"
+id: "{{ id }}"
+tags: [{{ tags }}]
+status: draft
+type: note
+summary: ""
+created: {{ created }}
+---
+
+# {{ title }}
+
+## Definition
+
+_What is this concept?_
+
+## Key Properties
+
+-
+
+## Examples
+
+-
+
+## Related
+
+- [[]]
+""",
+ "reference": """\
+---
+title: "{{ title }}"
+id: "{{ id }}"
+tags: [{{ tags }}]
+status: draft
+type: raw
+source: ""
+summary: ""
+confidence: 0.7
+created: {{ created }}
+---
+
+# {{ title }}
+
+## Citation
+
+_Author, Title, Year. URL._
+
+## Key Points
+
+-
+
+## Quotes
+
+>
+
+## My Notes
+
+""",
+ "guide": """\
+---
+title: "{{ title }}"
+id: "{{ id }}"
+tags: [{{ tags }}]
+status: draft
+type: note
+summary: ""
+created: {{ created }}
+---
+
+# {{ title }}
+
+## Prerequisites
+
+- [[]]
+
+## Steps
+
+### 1.
+
+### 2.
+
+### 3.
+
+## Pitfalls
+
+-
+
+## See Also
+
+- [[]]
+""",
+ "comparison": """\
+---
+title: "{{ title }}"
+id: "{{ id }}"
+tags: [{{ tags }}]
+status: draft
+type: note
+summary: ""
+created: {{ created }}
+---
+
+# {{ title }}
+
+## Overview
+
+_What are we comparing and why?_
+
+## Comparison
+
+| Criteria | Option A | Option B |
+|----------|----------|----------|
+| | | |
+| | | |
+
+## Verdict
+
+## Related
+
+- [[]]
+""",
+ "moc": """\
+---
+title: "{{ title }}"
+id: "{{ id }}"
+tags: [{{ tags }}]
+status: draft
+type: moc
+summary: "Map of content for {{ title }}"
+created: {{ created }}
+---
+
+# {{ title }}
+
+## Core Concepts
+
+- [[]]
+
+## Guides
+
+- [[]]
+
+## References
+
+- [[]]
+
+## Open Questions
+
+-
+""",
+}
+
+
+def get_template(name: str, templates_dir=None) -> str | None:
+ """Get a template by name. Checks vault templates dir first, then built-ins."""
+ if templates_dir:
+ custom = templates_dir / f"{name}.md"
+ if custom.exists():
+ return custom.read_text(encoding="utf-8")
+ return BUILTIN_TEMPLATES.get(name)
+
+
+def list_templates(templates_dir=None) -> list[dict]:
+ """List available templates."""
+ templates = []
+ for name in BUILTIN_TEMPLATES:
+ templates.append({"name": name, "source": "builtin"})
+
+ if templates_dir and templates_dir.exists():
+ for f in sorted(templates_dir.glob("*.md")):
+ name = f.stem
+ if name not in BUILTIN_TEMPLATES:
+ templates.append({"name": name, "source": "custom"})
+ return templates
+
+
+def render_template(template_str: str, title: str, note_id: str, tags: list[str]) -> str:
+ """Render a template with Jinja2-like variable substitution."""
+ from datetime import datetime
+
+ now = datetime.now(UTC).isoformat()
+ tags_str = ", ".join(tags) if tags else ""
+
+ result = template_str
+ result = result.replace("{{ title }}", title)
+ result = result.replace("{{ id }}", note_id)
+ result = result.replace("{{ tags }}", tags_str)
+ result = result.replace("{{ created }}", now)
+ return result
diff --git a/src/hyperresearch/core/vault.py b/src/hyperresearch/core/vault.py
new file mode 100644
index 0000000..785ac15
--- /dev/null
+++ b/src/hyperresearch/core/vault.py
@@ -0,0 +1,153 @@
+"""Vault discovery, initialization, and management."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from hyperresearch.core.config import VaultConfig
+from hyperresearch.core.db import get_connection, init_schema
+
+HYPERRESEARCH_DIR = ".hyperresearch"
+CONFIG_FILE = "config.toml"
+DB_FILE = "hyperresearch.db"
+
+
+class VaultError(Exception):
+ pass
+
+
+class Vault:
+ """Represents a hyperresearch research base vault."""
+
+ def __init__(self, root: Path) -> None:
+ self.root = root.resolve()
+ self.hyperresearch_dir = self.root / HYPERRESEARCH_DIR
+ self.config_path = self.hyperresearch_dir / CONFIG_FILE
+ self.db_path = self.hyperresearch_dir / DB_FILE
+ self._conn: sqlite3.Connection | None = None
+ self._config: VaultConfig | None = None
+
+ @property
+ def config(self) -> VaultConfig:
+ if self._config is None:
+ self._config = VaultConfig.load(self.config_path)
+ return self._config
+
+ @property
+ def db(self) -> sqlite3.Connection:
+ if self._conn is None:
+ self._conn = get_connection(self.db_path)
+ return self._conn
+
+ @property
+ def is_initialized(self) -> bool:
+ return self.hyperresearch_dir.is_dir() and self.db_path.exists()
+
+ # --- Path properties: single source of truth for directory layout ---
+
+ @property
+ def research_dir(self) -> Path:
+ """The one visible directory at repo root (default: research/)."""
+ return self.root / self.config.research_dir
+
+ @property
+ def notes_dir(self) -> Path:
+ return self.research_dir / "notes"
+
+ @property
+ def index_dir(self) -> Path:
+ return self.research_dir / "index"
+
+ @property
+ def templates_dir(self) -> Path:
+ """Templates live inside .hyperresearch/ (hidden)."""
+ return self.hyperresearch_dir / "templates"
+
+ @property
+ def exports_dir(self) -> Path:
+ """Exports live inside .hyperresearch/ (hidden)."""
+ return self.hyperresearch_dir / "exports"
+
+ def close(self) -> None:
+ if self._conn is not None:
+ self._conn.close()
+ self._conn = None
+
+ def __enter__(self) -> Vault:
+ return self
+
+ def __exit__(self, *args) -> None:
+ self.close()
+
+ @staticmethod
+ def init(root: Path, name: str = "Research Base", research_dir: str = "research", agents: list[str] | None = None) -> Vault:
+ """Initialize a new vault at the given path."""
+ root = root.resolve()
+ hyperresearch_dir = root / HYPERRESEARCH_DIR
+
+ if hyperresearch_dir.exists():
+ raise VaultError(f"Vault already initialized at {root}")
+
+ # Create .hyperresearch/ structure (hidden)
+ hyperresearch_dir.mkdir(parents=True)
+ (hyperresearch_dir / "templates").mkdir()
+ (hyperresearch_dir / "exports").mkdir()
+
+ # Create the one visible directory
+ kb_dir = root / research_dir
+ (kb_dir / "notes").mkdir(parents=True, exist_ok=True)
+ (kb_dir / "index").mkdir(exist_ok=True)
+
+ # Write config
+ config = VaultConfig(name=name, research_dir=research_dir)
+ config.save(hyperresearch_dir / CONFIG_FILE)
+
+ # Initialize database
+ vault = Vault(root)
+ init_schema(vault.db)
+
+ # Write default note template
+ template_path = hyperresearch_dir / "templates" / "note.md"
+ template_path.write_text(
+ "---\n"
+ "title: \"{{ title }}\"\n"
+ "id: \"{{ id }}\"\n"
+ "tags: []\n"
+ "status: draft\n"
+ "type: note\n"
+ "created: {{ created }}\n"
+ "---\n\n"
+ "# {{ title }}\n\n"
+ )
+
+ # Inject hyperresearch docs into agent config files (CLAUDE.md, AGENTS.md)
+ from hyperresearch.core.agent_docs import inject_agent_docs
+ inject_agent_docs(root, agents=agents)
+
+ return vault
+
+ @staticmethod
+ def discover(start: Path | None = None) -> Vault:
+ """Walk up from start (default: cwd) to find a vault root."""
+ current = (start or Path.cwd()).resolve()
+ while True:
+ if (current / HYPERRESEARCH_DIR).is_dir():
+ return Vault(current)
+ parent = current.parent
+ if parent == current:
+ break
+ current = parent
+ raise VaultError(
+ "No hyperresearch vault found. Run 'hyperresearch init' to create one."
+ )
+
+ def auto_sync(self) -> None:
+ """Run an incremental sync if auto_sync is enabled."""
+ if not self.config.auto_sync:
+ return
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+
+ plan = compute_sync_plan(self)
+ if plan.to_add or plan.to_update or plan.to_delete:
+ execute_sync(self, plan)
diff --git a/src/hyperresearch/export/__init__.py b/src/hyperresearch/export/__init__.py
new file mode 100644
index 0000000..6b9304d
--- /dev/null
+++ b/src/hyperresearch/export/__init__.py
@@ -0,0 +1 @@
+"""Export formatters."""
diff --git a/src/hyperresearch/graph/__init__.py b/src/hyperresearch/graph/__init__.py
new file mode 100644
index 0000000..267c26c
--- /dev/null
+++ b/src/hyperresearch/graph/__init__.py
@@ -0,0 +1 @@
+"""Knowledge graph operations."""
diff --git a/src/hyperresearch/indexgen/__init__.py b/src/hyperresearch/indexgen/__init__.py
new file mode 100644
index 0000000..b9be36c
--- /dev/null
+++ b/src/hyperresearch/indexgen/__init__.py
@@ -0,0 +1 @@
+"""Auto-generated index page builder."""
diff --git a/src/hyperresearch/indexgen/generator.py b/src/hyperresearch/indexgen/generator.py
new file mode 100644
index 0000000..24a3273
--- /dev/null
+++ b/src/hyperresearch/indexgen/generator.py
@@ -0,0 +1,256 @@
+"""Index page generation — builds auto-maintained .md index files."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+class IndexGenerator:
+ def __init__(self, vault) -> None:
+ self.vault = vault
+ self.index_dir = vault.index_dir
+ self.index_dir.mkdir(exist_ok=True)
+
+ def build_all(self) -> list[str]:
+ """Build all index pages. Cleans up stale pages first."""
+ # Delete all existing index pages before regenerating
+ if self.index_dir.exists():
+ for old_file in self.index_dir.glob("*.md"):
+ old_file.unlink()
+
+ built = []
+ built.append(self._build_master_index())
+ built.append(self._build_tags_index())
+ built.extend(self._build_per_tag_indexes())
+ built.append(self._build_recent())
+ built.append(self._build_orphans())
+ built.append(self._build_stats())
+ built.append(self._build_raw_pending())
+ built.extend(self._build_by_month())
+ built.append(self._build_stale())
+ built.append(self._build_most_linked())
+ return [b for b in built if b]
+
+ def _write_index(self, filename: str, title: str, body: str) -> str:
+ now_iso = datetime.now(UTC).isoformat()
+ content = (
+ f"---\n"
+ f"title: \"{title}\"\n"
+ f"id: \"{filename.replace('.md', '')}\"\n"
+ f"type: index\n"
+ f"created: {now_iso}\n"
+ f"updated: {now_iso}\n"
+ f"---\n\n"
+ f"{body}\n\n"
+ f"---\n*Auto-generated by hyperresearch. Do not edit manually.*\n"
+ )
+ path = self.index_dir / filename
+ path.write_text(content, encoding="utf-8")
+ return f"index/{filename}"
+
+ def _build_master_index(self) -> str:
+ rows = self.vault.db.execute(
+ "SELECT id, title, path, status, type, parent, word_count, summary "
+ "FROM notes WHERE type NOT IN ('index') ORDER BY parent, title"
+ ).fetchall()
+
+ lines = ["# Master Index\n", f"**{len(rows)}** notes in vault.\n"]
+
+ # Group by parent
+ groups: dict[str, list] = {}
+ for r in rows:
+ parent = r["parent"] or "Uncategorized"
+ groups.setdefault(parent, []).append(r)
+
+ for parent, notes in sorted(groups.items()):
+ lines.append(f"\n## {parent}\n")
+ for n in notes:
+ status_badge = f"`{n['status']}`"
+ summary = f" — {n['summary']}" if n["summary"] else ""
+ lines.append(f"- [[{n['id']}]] — {n['title']}{summary} {status_badge} ({n['word_count']} words)")
+
+ return self._write_index("_index.md", "Master Index", "\n".join(lines))
+
+ def _build_tags_index(self) -> str:
+ rows = self.vault.db.execute(
+ "SELECT tag, COUNT(*) as count FROM tags GROUP BY tag ORDER BY count DESC"
+ ).fetchall()
+
+ lines = ["# Tags Index\n", f"**{len(rows)}** unique tags.\n"]
+ for r in rows:
+ # Only link to per-tag page if tag has 3+ notes (avoids index bloat)
+ if r["count"] >= 3:
+ lines.append(f"- **{r['tag']}** ({r['count']} notes) → [[_tag-{r['tag']}]]")
+ else:
+ lines.append(f"- **{r['tag']}** ({r['count']} notes)")
+
+ return self._write_index("_tags.md", "Tags Index", "\n".join(lines))
+
+ def _build_per_tag_indexes(self) -> list[str]:
+ """Only generate per-tag index pages for tags with 3+ notes."""
+ built = []
+ tags = self.vault.db.execute(
+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag HAVING c >= 3 ORDER BY tag"
+ ).fetchall()
+ for tag_row in tags:
+ tag = tag_row["tag"]
+ rows = self.vault.db.execute(
+ "SELECT n.id, n.title, n.status, n.word_count, n.summary "
+ "FROM notes n JOIN tags t ON n.id = t.note_id "
+ "WHERE t.tag = ? ORDER BY n.title",
+ (tag,),
+ ).fetchall()
+ lines = [f"# Tag: {tag}\n", f"**{len(rows)}** notes.\n"]
+ for r in rows:
+ summary = f" — {r['summary']}" if r["summary"] else ""
+ lines.append(f"- [[{r['id']}]] — {r['title']}{summary} `{r['status']}`")
+ built.append(self._write_index(f"_tag-{tag}.md", f"Tag: {tag}", "\n".join(lines)))
+ return built
+
+ def _build_recent(self) -> str:
+ rows = self.vault.db.execute(
+ "SELECT id, title, status, type, created, updated, word_count "
+ "FROM notes WHERE type NOT IN ('index') "
+ "ORDER BY COALESCE(updated, created) DESC LIMIT 50"
+ ).fetchall()
+
+ lines = ["# Recently Updated\n"]
+ for r in rows:
+ date = r["updated"] or r["created"]
+ if date and len(date) > 10:
+ date = date[:10]
+ lines.append(f"- `{date}` [[{r['id']}]] — {r['title']}")
+
+ return self._write_index("_recent.md", "Recently Updated", "\n".join(lines))
+
+ def _build_orphans(self) -> str:
+ rows = self.vault.db.execute("""
+ SELECT n.id, n.title, n.path, n.status
+ FROM notes n
+ WHERE n.type NOT IN ('index', 'raw')
+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)
+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)
+ ORDER BY n.title
+ """).fetchall()
+
+ lines = ["# Orphan Notes\n", f"**{len(rows)}** notes with no inbound or outbound links.\n"]
+ if not rows:
+ lines.append("*No orphans — all notes are connected!*")
+ for r in rows:
+ lines.append(f"- [[{r['id']}]] — {r['title']} ({r['path']})")
+
+ return self._write_index("_orphans.md", "Orphan Notes", "\n".join(lines))
+
+ def _build_stats(self) -> str:
+ total = self.vault.db.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]
+ total_words = self.vault.db.execute(
+ "SELECT COALESCE(SUM(word_count), 0) as c FROM notes"
+ ).fetchone()["c"]
+ total_links = self.vault.db.execute("SELECT COUNT(*) as c FROM links").fetchone()["c"]
+ broken = self.vault.db.execute(
+ "SELECT COUNT(*) as c FROM links WHERE target_id IS NULL"
+ ).fetchone()["c"]
+ total_tags = self.vault.db.execute(
+ "SELECT COUNT(DISTINCT tag) as c FROM tags"
+ ).fetchone()["c"]
+
+ by_status = {}
+ for r in self.vault.db.execute("SELECT status, COUNT(*) as c FROM notes GROUP BY status"):
+ by_status[r["status"]] = r["c"]
+
+ by_type = {}
+ for r in self.vault.db.execute("SELECT type, COUNT(*) as c FROM notes GROUP BY type"):
+ by_type[r["type"]] = r["c"]
+
+ lines = [
+ "# Vault Statistics\n",
+ "| Metric | Value |",
+ "|--------|-------|",
+ f"| Total notes | {total} |",
+ f"| Total words | {total_words:,} |",
+ f"| Unique tags | {total_tags} |",
+ f"| Total links | {total_links} |",
+ f"| Broken links | {broken} |",
+ "",
+ "## By Status\n",
+ ]
+ for s, c in sorted(by_status.items()):
+ lines.append(f"- **{s}**: {c}")
+
+ lines.append("\n## By Type\n")
+ for t, c in sorted(by_type.items()):
+ lines.append(f"- **{t}**: {c}")
+
+ return self._write_index("_stats.md", "Vault Statistics", "\n".join(lines))
+
+ def _build_raw_pending(self) -> str:
+ rows = self.vault.db.execute(
+ "SELECT id, title, path, created FROM notes WHERE type = 'raw' ORDER BY created DESC"
+ ).fetchall()
+
+ lines = ["# Unprocessed (Pending Compilation)\n", f"**{len(rows)}** raw notes awaiting compilation.\n"]
+ for r in rows:
+ date = r["created"][:10] if r["created"] and len(r["created"]) > 10 else r["created"]
+ lines.append(f"- `{date}` [[{r['id']}]] — {r['title']}")
+
+ return self._write_index("_raw-pending.md", "Raw Pending", "\n".join(lines))
+
+ def _build_by_month(self) -> list[str]:
+ """Generate per-month index pages for months with 3+ notes."""
+ rows = self.vault.db.execute(
+ "SELECT id, title, status, summary, created FROM notes "
+ "WHERE type NOT IN ('index') AND created IS NOT NULL "
+ "ORDER BY created DESC"
+ ).fetchall()
+
+ months: dict[str, list] = {}
+ for r in rows:
+ created = r["created"] or ""
+ month = created[:7] if len(created) >= 7 else "unknown"
+ months.setdefault(month, []).append(r)
+
+ built = []
+ for month, notes in sorted(months.items(), reverse=True):
+ if len(notes) < 3 or month == "unknown":
+ continue
+ lines = [f"# Notes from {month}\n", f"**{len(notes)}** notes.\n"]
+ for r in notes:
+ date = (r["created"] or "")[:10]
+ summary = f" — {r['summary']}" if r["summary"] else ""
+ lines.append(f"- `{date}` [[{r['id']}]] — {r['title']}{summary}")
+ built.append(self._write_index(f"_month-{month}.md", f"Month: {month}", "\n".join(lines)))
+ return built
+
+ def _build_stale(self) -> str:
+ """Evergreen notes not updated in 6+ months — candidates for review."""
+ from datetime import datetime, timedelta
+ cutoff = (datetime.now(UTC) - timedelta(days=180)).isoformat()
+ rows = self.vault.db.execute(
+ "SELECT id, title, status, updated, created, word_count FROM notes "
+ "WHERE status = 'evergreen' AND type NOT IN ('index') "
+ "AND COALESCE(updated, created) < ? "
+ "ORDER BY COALESCE(updated, created)",
+ (cutoff,),
+ ).fetchall()
+
+ lines = ["# Stale Notes\n", f"**{len(rows)}** evergreen notes not updated in 6+ months.\n"]
+ for r in rows:
+ date = (r["updated"] or r["created"] or "")[:10]
+ lines.append(f"- `{date}` [[{r['id']}]] — {r['title']} ({r['word_count']}w)")
+
+ return self._write_index("_stale.md", "Stale Notes", "\n".join(lines))
+
+ def _build_most_linked(self) -> str:
+ """Top 30 notes by inbound link count."""
+ rows = self.vault.db.execute(
+ "SELECT l.target_id as id, n.title, COUNT(*) as inbound "
+ "FROM links l JOIN notes n ON l.target_id = n.id "
+ "WHERE l.target_id IS NOT NULL "
+ "GROUP BY l.target_id ORDER BY inbound DESC LIMIT 30"
+ ).fetchall()
+
+ lines = ["# Most Linked Notes\n", f"Top {len(rows)} notes by inbound link count.\n"]
+ for r in rows:
+ lines.append(f"- [[{r['id']}]] — {r['title']} ({r['inbound']} inbound links)")
+
+ return self._write_index("_most-linked.md", "Most Linked", "\n".join(lines))
diff --git a/src/hyperresearch/mcp/__init__.py b/src/hyperresearch/mcp/__init__.py
new file mode 100644
index 0000000..f269048
--- /dev/null
+++ b/src/hyperresearch/mcp/__init__.py
@@ -0,0 +1 @@
+"""MCP server for hyperresearch — exposes research base tools to any MCP-compatible agent."""
diff --git a/src/hyperresearch/mcp/server.py b/src/hyperresearch/mcp/server.py
new file mode 100644
index 0000000..3c12804
--- /dev/null
+++ b/src/hyperresearch/mcp/server.py
@@ -0,0 +1,235 @@
+"""hyperresearch MCP server — thin protocol layer over existing hyperresearch functions.
+
+Exposes 8 tools for agents: search, read, read_many, list, backlinks, hubs, status, lint.
+Read-only by design — agents create/edit notes via file operations, hyperresearch auto-syncs.
+"""
+
+from __future__ import annotations
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+server = FastMCP("hyperresearch", instructions=(
+ "hyperresearch is an agent-driven research knowledge base. Use these tools to search, read, "
+ "and navigate research notes with wiki-links, tags, and summaries. Notes live in the research/ "
+ "directory as markdown files with YAML frontmatter. To create or edit notes, write "
+ "files directly and they will be auto-indexed."
+))
+
+_vault = None
+
+
+def _get_vault():
+ global _vault
+ if _vault is None:
+ from hyperresearch.core.vault import Vault
+ _vault = Vault.discover()
+ _vault.auto_sync()
+ return _vault
+
+
+def search_notes(query: str, tag: str = "", status: str = "", parent: str = "", limit: int = 10) -> str:
+ """Search the research base by text. Returns matching notes with titles, summaries, and full bodies.
+
+ Args:
+ query: Search query (supports natural language, FTS5 with porter stemming)
+ tag: Filter by tag (comma-separated for multiple, AND logic)
+ status: Filter by status (draft, review, evergreen, stale, deprecated, archive)
+ parent: Filter by parent topic (e.g. "ml/deep-learning")
+ limit: Max results to return (default 10)
+ """
+ vault = _get_vault()
+ vault.auto_sync()
+ from hyperresearch.search.filters import SearchFilters
+ from hyperresearch.search.fts import search_fts
+ tags = [t.strip() for t in tag.split(",") if t.strip()] or None
+ filters = SearchFilters(tags=tags, status=status or None, parent=parent or None)
+ ranking = {
+ "title_weight": vault.config.search_title_weight,
+ "body_weight": vault.config.search_body_weight,
+ "tags_weight": vault.config.search_tags_weight,
+ "aliases_weight": vault.config.search_aliases_weight,
+ "boost_evergreen": vault.config.search_boost_evergreen,
+ "penalize_deprecated": vault.config.search_penalize_deprecated,
+ "penalize_stale": vault.config.search_penalize_stale,
+ }
+ results = search_fts(vault.db, query, filters=filters, limit=limit, ranking=ranking)
+ for r in results:
+ row = vault.db.execute("SELECT body FROM note_content WHERE note_id = ?", (r["id"],)).fetchone()
+ r["body"] = row["body"] if row else ""
+ return json.dumps(results, default=str)
+
+
+def read_note(note_id: str) -> str:
+ """Read a single note by ID. Returns full metadata and body content.
+
+ Args:
+ note_id: The note's slug ID (e.g. "transformer-architecture")
+ """
+ vault = _get_vault()
+ vault.auto_sync()
+ row = vault.db.execute(
+ "SELECT n.*, nc.body FROM notes n JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?",
+ (note_id,),
+ ).fetchone()
+ if not row:
+ return json.dumps({"error": f"Note not found: {note_id}"})
+ tag_row = vault.db.execute("SELECT GROUP_CONCAT(tag, ',') as tl FROM tags WHERE note_id = ?", (note_id,)).fetchone()
+ tags = tag_row["tl"].split(",") if tag_row and tag_row["tl"] else []
+ return json.dumps({
+ "id": row["id"], "title": row["title"], "path": row["path"],
+ "status": row["status"], "type": row["type"], "tags": tags,
+ "created": row["created"], "updated": row["updated"],
+ "word_count": row["word_count"], "summary": row["summary"],
+ "source": row["source"], "parent": row["parent"], "body": row["body"],
+ }, default=str)
+
+
+def read_many(note_ids: str) -> str:
+ """Read multiple notes at once. Pass comma-separated IDs.
+
+ Args:
+ note_ids: Comma-separated note IDs (e.g. "auth-flow,session-mgmt,jwt-tokens")
+ """
+ vault = _get_vault()
+ vault.auto_sync()
+ ids = [nid.strip() for nid in note_ids.split(",") if nid.strip()]
+ notes, not_found = [], []
+ for nid in ids:
+ row = vault.db.execute(
+ "SELECT n.*, nc.body FROM notes n JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?", (nid,)
+ ).fetchone()
+ if row:
+ tag_row = vault.db.execute("SELECT GROUP_CONCAT(tag, ',') as tl FROM tags WHERE note_id = ?", (nid,)).fetchone()
+ tags = tag_row["tl"].split(",") if tag_row and tag_row["tl"] else []
+ notes.append({"id": row["id"], "title": row["title"], "status": row["status"],
+ "tags": tags, "word_count": row["word_count"], "summary": row["summary"], "body": row["body"]})
+ else:
+ not_found.append(nid)
+ return json.dumps({"notes": notes, "not_found": not_found}, default=str)
+
+
+def list_notes(status: str = "", tag: str = "", parent: str = "", sort: str = "updated", limit: int = 50) -> str:
+ """List notes with optional filters. Returns summaries (no bodies).
+
+ Args:
+ status: Filter by status
+ tag: Filter by tag
+ parent: Filter by parent topic
+ sort: Sort order (created, updated, title, words)
+ limit: Max results (default 50, use 0 for all)
+ """
+ vault = _get_vault()
+ vault.auto_sync()
+ clauses, params = ["n.type NOT IN ('index')"], []
+ 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.extend([parent, parent + "/%"])
+ where = " AND ".join(clauses)
+ sort_map = {"created": "n.created DESC", "updated": "COALESCE(n.updated, n.created) DESC",
+ "title": "n.title ASC", "words": "n.word_count DESC"}
+ order = sort_map.get(sort, "COALESCE(n.updated, n.created) DESC")
+ effective_limit = 999999 if limit == 0 else limit
+ rows = vault.db.execute(
+ f"SELECT n.*, (SELECT GROUP_CONCAT(t.tag, ',') FROM tags t WHERE t.note_id = n.id) as tag_list "
+ f"FROM notes n WHERE {where} ORDER BY {order} LIMIT ?", [*params, effective_limit]
+ ).fetchall()
+ notes = [{"id": r["id"], "title": r["title"], "status": r["status"],
+ "tags": r["tag_list"].split(",") if r["tag_list"] else [],
+ "word_count": r["word_count"], "summary": r["summary"]} for r in rows]
+ return json.dumps(notes, default=str)
+
+
+def get_backlinks(note_id: str) -> str:
+ """Get all notes that link TO a given note.
+
+ Args:
+ note_id: The target note ID
+ """
+ vault = _get_vault()
+ vault.auto_sync()
+ rows = vault.db.execute(
+ "SELECT l.source_id, n.title, l.line_number, l.context "
+ "FROM links l JOIN notes n ON l.source_id = n.id WHERE l.target_id = ? ORDER BY n.title",
+ (note_id,),
+ ).fetchall()
+ backlinks = [{"source_id": r["source_id"], "title": r["title"],
+ "line": r["line_number"], "context": r["context"]} for r in rows]
+ return json.dumps({"note_id": note_id, "backlinks": backlinks, "count": len(backlinks)})
+
+
+def get_hubs(limit: int = 20) -> str:
+ """Get the most-linked-to notes in the research base (hub notes).
+
+ Args:
+ limit: Max results (default 20)
+ """
+ vault = _get_vault()
+ vault.auto_sync()
+ rows = vault.db.execute(
+ "SELECT l.target_id as id, n.title, COUNT(*) as inbound "
+ "FROM links l JOIN notes n ON l.target_id = n.id "
+ "WHERE l.target_id IS NOT NULL GROUP BY l.target_id ORDER BY inbound DESC LIMIT ?",
+ (limit,),
+ ).fetchall()
+ return json.dumps([{"id": r["id"], "title": r["title"], "inbound_links": r["inbound"]} for r in rows])
+
+
+def vault_status() -> str:
+ """Get vault health overview: note counts, tag distribution, link stats, word count."""
+ vault = _get_vault()
+ vault.auto_sync()
+ conn = vault.db
+ total = conn.execute("SELECT COUNT(*) as c FROM notes WHERE type NOT IN ('index')").fetchone()["c"]
+ by_status = {r["status"]: r["c"] for r in conn.execute(
+ "SELECT status, COUNT(*) as c FROM notes WHERE type NOT IN ('index') GROUP BY status")}
+ tag_count = conn.execute("SELECT COUNT(DISTINCT tag) as c FROM tags").fetchone()["c"]
+ top_tags = [{"tag": r["tag"], "count": r["count"]} for r in conn.execute(
+ "SELECT tag, COUNT(*) as count FROM tags GROUP BY tag ORDER BY count DESC LIMIT 10")]
+ total_links = conn.execute("SELECT COUNT(*) as c FROM links").fetchone()["c"]
+ broken = conn.execute("SELECT COUNT(*) as c FROM links WHERE target_id IS NULL").fetchone()["c"]
+ total_words = conn.execute("SELECT COALESCE(SUM(word_count), 0) as c FROM notes").fetchone()["c"]
+ return json.dumps({"vault_name": vault.config.name, "total_notes": total, "by_status": by_status,
+ "unique_tags": tag_count, "top_tags": top_tags, "total_links": total_links,
+ "broken_links": broken, "total_words": total_words})
+
+
+def lint_vault(rule: str = "") -> str:
+ """Run health checks on the vault. Returns issues found.
+
+ Args:
+ rule: Specific rule to check (leave empty for all)
+ """
+ vault = _get_vault()
+ vault.auto_sync()
+ conn = vault.db
+ issues: list[dict] = []
+ rules = [rule] if rule else ["missing-tags", "missing-summary", "broken-links", "orphaned-notes"]
+ if "missing-tags" in rules:
+ for r in conn.execute("SELECT id FROM notes WHERE type NOT IN ('index','raw') AND id NOT IN (SELECT DISTINCT note_id FROM tags)"):
+ issues.append({"rule": "missing-tags", "severity": "warning", "note_id": r["id"], "message": "No tags"})
+ if "missing-summary" in rules:
+ for r in conn.execute("SELECT id FROM notes WHERE type NOT IN ('index','raw') AND (summary IS NULL OR LENGTH(TRIM(COALESCE(summary, ''))) = 0)"):
+ issues.append({"rule": "missing-summary", "severity": "warning", "note_id": r["id"], "message": "No summary"})
+ if "broken-links" in rules:
+ for r in conn.execute("SELECT source_id, target_ref FROM links WHERE target_id IS NULL"):
+ issues.append({"rule": "broken-links", "severity": "warning", "note_id": r["source_id"], "message": f"Broken: [[{r['target_ref']}]]"})
+ if "orphaned-notes" in rules:
+ for r in conn.execute("SELECT id FROM notes WHERE type NOT IN ('index','raw') AND id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL) AND id NOT IN (SELECT DISTINCT source_id FROM links)"):
+ issues.append({"rule": "orphaned-notes", "severity": "info", "note_id": r["id"], "message": "No links"})
+ return json.dumps({"issues": issues, "total": len(issues), "warnings": sum(1 for i in issues if i["severity"] == "warning")})
diff --git a/src/hyperresearch/models/__init__.py b/src/hyperresearch/models/__init__.py
new file mode 100644
index 0000000..852edf5
--- /dev/null
+++ b/src/hyperresearch/models/__init__.py
@@ -0,0 +1 @@
+"""Pydantic models for hyperresearch data structures."""
diff --git a/src/hyperresearch/models/graph.py b/src/hyperresearch/models/graph.py
new file mode 100644
index 0000000..abd5ee3
--- /dev/null
+++ b/src/hyperresearch/models/graph.py
@@ -0,0 +1,21 @@
+"""Graph and link models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class LinkEntry(BaseModel):
+ source_id: str
+ target_ref: str
+ target_id: str | None
+ line_number: int | None
+ context: str = ""
+
+
+class BacklinkEntry(BaseModel):
+ source_id: str
+ source_title: str
+ source_path: str
+ line_number: int | None
+ context: str = ""
diff --git a/src/hyperresearch/models/note.py b/src/hyperresearch/models/note.py
new file mode 100644
index 0000000..336fa8c
--- /dev/null
+++ b/src/hyperresearch/models/note.py
@@ -0,0 +1,88 @@
+"""Note and frontmatter models."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class NoteStatus(StrEnum):
+ DRAFT = "draft"
+ REVIEW = "review"
+ EVERGREEN = "evergreen"
+ STALE = "stale"
+ DEPRECATED = "deprecated"
+ ARCHIVE = "archive"
+
+
+class NoteType(StrEnum):
+ NOTE = "note"
+ RAW = "raw"
+ INDEX = "index"
+ MOC = "moc"
+
+
+def slugify(text: str) -> str:
+ """Convert text to a URL-friendly slug. Preserves underscores."""
+ text = text.lower().strip()
+ text = re.sub(r"[^\w\s-]", "", text, flags=re.ASCII)
+ text = re.sub(r"\s+", "-", text)
+ text = re.sub(r"-+", "-", text)
+ result = text.strip("-")
+ if not result:
+ # Fallback for titles with only special/non-ASCII characters
+ import hashlib
+ result = "note-" + hashlib.sha256(text.encode()).hexdigest()[:8]
+ return result
+
+
+class NoteMeta(BaseModel):
+ """YAML frontmatter schema for a hyperresearch note."""
+
+ title: str
+ id: str = ""
+ tags: list[str] = Field(default_factory=list)
+ created: datetime = Field(default_factory=lambda: datetime.now(UTC))
+ updated: datetime | None = None
+ source: str | None = None
+ status: NoteStatus = NoteStatus.DRAFT
+ type: NoteType = NoteType.NOTE
+ aliases: list[str] = Field(default_factory=list)
+ parent: str | None = None
+ confidence: float | None = None
+ superseded_by: str | None = None # Note ID that replaces this one
+ deprecated: bool = False # Explicitly marked as outdated
+ reviewed: datetime | None = None # Last time a human verified accuracy
+ expires: datetime | None = None # Auto-stale after this date
+ llm_compiled: bool = False
+ llm_model: str | None = None
+ compile_source: str | None = None
+ summary: str | None = None
+
+ @field_validator("tags", mode="before")
+ @classmethod
+ def lowercase_tags(cls, v: list[str]) -> list[str]:
+ return [t.lower().strip() for t in v]
+
+ @field_validator("id", mode="before")
+ @classmethod
+ def ensure_slug(cls, v: str) -> str:
+ if v:
+ return slugify(v)
+ return v
+
+ model_config = {"use_enum_values": True}
+
+
+class Note(BaseModel):
+ """A full note: metadata + body + disk info."""
+
+ meta: NoteMeta
+ body: str
+ path: str # Relative path from vault root
+ content_hash: str = ""
+ word_count: int = 0
+ outgoing_links: list[str] = Field(default_factory=list)
diff --git a/src/hyperresearch/models/output.py b/src/hyperresearch/models/output.py
new file mode 100644
index 0000000..48df8c4
--- /dev/null
+++ b/src/hyperresearch/models/output.py
@@ -0,0 +1,28 @@
+"""Envelope models for consistent CLI output."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Envelope(BaseModel):
+ """Standard JSON output wrapper for all commands."""
+
+ ok: bool = True
+ data: Any = None
+ error: str | None = None
+ error_code: str | None = None
+ count: int | None = None
+ vault: str | None = None
+ timestamp: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+
+def success(data: Any, count: int | None = None, vault: str | None = None) -> Envelope:
+ return Envelope(ok=True, data=data, count=count, vault=vault)
+
+
+def error(message: str, code: str = "ERROR", vault: str | None = None) -> Envelope:
+ return Envelope(ok=False, error=message, error_code=code, vault=vault)
diff --git a/src/hyperresearch/models/search.py b/src/hyperresearch/models/search.py
new file mode 100644
index 0000000..2e7e6aa
--- /dev/null
+++ b/src/hyperresearch/models/search.py
@@ -0,0 +1,24 @@
+"""Search result models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class SearchResult(BaseModel):
+ id: str
+ title: str
+ path: str
+ status: str
+ tags: list[str]
+ created: str
+ updated: str | None
+ score: float
+ snippet: str = ""
+
+
+class SearchResponse(BaseModel):
+ query: str
+ filters: dict
+ total: int
+ results: list[SearchResult]
diff --git a/src/hyperresearch/py.typed b/src/hyperresearch/py.typed
new file mode 100644
index 0000000..e69de29
diff --git a/src/hyperresearch/search/__init__.py b/src/hyperresearch/search/__init__.py
new file mode 100644
index 0000000..d08db2d
--- /dev/null
+++ b/src/hyperresearch/search/__init__.py
@@ -0,0 +1 @@
+"""Search engines for hyperresearch."""
diff --git a/src/hyperresearch/search/filters.py b/src/hyperresearch/search/filters.py
new file mode 100644
index 0000000..675a4b5
--- /dev/null
+++ b/src/hyperresearch/search/filters.py
@@ -0,0 +1,95 @@
+"""Structured field filter builder for search queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SearchFilters:
+ tags: list[str] | None = None
+ status: str | None = None
+ note_type: str | None = None
+ after: str | None = None
+ before: str | None = None
+ path_glob: str | None = None
+ parent: str | None = None
+ min_words: int | None = None
+ max_words: int | None = None
+ # Graph-aware filters
+ linked_from: str | None = None # Only notes linked FROM this note ID
+ linked_to: str | None = None # Only notes that link TO this note ID
+ min_inbound: int | None = None # Minimum inbound link count
+ has_backlinks: bool | None = None # Must have at least one inbound link
+
+ def to_sql(self, table_alias: str = "n") -> tuple[str, list]:
+ """Build SQL WHERE clauses and parameters."""
+ clauses: list[str] = []
+ params: list = []
+
+ if self.tags:
+ for tag in self.tags:
+ clauses.append(
+ f"{table_alias}.id IN (SELECT note_id FROM tags WHERE tag = ?)"
+ )
+ params.append(tag.lower())
+
+ if self.status:
+ clauses.append(f"{table_alias}.status = ?")
+ params.append(self.status)
+
+ if self.note_type:
+ clauses.append(f"{table_alias}.type = ?")
+ params.append(self.note_type)
+
+ if self.after:
+ clauses.append(f"{table_alias}.created >= ?")
+ params.append(self.after)
+
+ if self.before:
+ clauses.append(f"{table_alias}.created <= ?")
+ params.append(self.before)
+
+ if self.path_glob:
+ clauses.append(f"{table_alias}.path GLOB ?")
+ params.append(self.path_glob)
+
+ if self.parent:
+ clauses.append(f"{table_alias}.parent = ?")
+ params.append(self.parent)
+
+ if self.min_words is not None:
+ clauses.append(f"{table_alias}.word_count >= ?")
+ params.append(self.min_words)
+
+ if self.max_words is not None:
+ clauses.append(f"{table_alias}.word_count <= ?")
+ params.append(self.max_words)
+
+ # Graph-aware filters
+ if self.linked_from:
+ clauses.append(
+ f"{table_alias}.id IN (SELECT target_id FROM links WHERE source_id = ? AND target_id IS NOT NULL)"
+ )
+ params.append(self.linked_from)
+
+ if self.linked_to:
+ clauses.append(
+ f"{table_alias}.id IN (SELECT source_id FROM links WHERE target_id = ?)"
+ )
+ params.append(self.linked_to)
+
+ if self.min_inbound is not None:
+ clauses.append(
+ f"{table_alias}.id IN (SELECT target_id FROM links WHERE target_id IS NOT NULL "
+ f"GROUP BY target_id HAVING COUNT(*) >= ?)"
+ )
+ params.append(self.min_inbound)
+
+ if self.has_backlinks is True:
+ clauses.append(
+ f"{table_alias}.id IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)"
+ )
+
+ where = " AND ".join(clauses) if clauses else "1=1"
+ return where, params
diff --git a/src/hyperresearch/search/fts.py b/src/hyperresearch/search/fts.py
new file mode 100644
index 0000000..abb2fb6
--- /dev/null
+++ b/src/hyperresearch/search/fts.py
@@ -0,0 +1,139 @@
+"""FTS5 full-text search engine."""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+
+from hyperresearch.search.filters import SearchFilters
+
+
+def _split_alphanum(word: str) -> list[str]:
+ """Split words where letters meet digits: 'mamba3' -> ['mamba', '3'],
+ 'gpt4o' -> ['gpt', '4', 'o'], 'llama3.1' -> ['llama', '3', '1'].
+ """
+ # Insert space at letter/digit boundaries
+ split = re.sub(r'([a-zA-Z])(\d)', r'\1 \2', word)
+ split = re.sub(r'(\d)([a-zA-Z])', r'\1 \2', split)
+ # Also split on dots/hyphens between digits (3.1 -> 3 1)
+ split = re.sub(r'(\d)[.\-](\d)', r'\1 \2', split)
+ return split.split()
+
+
+def preprocess_query(raw: str) -> str:
+ """Transform user query into FTS5 query syntax.
+
+ - Simple words get prefix matching: 'python async' -> 'python* async*'
+ - Glued alphanumeric split: 'mamba3' -> 'mamba 3', 'gpt4o' -> 'gpt 4 o'
+ - Quoted phrases stay exact: '"async await"' stays as-is
+ - Handles special FTS5 operators: AND, OR, NOT, NEAR
+ """
+ if any(op in raw.upper() for op in (" AND ", " OR ", " NOT ", " NEAR(")):
+ return raw
+
+ parts = re.split(r'(".*?")', raw)
+ processed = []
+ for part in parts:
+ if part.startswith('"'):
+ processed.append(part)
+ else:
+ words = part.strip().split()
+ for word in words:
+ if word:
+ clean = re.sub(r'[*^():{}]', '', word)
+ if not clean:
+ continue
+ # Split glued alphanumeric (mamba3 -> mamba + 3)
+ subwords = _split_alphanum(clean)
+ for sw in subwords:
+ if sw:
+ processed.append(f'"{sw}"*')
+ return " ".join(processed)
+
+
+def search_fts(
+ conn: sqlite3.Connection,
+ query: str,
+ *,
+ filters: SearchFilters | None = None,
+ limit: int = 20,
+ offset: int = 0,
+ include_index: bool = False,
+ ranking: dict | None = None,
+) -> list[dict]:
+ """Execute a full-text search against the notes_fts table."""
+ fts_query = preprocess_query(query)
+
+ filter_clause = ""
+ filter_params: list = []
+ if filters:
+ where, filter_params = filters.to_sql("n")
+ if where != "1=1":
+ filter_clause = f"AND {where}"
+
+ # Exclude auto-generated index pages by default
+ index_clause = "" if include_index else "AND n.type != 'index'"
+
+ # BM25 column weights from config (id=unindexed=0, title, body, tags, aliases)
+ w = ranking or {}
+ tw = w.get("title_weight", 10.0)
+ bw = w.get("body_weight", 1.0)
+ tgw = w.get("tags_weight", 5.0)
+ aw = w.get("aliases_weight", 3.0)
+
+ sql = f"""
+ SELECT
+ n.id, n.title, n.path, n.status, n.type,
+ n.created, n.updated, n.word_count, n.summary,
+ snippet(notes_fts, 2, '>>>', '<<<', '...', 64) as snippet,
+ bm25(notes_fts, 0.0, {tw}, {bw}, {tgw}, {aw}) as score,
+ (SELECT GROUP_CONCAT(t.tag, ',') FROM tags t WHERE t.note_id = n.id) as tag_list
+ FROM notes_fts fts
+ JOIN notes n ON fts.id = n.id
+ WHERE notes_fts MATCH ?
+ {filter_clause}
+ {index_clause}
+ ORDER BY score
+ LIMIT ? OFFSET ?
+ """
+
+ params = [fts_query, *filter_params, limit, offset]
+
+ try:
+ rows = conn.execute(sql, params).fetchall()
+ except sqlite3.OperationalError:
+ return []
+
+ results = []
+ for row in rows:
+ tag_list = row["tag_list"].split(",") if row["tag_list"] else []
+ results.append({
+ "id": row["id"],
+ "title": row["title"],
+ "path": row["path"],
+ "status": row["status"],
+ "type": row["type"],
+ "tags": tag_list,
+ "created": row["created"],
+ "updated": row["updated"],
+ "word_count": row["word_count"],
+ "summary": row["summary"],
+ "score": abs(row["score"]),
+ "snippet": row["snippet"] or "",
+ })
+
+ # Apply status-based ranking adjustments
+ if ranking:
+ boost_evergreen = ranking.get("boost_evergreen", 1.0)
+ penalize_deprecated = ranking.get("penalize_deprecated", 1.0)
+ penalize_stale = ranking.get("penalize_stale", 1.0)
+ for r in results:
+ if r["status"] == "evergreen":
+ r["score"] *= boost_evergreen
+ elif r["status"] == "deprecated":
+ r["score"] *= penalize_deprecated
+ elif r["status"] == "stale":
+ r["score"] *= penalize_stale
+ results.sort(key=lambda x: x["score"], reverse=True)
+
+ return results
diff --git a/src/hyperresearch/serve/__init__.py b/src/hyperresearch/serve/__init__.py
new file mode 100644
index 0000000..5debc08
--- /dev/null
+++ b/src/hyperresearch/serve/__init__.py
@@ -0,0 +1 @@
+"""Lightweight web UI for browsing hyperresearch vaults."""
diff --git a/src/hyperresearch/serve/renderer.py b/src/hyperresearch/serve/renderer.py
new file mode 100644
index 0000000..d438af2
--- /dev/null
+++ b/src/hyperresearch/serve/renderer.py
@@ -0,0 +1,124 @@
+"""Markdown to HTML renderer with [[wiki-link]] resolution."""
+
+from __future__ import annotations
+
+import html
+import re
+
+# Simple markdown patterns
+MD_PATTERNS = [
+ # Headers
+ (re.compile(r"^######\s+(.+)$", re.MULTILINE), r"<h6>\1</h6>"),
+ (re.compile(r"^#####\s+(.+)$", re.MULTILINE), r"<h5>\1</h5>"),
+ (re.compile(r"^####\s+(.+)$", re.MULTILINE), r"<h4>\1</h4>"),
+ (re.compile(r"^###\s+(.+)$", re.MULTILINE), r"<h3>\1</h3>"),
+ (re.compile(r"^##\s+(.+)$", re.MULTILINE), r"<h2>\1</h2>"),
+ (re.compile(r"^#\s+(.+)$", re.MULTILINE), r"<h1>\1</h1>"),
+ # Bold/italic
+ (re.compile(r"\*\*\*(.+?)\*\*\*"), r"<strong><em>\1</em></strong>"),
+ (re.compile(r"\*\*(.+?)\*\*"), r"<strong>\1</strong>"),
+ (re.compile(r"\*(.+?)\*"), r"<em>\1</em>"),
+ # Code
+ (re.compile(r"`([^`]+)`"), r"<code>\1</code>"),
+ # Links
+ (re.compile(r"\[([^\]]+)\]\(([^)]+)\)"), r'<a href="\2">\1</a>'),
+ # Images
+ (re.compile(r"!\[([^\]]*)\]\(([^)]+)\)"), r'<img src="\2" alt="\1">'),
+ # Horizontal rule
+ (re.compile(r"^---+$", re.MULTILINE), r"<hr>"),
+ # Blockquotes
+ (re.compile(r"^>\s*(.+)$", re.MULTILINE), r"<blockquote>\1</blockquote>"),
+]
+
+
+def render_markdown(body: str) -> str:
+ """Convert markdown body to HTML, resolving [[wiki-links]]."""
+ # Escape HTML first
+ text = html.escape(body)
+
+ # Handle code blocks (preserve them)
+ code_blocks = []
+ def save_code_block(m):
+ code_blocks.append(m.group(0))
+ return f"\x00CODE{len(code_blocks) - 1}\x00"
+
+ text = re.sub(r"```(\w*)\n(.*?)```", save_code_block, text, flags=re.DOTALL)
+
+ # Apply markdown patterns
+ for pattern, replacement in MD_PATTERNS:
+ text = pattern.sub(replacement, text)
+
+ # Wiki links: [[target|display]] or [[target]]
+ def replace_wiki_link(m):
+ full = m.group(0)
+ # Unescape the brackets that html.escape would have converted
+ inner = full[2:-2] # strip [[ and ]]
+ if "|" in inner:
+ target, display = inner.split("|", 1)
+ else:
+ target = display = inner
+ target = target.strip()
+ display = display.strip()
+ return f'<a href="/note/{target}" class="wiki-link">{display}</a>'
+
+ text = re.sub(r"\[\[([^\]]+)\]\]", replace_wiki_link, text)
+
+ # Lists (simple)
+ text = re.sub(r"^- (.+)$", r"<li>\1</li>", text, flags=re.MULTILINE)
+ text = re.sub(r"(<li>.*</li>\n?)+", lambda m: f"<ul>{m.group(0)}</ul>", text)
+
+ # Tables
+ lines = text.split("\n")
+ in_table = False
+ table_lines = []
+ result_lines = []
+ for line in lines:
+ if "|" in line and line.strip().startswith("|"):
+ if not in_table:
+ in_table = True
+ table_lines = []
+ table_lines.append(line)
+ else:
+ if in_table:
+ result_lines.append(_render_table(table_lines))
+ in_table = False
+ table_lines = []
+ result_lines.append(line)
+ if in_table:
+ result_lines.append(_render_table(table_lines))
+ text = "\n".join(result_lines)
+
+ # Restore code blocks
+ for i, block in enumerate(code_blocks):
+ html.escape(block)
+ lang_match = re.match(r"```(\w+)\n", block)
+ lang = lang_match.group(1) if lang_match else ""
+ code_content = re.sub(r"```\w*\n|```", "", block)
+ code_html = f'<pre><code class="language-{lang}">{html.escape(code_content)}</code></pre>'
+ text = text.replace(f"\x00CODE{i}\x00", code_html)
+
+ # Paragraphs: wrap standalone lines
+ text = re.sub(r"\n\n+", "\n</p>\n<p>\n", text)
+ if not text.startswith("<"):
+ text = "<p>\n" + text
+ if not text.rstrip().endswith(">"):
+ text = text + "\n</p>"
+
+ return text
+
+
+def _render_table(lines: list[str]) -> str:
+ """Render a markdown table to HTML."""
+ if len(lines) < 2:
+ return "\n".join(lines)
+
+ rows = []
+ for i, line in enumerate(lines):
+ cells = [c.strip() for c in line.strip("|").split("|")]
+ if i == 1 and all(re.match(r"^[-:]+$", c.strip()) for c in cells):
+ continue # Skip separator row
+ tag = "th" if i == 0 else "td"
+ row = "".join(f"<{tag}>{c}</{tag}>" for c in cells)
+ rows.append(f"<tr>{row}</tr>")
+
+ return f'<table class="md-table">{"".join(rows)}</table>'
diff --git a/src/hyperresearch/serve/server.py b/src/hyperresearch/serve/server.py
new file mode 100644
index 0000000..46b2707
--- /dev/null
+++ b/src/hyperresearch/serve/server.py
@@ -0,0 +1,588 @@
+"""Lightweight HTTP server for browsing hyperresearch vaults."""
+
+from __future__ import annotations
+
+import html as html_mod
+import json
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from hyperresearch.serve.renderer import render_markdown
+
+# -- Vintage cream & dark brown theme --
+CSS = """
+:root {
+ --nav-width: 300px;
+ --bg: #fdf6ec;
+ --bg-alt: #f5ead6;
+ --fg: #3b2f1e;
+ --fg-dim: #7a6b57;
+ --accent: #8b5e3c;
+ --accent-light: #c4956a;
+ --link: #6b4226;
+ --link-hover: #8b5e3c;
+ --nav-bg: #2c1e0f;
+ --nav-fg: #e8d5b8;
+ --nav-link: #d4b896;
+ --nav-heading: #f0e0c8;
+ --border: #d4c4a8;
+ --tag-bg: #e8d5b8;
+ --tag-fg: #5a3e24;
+ --code-bg: #efe3cf;
+ --pre-bg: #2c1e0f;
+ --pre-fg: #e8d5b8;
+}
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+ line-height: 1.6; color: var(--fg); background: var(--bg); }
+a { color: var(--link); text-decoration: none; border-bottom: 1px solid transparent; }
+a:hover { border-bottom-color: var(--accent); }
+.wiki-link { color: var(--accent); font-weight: 600; }
+
+.layout { display: flex; min-height: 100vh; }
+nav { width: var(--nav-width); min-width: 200px; max-width: 500px;
+ background: var(--nav-bg); color: var(--nav-fg); padding: 1.2rem;
+ position: fixed; height: 100vh; overflow-y: auto; resize: horizontal; overflow-x: hidden;
+ display: flex; flex-direction: column; }
+nav .nav-top { flex: 1; overflow-y: auto; min-height: 0; }
+nav .nav-bottom { flex-shrink: 0; padding-top: 0.8rem; margin-top: 0.5rem;
+ border-top: 1px solid rgba(255,255,255,0.1); }
+nav .nav-bottom a { font-size: 0.9rem; padding: 6px 0; }
+nav a { color: var(--nav-link); display: block; padding: 3px 0; font-size: 0.82rem;
+ white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+ border: none; }
+nav a:hover { color: #fff; }
+nav h3 { color: var(--nav-heading); margin: 1.2rem 0 0.4rem 0; font-size: 0.7rem;
+ text-transform: uppercase; letter-spacing: 0.08em;
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+nav .brand { font-size: 1.2rem; font-weight: bold; color: #fff;
+ letter-spacing: 0.02em; }
+nav .brand-sub { font-size: 0.7rem; color: var(--fg-dim); margin-top: -0.2rem; margin-bottom: 1rem;
+ font-family: -apple-system, sans-serif; }
+.nav-handle { width: 5px; position: fixed; left: var(--nav-width); top: 0; height: 100vh;
+ cursor: col-resize; background: transparent; z-index: 10; }
+.nav-handle:hover { background: var(--accent-light); }
+
+main { margin-left: var(--nav-width); padding: 2.5rem 3rem; max-width: 860px; flex: 1; }
+main h1 { margin-bottom: 0.5rem; font-weight: 700; color: var(--fg); }
+main h2 { margin-top: 2rem; margin-bottom: 0.5rem; border-bottom: 1px solid var(--border);
+ padding-bottom: 0.3rem; color: var(--accent); }
+main h3 { margin-top: 1.2rem; color: var(--fg); }
+
+.meta { color: var(--fg-dim); font-size: 0.82rem; margin-bottom: 1.5rem;
+ font-family: -apple-system, sans-serif; }
+.meta .tag { background: var(--tag-bg); color: var(--tag-fg); padding: 2px 8px; border-radius: 3px;
+ font-size: 0.72rem; margin-right: 4px; }
+.meta .status { background: var(--bg-alt); color: var(--accent); padding: 2px 8px; border-radius: 3px;
+ font-size: 0.72rem; border: 1px solid var(--border); }
+.meta .status.deprecated { background: #f0d0c0; color: #8b3a2a; }
+.meta .status.draft { background: #f5e6c8; color: #7a5a2a; }
+
+.backlinks { background: var(--bg-alt); border: 1px solid var(--border);
+ border-radius: 6px; padding: 1rem; margin-top: 2rem; }
+.backlinks h3 { font-size: 0.85rem; margin-bottom: 0.5rem; color: var(--accent); }
+.backlinks li { font-size: 0.82rem; }
+
+code { background: var(--code-bg); padding: 2px 6px; border-radius: 3px; font-size: 0.88em; }
+pre { background: var(--pre-bg); color: var(--pre-fg); padding: 1rem; border-radius: 6px;
+ overflow-x: auto; margin: 1rem 0; font-size: 0.88rem; }
+pre code { background: none; padding: 0; color: inherit; }
+
+.md-table { border-collapse: collapse; margin: 1rem 0; }
+.md-table th, .md-table td { border: 1px solid var(--border); padding: 8px 12px; text-align: left; }
+.md-table th { background: var(--bg-alt); font-weight: 600; }
+.md-table tr:nth-child(even) { background: var(--bg-alt); }
+
+blockquote { border-left: 3px solid var(--accent-light); padding-left: 1rem;
+ color: var(--fg-dim); margin: 1rem 0; font-style: italic; }
+ul { margin: 0.5rem 0 0.5rem 1.5rem; }
+li { margin: 0.2rem 0; }
+hr { border: none; border-top: 1px solid var(--border); margin: 1.5rem 0; }
+
+.search-box { margin-bottom: 1rem; }
+.search-box input { width: 100%; padding: 7px 10px; border: 1px solid #5a4030;
+ border-radius: 4px; background: #1e1208; color: var(--nav-fg);
+ font-family: -apple-system, sans-serif; font-size: 0.85rem; }
+.search-box input::placeholder { color: #7a6b57; }
+.results .result { margin-bottom: 1.2rem; }
+.results .result .title { font-weight: 600; }
+.results .result .snippet { color: var(--fg-dim); font-size: 0.82rem;
+ font-family: -apple-system, sans-serif; }
+mark { background: #f0d8a0; color: var(--fg); padding: 1px 2px; border-radius: 2px; }
+
+/* Graph page */
+.graph-container { position: relative; width: 100%; height: calc(100vh - 120px);
+ background: var(--bg-alt); border: 1px solid var(--border); border-radius: 6px; }
+.graph-fullpage { height: 100vh; border: none; border-radius: 0;
+ position: fixed; top: 0; left: var(--nav-width); right: 0; bottom: 0;
+ width: calc(100vw - var(--nav-width)); z-index: 1; }
+.graph-container canvas { width: 100%; height: 100%; cursor: grab; }
+.graph-container canvas:active { cursor: grabbing; }
+.graph-search { position: absolute; top: 12px; right: 12px; z-index: 5;
+ padding: 6px 10px; border: 1px solid var(--border); border-radius: 4px;
+ background: var(--bg); color: var(--fg); font-size: 0.85rem; width: 200px; }
+.graph-info { position: absolute; bottom: 12px; left: 12px; z-index: 5;
+ background: var(--bg); border: 1px solid var(--border); border-radius: 4px;
+ padding: 6px 10px; font-size: 0.78rem; color: var(--fg-dim);
+ font-family: -apple-system, sans-serif; pointer-events: none; }
+"""
+
+FAVICON = (
+ "data:image/svg+xml,"
+ "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'>"
+ "<rect x='10' y='20' width='80' height='65' rx='4' fill='%232c1e0f' stroke='%238b5e3c' stroke-width='3'/>"
+ "<rect x='20' y='10' width='60' height='15' rx='3' fill='%238b5e3c'/>"
+ "<line x1='25' y1='42' x2='75' y2='42' stroke='%23d4b896' stroke-width='2'/>"
+ "<line x1='25' y1='52' x2='65' y2='52' stroke='%23d4b896' stroke-width='2'/>"
+ "<line x1='25' y1='62' x2='70' y2='62' stroke='%23d4b896' stroke-width='2'/>"
+ "<circle cx='72' cy='72' r='8' fill='%238b5e3c'/>"
+ "<line x1='72' y1='67' x2='72' y2='77' stroke='%23fdf6ec' stroke-width='2'/>"
+ "<line x1='67' y1='72' x2='77' y2='72' stroke='%23fdf6ec' stroke-width='2'/>"
+ "</svg>"
+)
+
+DRAG_JS = """
+<script>
+(function() {
+ var handle = document.querySelector('.nav-handle');
+ var nav = document.querySelector('nav');
+ var dragging = false;
+ if (!handle) return;
+ handle.addEventListener('mousedown', function(e) { dragging = true; e.preventDefault(); });
+ document.addEventListener('mousemove', function(e) {
+ if (!dragging) return;
+ var w = Math.min(Math.max(e.clientX, 200), 500);
+ document.documentElement.style.setProperty('--nav-width', w + 'px');
+ nav.style.width = w + 'px';
+ });
+ document.addEventListener('mouseup', function() { dragging = false; });
+})();
+</script>
+"""
+
+GRAPH_JS = """
+<script>
+(function() {
+ var canvas = document.getElementById('graph-canvas');
+ var ctx = canvas.getContext('2d');
+ var info = document.getElementById('graph-info');
+ var searchBox = document.getElementById('graph-search');
+ var nodes = [], edges = [], nodeMap = {};
+ var W, H, scale = 1, panX = 0, panY = 0, dragging = false, dragX = 0, dragY = 0;
+ var hoverNode = null, searchTerm = '';
+
+ function resize() { W = canvas.width = canvas.parentElement.clientWidth; H = canvas.height = canvas.parentElement.clientHeight; }
+ window.addEventListener('resize', resize);
+ resize();
+
+ fetch('/api/graph').then(r => r.json()).then(function(data) {
+ nodes = data.nodes; edges = data.edges;
+ // Center around origin
+ nodes.forEach(function(n, i) { nodeMap[n.id] = i; n.x = (Math.random()-0.5)*800; n.y = (Math.random()-0.5)*800; n.vx = 0; n.vy = 0; });
+ simulate();
+ });
+
+ function fitToScreen() {
+ if (nodes.length === 0) return;
+ var minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+ nodes.forEach(function(n) {
+ if (n.x < minX) minX = n.x; if (n.x > maxX) maxX = n.x;
+ if (n.y < minY) minY = n.y; if (n.y > maxY) maxY = n.y;
+ });
+ var gw = maxX - minX + 100, gh = maxY - minY + 100;
+ var cx = (minX + maxX) / 2, cy = (minY + maxY) / 2;
+ scale = Math.min(W / gw, H / gh) * 0.9;
+ scale = Math.min(Math.max(scale, 0.02), 3);
+ panX = -cx;
+ panY = -cy;
+ }
+
+ function simulate() {
+ var alpha = 1.0;
+ function tick() {
+ if (alpha < 0.001) { fitToScreen(); draw(); return; }
+ alpha *= 0.98;
+ // Repulsion
+ for (var i = 0; i < nodes.length; i++) {
+ for (var j = i+1; j < nodes.length; j++) {
+ var dx = nodes[j].x - nodes[i].x, dy = nodes[j].y - nodes[i].y;
+ var d2 = dx*dx + dy*dy + 1;
+ var f = 800 / d2 * alpha;
+ nodes[i].vx -= dx * f; nodes[i].vy -= dy * f;
+ nodes[j].vx += dx * f; nodes[j].vy += dy * f;
+ }
+ }
+ // Attraction along edges
+ edges.forEach(function(e) {
+ var si = nodeMap[e[0]], ti = nodeMap[e[1]];
+ if (si === undefined || ti === undefined) return;
+ var dx = nodes[ti].x - nodes[si].x, dy = nodes[ti].y - nodes[si].y;
+ var d = Math.sqrt(dx*dx + dy*dy) + 1;
+ var f = (d - 120) * 0.005 * alpha;
+ nodes[si].vx += dx/d * f; nodes[si].vy += dy/d * f;
+ nodes[ti].vx -= dx/d * f; nodes[ti].vy -= dy/d * f;
+ });
+ // Center gravity
+ nodes.forEach(function(n) {
+ n.vx += (0 - n.x) * 0.0005 * alpha;
+ n.vy += (0 - n.y) * 0.0005 * alpha;
+ n.vx *= 0.85; n.vy *= 0.85;
+ n.x += n.vx; n.y += n.vy;
+ });
+ draw();
+ requestAnimationFrame(tick);
+ }
+ tick();
+ }
+
+ function toScreen(x, y) { return [(x + panX) * scale + W/2, (y + panY) * scale + H/2]; }
+ function toWorld(sx, sy) { return [(sx - W/2) / scale - panX, (sy - H/2) / scale - panY]; }
+
+ function draw() {
+ ctx.clearRect(0, 0, W, H);
+ ctx.save();
+ ctx.translate(W/2, H/2);
+ ctx.scale(scale, scale);
+ ctx.translate(panX, panY);
+
+ // Edges
+ ctx.strokeStyle = 'rgba(139,94,60,0.12)';
+ ctx.lineWidth = 0.5 / scale;
+ edges.forEach(function(e) {
+ var si = nodeMap[e[0]], ti = nodeMap[e[1]];
+ if (si === undefined || ti === undefined) return;
+ var s = nodes[si], t = nodes[ti];
+ var highlight = hoverNode && (s.id === hoverNode.id || t.id === hoverNode.id);
+ if (highlight) { ctx.strokeStyle = 'rgba(139,94,60,0.6)'; ctx.lineWidth = 1.5 / scale; }
+ ctx.beginPath(); ctx.moveTo(s.x, s.y); ctx.lineTo(t.x, t.y); ctx.stroke();
+ if (highlight) { ctx.strokeStyle = 'rgba(139,94,60,0.12)'; ctx.lineWidth = 0.5 / scale; }
+ });
+
+ // Nodes
+ var sl = searchTerm.toLowerCase();
+ nodes.forEach(function(n) {
+ var r = Math.max(3, Math.min(20, 3 + Math.pow(n.inbound, 0.7) * 1.5));
+ var isHover = hoverNode && n.id === hoverNode.id;
+ var isConnected = hoverNode && n.connected && n.connected.has(hoverNode.id);
+ var isSearch = sl && n.title.toLowerCase().includes(sl);
+ var alpha = (hoverNode && !isHover && !isConnected) ? 0.15 : 1;
+ if (isSearch) alpha = 1;
+
+ ctx.globalAlpha = alpha;
+ ctx.fillStyle = isSearch ? '#c4652a' : isHover ? '#6b4226' : n.status === 'evergreen' ? '#8b5e3c' : n.status === 'draft' ? '#b8a080' : '#a08060';
+ ctx.beginPath(); ctx.arc(n.x, n.y, r / scale, 0, Math.PI * 2); ctx.fill();
+
+ if ((isHover || isSearch) && scale > 0.1) {
+ ctx.fillStyle = '#3b2f1e';
+ ctx.font = (11 / scale) + 'px -apple-system, sans-serif';
+ ctx.fillText(n.title.substring(0, 40), n.x + r/scale + 4/scale, n.y + 3/scale);
+ }
+ ctx.globalAlpha = 1;
+ });
+
+ ctx.restore();
+ if (hoverNode) info.textContent = hoverNode.title + ' (' + hoverNode.inbound + ' inbound)';
+ else info.textContent = nodes.length + ' notes, ' + edges.length + ' links';
+ }
+
+ // Build connectivity sets for hover highlighting
+ function buildConnections() {
+ nodes.forEach(function(n) { n.connected = new Set(); });
+ edges.forEach(function(e) {
+ var si = nodeMap[e[0]], ti = nodeMap[e[1]];
+ if (si !== undefined && ti !== undefined) {
+ nodes[si].connected.add(e[1]);
+ nodes[ti].connected.add(e[0]);
+ }
+ });
+ }
+ setTimeout(buildConnections, 1000);
+
+ // Mouse interaction
+ var mouseDown = false, lastMX = 0, lastMY = 0;
+ canvas.addEventListener('wheel', function(e) {
+ e.preventDefault();
+ var factor = e.deltaY > 0 ? 0.9 : 1.1;
+ scale = Math.min(Math.max(scale * factor, 0.02), 5);
+ draw();
+ });
+ canvas.addEventListener('mousedown', function(e) { mouseDown = true; lastMX = e.clientX; lastMY = e.clientY; });
+ canvas.addEventListener('mousemove', function(e) {
+ if (mouseDown) {
+ panX += (e.clientX - lastMX) / scale;
+ panY += (e.clientY - lastMY) / scale;
+ lastMX = e.clientX; lastMY = e.clientY;
+ draw();
+ } else {
+ // Hit test for hover
+ var rect = canvas.getBoundingClientRect();
+ var wp = toWorld(e.clientX - rect.left, e.clientY - rect.top);
+ hoverNode = null;
+ for (var i = 0; i < nodes.length; i++) {
+ var dx = nodes[i].x - wp[0], dy = nodes[i].y - wp[1];
+ if (dx*dx + dy*dy < 100) { hoverNode = nodes[i]; break; }
+ }
+ canvas.style.cursor = hoverNode ? 'pointer' : 'grab';
+ draw();
+ }
+ });
+ canvas.addEventListener('mouseup', function() { mouseDown = false; });
+ canvas.addEventListener('click', function() {
+ if (hoverNode) window.location.href = '/note/' + hoverNode.id;
+ });
+
+ searchBox.addEventListener('input', function() { searchTerm = this.value; draw(); });
+})();
+</script>
+"""
+
+
+class HyperresearchHandler(BaseHTTPRequestHandler):
+ vault = None
+ _db = None
+
+ @property
+ def db(self):
+ if self.__class__._db is None:
+ import sqlite3
+ self.__class__._db = sqlite3.connect(str(self.__class__.vault.db_path), check_same_thread=False)
+ self.__class__._db.row_factory = sqlite3.Row
+ return self.__class__._db
+
+ def do_GET(self):
+ parsed = urllib.parse.urlparse(self.path)
+ path = parsed.path
+ query = urllib.parse.parse_qs(parsed.query)
+
+ if path == "/" or path == "":
+ self._serve_index()
+ elif path.startswith("/note/"):
+ note_id = urllib.parse.unquote(path[6:])
+ self._serve_note(note_id)
+ elif path.startswith("/tag/"):
+ tag = urllib.parse.unquote(path[5:])
+ self._serve_tag(tag)
+ elif path == "/tags":
+ self._serve_tags()
+ elif path == "/search":
+ q = query.get("q", [""])[0]
+ self._serve_search(q)
+ elif path == "/graph":
+ self._serve_graph()
+ elif path == "/api/graph":
+ self._serve_graph_api()
+ else:
+ self._send(404, "<h1>Not Found</h1>")
+
+ def _send(self, code: int, body_html: str, title: str = "Home", extra_head: str = "", extra_body: str = ""):
+ nav = self._build_nav()
+ full = f"""<!DOCTYPE html><html><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{title} | LLM-Hyperresearch</title>
+<link rel="icon" href="{FAVICON}">
+<style>{CSS}</style>{extra_head}</head>
+<body><div class="layout"><nav>{nav}</nav><div class="nav-handle"></div><main>{body_html}</main></div>{DRAG_JS}{extra_body}</body></html>"""
+ self.send_response(code)
+ self.send_header("Content-Type", "text/html; charset=utf-8")
+ self.end_headers()
+ self.wfile.write(full.encode("utf-8"))
+
+ def _send_json(self, data):
+ body = json.dumps(data)
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.end_headers()
+ self.wfile.write(body.encode("utf-8"))
+
+ def _build_nav(self) -> str:
+ vault = self.__class__.vault
+ name = vault.config.name
+ lines = [
+ '<div class="nav-top">',
+ '<div class="brand">LLM-Hyperresearch</div>',
+ f'<div class="brand-sub">{html_mod.escape(name)}</div>',
+ '<form action="/search"><div class="search-box">'
+ '<input type="text" name="q" placeholder="Search..."></div></form>',
+ '<a href="/">Home</a>',
+ '<a href="/tags">Tags</a>',
+ '<h3>Recent</h3>',
+ ]
+ rows = self.db.execute(
+ "SELECT id, title FROM notes WHERE type NOT IN ('index') "
+ "ORDER BY COALESCE(updated, created) DESC LIMIT 15"
+ ).fetchall()
+ for r in rows:
+ lines.append(f'<a href="/note/{html_mod.escape(r["id"])}">{html_mod.escape(r["title"])}</a>')
+ lines.append('</div>')
+ lines.append(
+ '<div class="nav-bottom">'
+ '<a href="/graph" title="Knowledge Graph" style="display:flex;align-items:center;gap:6px">'
+ '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+ '<circle cx="5" cy="6" r="2.5"/><circle cx="19" cy="6" r="2.5"/>'
+ '<circle cx="12" cy="18" r="2.5"/><circle cx="5" cy="18" r="2.5"/>'
+ '<circle cx="19" cy="18" r="2.5"/><circle cx="12" cy="10" r="2.5"/>'
+ '<line x1="7" y1="7" x2="10" y2="9"/><line x1="17" y1="7" x2="14" y2="9"/>'
+ '<line x1="12" y1="12.5" x2="12" y2="15.5"/>'
+ '<line x1="7" y1="17" x2="10" y2="16"/><line x1="17" y1="17" x2="14" y2="16"/>'
+ '</svg>Graph</a></div>'
+ )
+ return "\n".join(lines)
+
+ def _serve_index(self):
+ rows = self.db.execute(
+ "SELECT id, title, status, summary, word_count FROM notes "
+ "WHERE type NOT IN ('index') ORDER BY title"
+ ).fetchall()
+ body = "<h1>All Notes</h1>\n<ul>\n"
+ for r in rows:
+ summary = f' <span style="color:var(--fg-dim);font-size:0.85rem">-- {html_mod.escape(r["summary"] or "")}</span>' if r["summary"] else ""
+ body += f'<li><a href="/note/{html_mod.escape(r["id"])}">{html_mod.escape(r["title"])}</a>{summary}</li>\n'
+ body += "</ul>"
+ self._send(200, body, "Home")
+
+ def _serve_note(self, note_id: str):
+ row = self.db.execute(
+ "SELECT n.*, nc.body FROM notes n "
+ "JOIN note_content nc ON n.id = nc.note_id WHERE n.id = ?",
+ (note_id,),
+ ).fetchone()
+ if not row:
+ self._send(404, f"<h1>Note not found: {html_mod.escape(note_id)}</h1>")
+ return
+
+ tags = [r["tag"] for r in self.db.execute("SELECT tag FROM tags WHERE note_id = ?", (note_id,))]
+ backlinks = self.db.execute(
+ "SELECT l.source_id, n.title FROM links l "
+ "JOIN notes n ON l.source_id = n.id WHERE l.target_id = ? ORDER BY n.title",
+ (note_id,),
+ ).fetchall()
+
+ html_body = render_markdown(row["body"])
+ tags_html = " ".join(f'<a href="/tag/{html_mod.escape(t)}" class="tag">{html_mod.escape(t)}</a>' for t in tags)
+ status_class = row["status"]
+ meta = (
+ f'<div class="meta">'
+ f'<span class="status {status_class}">{html_mod.escape(row["status"])}</span> '
+ f'{tags_html} '
+ f'<span>{row["word_count"]} words</span>'
+ f'</div>'
+ )
+ bl_html = ""
+ if backlinks:
+ bl_items = "\n".join(
+ f'<li><a href="/note/{html_mod.escape(r["source_id"])}">{html_mod.escape(r["title"])}</a></li>' for r in backlinks
+ )
+ bl_html = f'<div class="backlinks"><h3>Backlinks</h3><ul>{bl_items}</ul></div>'
+ self._send(200, f"{meta}\n{html_body}\n{bl_html}", html_mod.escape(row["title"]))
+
+ def _serve_tag(self, tag: str):
+ rows = self.db.execute(
+ "SELECT n.id, n.title, n.status, n.summary FROM notes n "
+ "JOIN tags t ON n.id = t.note_id WHERE t.tag = ? ORDER BY n.title",
+ (tag,),
+ ).fetchall()
+ safe_tag = html_mod.escape(tag)
+ body = f"<h1>Tag: {safe_tag}</h1>\n<p>{len(rows)} notes</p>\n<ul>\n"
+ for r in rows:
+ summary = f' <span style="color:var(--fg-dim);font-size:0.85rem">-- {html_mod.escape(r["summary"] or "")}</span>' if r["summary"] else ""
+ body += f'<li><a href="/note/{html_mod.escape(r["id"])}">{html_mod.escape(r["title"])}</a>{summary}</li>\n'
+ body += "</ul>"
+ self._send(200, body, f"Tag: {safe_tag}")
+
+ def _serve_tags(self):
+ rows = self.db.execute(
+ "SELECT tag, COUNT(*) as c FROM tags GROUP BY tag ORDER BY c DESC"
+ ).fetchall()
+ body = "<h1>All Tags</h1>\n<ul>\n"
+ for r in rows:
+ body += f'<li><a href="/tag/{html_mod.escape(r["tag"])}">{html_mod.escape(r["tag"])}</a> ({r["c"]})</li>\n'
+ body += "</ul>"
+ self._send(200, body, "Tags")
+
+ def _serve_search(self, query: str):
+ safe_q = html_mod.escape(query)
+ body = f'<h1>Search: {safe_q}</h1>\n'
+ if not query:
+ body += "<p>Enter a search term.</p>"
+ self._send(200, body, "Search")
+ return
+
+ from hyperresearch.search.fts import search_fts
+ results = search_fts(self.db, query, limit=50)
+ body += f"<p>{len(results)} results</p>\n<div class='results'>\n"
+ for r in results:
+ snippet = r["snippet"].replace(">>>", "<mark>").replace("<<<", "</mark>")
+ body += (
+ f'<div class="result"><div class="title">'
+ f'<a href="/note/{html_mod.escape(r["id"])}">{html_mod.escape(r["title"])}</a></div>'
+ f'<div class="snippet">{snippet}</div></div>\n'
+ )
+ body += "</div>"
+ self._send(200, body, f"Search: {safe_q}")
+
+ def _serve_graph(self):
+ body = (
+ '<div class="graph-container graph-fullpage">'
+ '<canvas id="graph-canvas"></canvas>'
+ '<input type="text" class="graph-search" id="graph-search" placeholder="Filter nodes...">'
+ '<div class="graph-info" id="graph-info">Loading...</div>'
+ '</div>'
+ )
+ self._send(200, body, "Graph", extra_body=GRAPH_JS)
+
+ def _serve_graph_api(self):
+ nodes_rows = self.db.execute(
+ "SELECT n.id, n.title, n.status, n.word_count FROM notes n WHERE n.type NOT IN ('index')"
+ ).fetchall()
+ inbound_counts = {}
+ for r in self.db.execute(
+ "SELECT target_id, COUNT(*) as c FROM links WHERE target_id IS NOT NULL GROUP BY target_id"
+ ):
+ inbound_counts[r["target_id"]] = r["c"]
+
+ nodes = [
+ {"id": r["id"], "title": r["title"], "status": r["status"],
+ "words": r["word_count"], "inbound": inbound_counts.get(r["id"], 0)}
+ for r in nodes_rows
+ ]
+ edges_rows = self.db.execute(
+ "SELECT DISTINCT source_id, target_id FROM links WHERE target_id IS NOT NULL"
+ ).fetchall()
+ edges = [[r["source_id"], r["target_id"]] for r in edges_rows]
+
+ self._send_json({"nodes": nodes, "edges": edges})
+
+ def log_message(self, format, *args):
+ pass
+
+
+def run_server(vault, port: int = 8080, open_browser: bool = False):
+ import signal
+ import sys
+
+ HyperresearchHandler.vault = vault
+ server = HTTPServer(("127.0.0.1", port), HyperresearchHandler)
+ server.timeout = 0.5 # Check for Ctrl+C every 500ms
+ url = f"http://127.0.0.1:{port}"
+ print(f"Serving at {url}")
+ print("Press Ctrl+C to stop.\n")
+
+ if open_browser:
+ import webbrowser
+ webbrowser.open(url)
+
+ running = True
+
+ def _shutdown(sig, frame):
+ nonlocal running
+ running = False
+
+ signal.signal(signal.SIGINT, _shutdown)
+
+ while running:
+ server.handle_request()
+
+ print("\nStopped.")
+ server.server_close()
+ sys.exit(0)
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..505fc87
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,83 @@
+"""Shared test fixtures."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from hyperresearch.core.vault import Vault
+
+
+def tmp_vault(tmp_path: Path) -> Vault:
+ """Create a temporary vault for testing."""
+ vault = Vault.init(tmp_path / "test-vault", name="Test Vault")
+ return vault
+
+
+def seeded_vault(tmp_vault: Vault) -> Vault:
+ """A vault with sample notes pre-populated."""
+ from hyperresearch.core.note import write_note
+
+ # Create interconnected notes
+ write_note(
+ tmp_vault.notes_dir,
+ "Python Async Patterns",
+ body=(
+ "# Python Async Patterns\n\n"
+ "Python's async/await syntax enables concurrent I/O.\n\n"
+ "See also [[concurrency]] and [[rust-ownership]].\n"
+ ),
+ tags=["python", "async", "concurrency"],
+ status="evergreen",
+ parent="python",
+ summary="Guide to async/await in Python",
+ )
+
+ write_note(
+ tmp_vault.notes_dir,
+ "Rust Ownership",
+ body=(
+ "# Rust Ownership\n\n"
+ "Rust's ownership model ensures memory safety without GC.\n\n"
+ "Related: [[python-async-patterns]] and [[concurrency]].\n"
+ ),
+ tags=["rust", "memory", "concurrency"],
+ status="evergreen",
+ parent="rust",
+ summary="Rust's ownership and borrowing system",
+ )
+
+ write_note(
+ tmp_vault.notes_dir,
+ "Concurrency",
+ body=(
+ "# Concurrency\n\n"
+ "Fundamental patterns for concurrent programming.\n\n"
+ "- [[python-async-patterns]]\n"
+ "- [[rust-ownership]]\n"
+ "- [[nonexistent-topic]]\n"
+ ),
+ tags=["concurrency", "concepts"],
+ status="evergreen",
+ note_type="moc",
+ summary="Map of content for concurrency topics",
+ )
+
+ write_note(
+ tmp_vault.notes_dir,
+ "Orphan Note",
+ body="# Orphan\n\nThis note links to nothing and nothing links to it.\n",
+ tags=["test"],
+ status="draft",
+ )
+
+ # Sync to populate DB
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+
+ plan = compute_sync_plan(tmp_vault, force=True)
+ execute_sync(tmp_vault, plan)
+
+ return tmp_vault
diff --git a/tests/test_cli/__init__.py b/tests/test_cli/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_cli/test_commands.py b/tests/test_cli/test_commands.py
new file mode 100644
index 0000000..ad2af9b
--- /dev/null
+++ b/tests/test_cli/test_commands.py
@@ -0,0 +1,176 @@
+"""CLI integration tests using typer.testing.CliRunner."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from hyperresearch.cli import app
+
+runner = CliRunner()
+
+
+def vault_dir(tmp_path: Path) -> Path:
+ """Init a vault and return its path."""
+ result = runner.invoke(app, ["init", str(tmp_path / "kb"), "--name", "CLI Test"])
+ assert result.exit_code == 0
+ return tmp_path / "kb"
+
+
+def test_init(tmp_path: Path):
+ result = runner.invoke(app, ["init", str(tmp_path / "new-kb")])
+ assert result.exit_code == 0
+ assert "Initialized" in result.output
+
+
+def test_init_json(tmp_path: Path):
+ result = runner.invoke(app, ["init", str(tmp_path / "json-kb"), "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["ok"] is True
+ assert "vault_path" in data["data"]
+
+
+def test_init_double(tmp_path: Path):
+ runner.invoke(app, ["init", str(tmp_path / "dup")])
+ result = runner.invoke(app, ["init", str(tmp_path / "dup")])
+ assert result.exit_code == 1
+
+
+def test_version():
+ result = runner.invoke(app, ["--version"])
+ assert result.exit_code == 0
+ assert "hyperresearch v" in result.output
+
+
+def test_status(vault_dir: Path):
+ os.chdir(vault_dir)
+ result = runner.invoke(app, ["status"])
+ assert result.exit_code == 0
+ assert "CLI Test" in result.output
+
+
+def test_status_json(vault_dir: Path):
+ os.chdir(vault_dir)
+ result = runner.invoke(app, ["status", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["ok"] is True
+ assert data["data"]["vault_name"] == "CLI Test"
+
+
+def test_note_new_and_list(vault_dir: Path):
+ os.chdir(vault_dir)
+ result = runner.invoke(app, ["note", "new", "Test Note", "--tag", "test"])
+ assert result.exit_code == 0
+ assert "Created" in result.output
+
+ result = runner.invoke(app, ["sync"])
+ assert result.exit_code == 0
+
+ result = runner.invoke(app, ["note", "list", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["ok"] is True
+ assert data["count"] >= 1
+
+
+def test_note_show(vault_dir: Path):
+ os.chdir(vault_dir)
+ runner.invoke(app, ["note", "new", "Show Me", "--tag", "demo"])
+ runner.invoke(app, ["sync"])
+
+ result = runner.invoke(app, ["note", "show", "show-me", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["data"]["title"] == "Show Me"
+
+
+def test_note_tags(vault_dir: Path):
+ os.chdir(vault_dir)
+ runner.invoke(app, ["note", "new", "A", "--tag", "alpha"])
+ runner.invoke(app, ["note", "new", "B", "--tag", "beta"])
+ runner.invoke(app, ["sync"])
+
+ result = runner.invoke(app, ["tags", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ tags = {t["tag"] for t in data["data"]}
+ assert "alpha" in tags
+ assert "beta" in tags
+
+
+def test_search_text(vault_dir: Path):
+ os.chdir(vault_dir)
+ runner.invoke(app, ["note", "new", "Python Guide", "--tag", "python"])
+ runner.invoke(app, ["sync"])
+
+ result = runner.invoke(app, ["search", "python", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["data"]["total"] >= 1
+
+
+def test_graph_broken(vault_dir: Path):
+ os.chdir(vault_dir)
+ # Create a note with a broken link
+ (vault_dir / "research" / "notes" / "linker.md").write_text(
+ "---\ntitle: Linker\nid: linker\nstatus: draft\ntype: note\n---\n\nSee [[nowhere]]\n",
+ encoding="utf-8",
+ )
+ runner.invoke(app, ["sync"])
+
+ result = runner.invoke(app, ["graph", "broken", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["count"] >= 1
+
+
+def test_lint(vault_dir: Path):
+ os.chdir(vault_dir)
+ runner.invoke(app, ["note", "new", "Lint Test"])
+ runner.invoke(app, ["sync"])
+
+ result = runner.invoke(app, ["lint", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "issues" in data["data"]
+ assert "summary" in data["data"]
+
+
+def test_sync_dry_run(vault_dir: Path):
+ os.chdir(vault_dir)
+ runner.invoke(app, ["note", "new", "Dry Run"])
+
+ result = runner.invoke(app, ["sync", "--dry-run", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "to_add" in data["data"]
+
+
+def test_index_build(vault_dir: Path):
+ os.chdir(vault_dir)
+ runner.invoke(app, ["note", "new", "Indexed Note", "--tag", "idx"])
+ runner.invoke(app, ["sync"])
+
+ result = runner.invoke(app, ["index", "build"])
+ assert result.exit_code == 0
+ assert "Built" in result.output
+
+ result = runner.invoke(app, ["index", "list"])
+ assert result.exit_code == 0
+
+
+def test_export_json(vault_dir: Path):
+ os.chdir(vault_dir)
+ runner.invoke(app, ["note", "new", "Export Me"])
+ runner.invoke(app, ["sync"])
+
+ result = runner.invoke(app, ["export", "json", "--output", "exports/test.json"])
+ assert result.exit_code == 0
+ assert (vault_dir / "exports" / "test.json").exists()
diff --git a/tests/test_cli/test_note_ops.py b/tests/test_cli/test_note_ops.py
new file mode 100644
index 0000000..bc1be8f
--- /dev/null
+++ b/tests/test_cli/test_note_ops.py
@@ -0,0 +1,70 @@
+"""Tests for note mv, edit, rm CLI operations."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from hyperresearch.cli import app
+
+runner = CliRunner()
+
+
+def vault_with_notes(tmp_path: Path) -> Path:
+ vault_dir = tmp_path / "kb"
+ runner.invoke(app, ["init", str(vault_dir)])
+ os.chdir(vault_dir)
+ runner.invoke(app, ["note", "new", "Alpha Note", "--tag", "test"])
+ runner.invoke(app, ["note", "new", "Beta Note", "--tag", "test"])
+ runner.invoke(app, ["sync"])
+ return vault_dir
+
+
+def test_note_rm_json(vault_with_notes):
+ result = runner.invoke(app, ["note", "rm", "alpha-note", "--force", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["ok"] is True
+ assert data["data"]["deleted"] == "alpha-note"
+
+
+def test_note_rm_nonexistent(vault_with_notes):
+ result = runner.invoke(app, ["note", "rm", "nonexistent", "--force", "--json"])
+ assert result.exit_code == 1
+
+
+def test_note_mv(vault_with_notes):
+ result = runner.invoke(
+ app, ["note", "mv", "beta-note", "notes/moved/beta-note.md", "--json"]
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["data"]["new_path"] == "notes/moved/beta-note.md"
+ assert (vault_with_notes / "notes" / "moved" / "beta-note.md").exists()
+
+
+def test_note_show_raw(vault_with_notes):
+ result = runner.invoke(app, ["note", "show", "alpha-note", "--raw"])
+ assert result.exit_code == 0
+ assert "---" in result.output
+ assert "Alpha Note" in result.output
+
+
+def test_note_list_with_filters(vault_with_notes):
+ result = runner.invoke(app, ["note", "list", "--tag", "test", "--json"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["count"] >= 2
+
+ result = runner.invoke(app, ["note", "list", "--status", "draft", "--json"])
+ data = json.loads(result.output)
+ assert data["count"] >= 2
+
+ result = runner.invoke(app, ["note", "list", "--sort", "title", "--limit", "1", "--json"])
+ data = json.loads(result.output)
+ assert data["count"] == 1
diff --git a/tests/test_core/__init__.py b/tests/test_core/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_core/test_frontmatter.py b/tests/test_core/test_frontmatter.py
new file mode 100644
index 0000000..9fd3510
--- /dev/null
+++ b/tests/test_core/test_frontmatter.py
@@ -0,0 +1,72 @@
+"""Tests for frontmatter parsing and serialization."""
+
+from hyperresearch.core.frontmatter import parse_frontmatter, serialize_frontmatter, render_note
+from hyperresearch.models.note import NoteMeta
+
+
+def test_parse_basic_frontmatter():
+ content = '---\ntitle: "Hello World"\nid: hello-world\ntags: [python, test]\nstatus: draft\ntype: note\n---\n\n# Hello\n'
+ meta, body = parse_frontmatter(content)
+ assert meta.title == "Hello World"
+ assert meta.id == "hello-world"
+ assert meta.tags == ["python", "test"]
+ assert "# Hello" in body
+
+
+def test_parse_missing_frontmatter():
+ content = "# Just markdown\n\nNo frontmatter here."
+ meta, body = parse_frontmatter(content)
+ assert meta.title == "Untitled"
+ assert body == content
+
+
+def test_parse_empty_frontmatter():
+ content = "---\n---\n\nBody here."
+ meta, body = parse_frontmatter(content)
+ assert meta.title == "Untitled"
+
+
+def test_serialize_roundtrip():
+ meta = NoteMeta(
+ title="Test Note",
+ id="test-note",
+ tags=["python", "test"],
+ status="draft",
+ type="note",
+ )
+ serialized = serialize_frontmatter(meta)
+ assert "title: Test Note" in serialized
+ assert "---" in serialized
+
+ # Parse it back
+ parsed, _ = parse_frontmatter(serialized + "\nBody text")
+ assert parsed.title == "Test Note"
+ assert parsed.id == "test-note"
+ assert parsed.tags == ["python", "test"]
+
+
+def test_render_note():
+ meta = NoteMeta(title="My Note", id="my-note")
+ rendered = render_note(meta, "# Content\n\nHello!")
+ assert rendered.startswith("---\n")
+ assert "title: My Note" in rendered
+ assert "# Content" in rendered
+
+
+def test_tags_lowercased():
+ content = '---\ntitle: Test\ntags: [Python, ASYNC, Test]\n---\n\nBody'
+ meta, _ = parse_frontmatter(content)
+ assert meta.tags == ["python", "async", "test"]
+
+
+def test_windows_path_in_source():
+ """Ensure Windows paths with backslashes are handled correctly."""
+ meta = NoteMeta(
+ title="Test",
+ id="test",
+ source=r"C:\Users\Jordan\file.md",
+ )
+ serialized = serialize_frontmatter(meta)
+ # Should be valid YAML
+ parsed, _ = parse_frontmatter(serialized + "\nBody")
+ assert "Jordan" in (parsed.source or "")
diff --git a/tests/test_core/test_note.py b/tests/test_core/test_note.py
new file mode 100644
index 0000000..7cf1c0a
--- /dev/null
+++ b/tests/test_core/test_note.py
@@ -0,0 +1,105 @@
+"""Tests for note read/write operations."""
+
+from pathlib import Path
+
+from hyperresearch.core.note import read_note, write_note, strip_markdown
+from hyperresearch.models.note import slugify
+
+
+def test_slugify_basic():
+ assert slugify("Hello World") == "hello-world"
+ assert slugify("Python 3.12 Features!") == "python-312-features"
+ assert slugify(" spaces ") == "spaces"
+ assert slugify("CamelCase") == "camelcase"
+ assert slugify("dashes--double") == "dashes-double"
+
+
+def test_write_and_read_roundtrip(tmp_vault):
+ path = write_note(
+ tmp_vault.notes_dir,
+ "Roundtrip Test",
+ body="# Content\n\nSome text here.\n",
+ tags=["test", "roundtrip"],
+ status="evergreen",
+ )
+ assert path.exists()
+
+ note = read_note(path, tmp_vault.root)
+ assert note.meta.title == "Roundtrip Test"
+ assert note.meta.id == "roundtrip-test"
+ assert note.meta.tags == ["test", "roundtrip"]
+ assert note.meta.status == "evergreen"
+ assert "# Content" in note.body
+ assert note.word_count > 0
+
+
+def test_write_avoids_collision(tmp_vault):
+ p1 = write_note(tmp_vault.notes_dir, "Same Title")
+ p2 = write_note(tmp_vault.notes_dir, "Same Title")
+ assert p1 != p2
+ assert p1.exists()
+ assert p2.exists()
+
+
+def test_write_with_parent(tmp_vault):
+ path = write_note(
+ tmp_vault.notes_dir,
+ "Child Note",
+ parent="parent-topic",
+ )
+ assert "parent-topic" in str(path)
+
+
+def test_read_extracts_links(tmp_vault):
+ path = write_note(
+ tmp_vault.notes_dir,
+ "Linking Note",
+ body="See [[note-a]] and [[note-b|display text]].\n",
+ )
+ note = read_note(path, tmp_vault.root)
+ assert "note-a" in note.outgoing_links
+ assert "note-b" in note.outgoing_links
+
+
+def test_read_ignores_code_links(tmp_vault):
+ path = write_note(
+ tmp_vault.notes_dir,
+ "Code Note",
+ body="Real: [[real-link]]\n\n```python\nfake: [[fake-link]]\n```\n\nAlso `[[inline-fake]]`\n",
+ )
+ note = read_note(path, tmp_vault.root)
+ assert "real-link" in note.outgoing_links
+ assert "fake-link" not in note.outgoing_links
+ assert "inline-fake" not in note.outgoing_links
+
+
+def test_strip_markdown():
+ md = "# Header\n\n**Bold** and *italic*. See [[link|display]] and [url](http://example.com).\n\n```python\ncode\n```\n"
+ plain = strip_markdown(md)
+ assert "Header" in plain
+ assert "Bold" in plain
+ assert "display" in plain
+ assert "url" in plain
+ assert "```" not in plain
+ assert "**" not in plain
+ assert "[[" not in plain
+
+
+def test_read_utf8_content(tmp_vault):
+ path = write_note(
+ tmp_vault.notes_dir,
+ "Unicode Note",
+ body="# Umlaute: Aaou. CJK: . Emoji: .\n",
+ )
+ note = read_note(path, tmp_vault.root)
+ assert "Aaou" in note.body
+
+
+def test_read_empty_body(tmp_vault):
+ path = tmp_vault.notes_dir / "empty.md"
+ path.parent.mkdir(exist_ok=True)
+ path.write_text("---\ntitle: Empty\nid: empty\nstatus: draft\ntype: note\n---\n", encoding="utf-8")
+
+ note = read_note(path, tmp_vault.root)
+ assert note.meta.title == "Empty"
+ assert note.body.strip() == ""
diff --git a/tests/test_core/test_sync.py b/tests/test_core/test_sync.py
new file mode 100644
index 0000000..a77c416
--- /dev/null
+++ b/tests/test_core/test_sync.py
@@ -0,0 +1,98 @@
+"""Tests for the sync engine."""
+
+from hyperresearch.core.sync import compute_sync_plan, execute_sync
+
+
+def test_sync_adds_new_files(tmp_vault):
+ from hyperresearch.core.note import write_note
+
+ write_note(tmp_vault.notes_dir, "Note A", body="# A\n\nContent.", tags=["test"])
+ write_note(tmp_vault.notes_dir, "Note B", body="# B\n\nMore content.", tags=["test"])
+
+ plan = compute_sync_plan(tmp_vault)
+ assert len(plan.to_add) == 2
+ assert len(plan.to_delete) == 0
+
+ result = execute_sync(tmp_vault, plan)
+ assert result.added == 2
+ assert result.errors == []
+
+ # Verify in DB
+ count = tmp_vault.db.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]
+ assert count == 2
+
+
+def test_sync_detects_updates(tmp_vault):
+ from hyperresearch.core.note import write_note
+
+ path = write_note(tmp_vault.notes_dir, "Updatable", body="# V1\n\nOriginal.")
+ plan = compute_sync_plan(tmp_vault)
+ execute_sync(tmp_vault, plan)
+
+ # Modify the file
+ import time
+ time.sleep(0.1)
+ path.write_text(path.read_text().replace("Original", "Updated"), encoding="utf-8")
+
+ plan2 = compute_sync_plan(tmp_vault)
+ assert len(plan2.to_update) == 1
+
+
+def test_sync_detects_deletes(tmp_vault):
+ from hyperresearch.core.note import write_note
+
+ path = write_note(tmp_vault.notes_dir, "Deletable", body="# Delete me")
+ plan = compute_sync_plan(tmp_vault)
+ execute_sync(tmp_vault, plan)
+
+ # Delete the file
+ path.unlink()
+
+ plan2 = compute_sync_plan(tmp_vault)
+ assert len(plan2.to_delete) == 1
+
+ result = execute_sync(tmp_vault, plan2)
+ assert result.deleted == 1
+
+ count = tmp_vault.db.execute("SELECT COUNT(*) as c FROM notes").fetchone()["c"]
+ assert count == 0
+
+
+def test_sync_populates_fts(seeded_vault):
+ rows = seeded_vault.db.execute(
+ "SELECT id FROM notes_fts WHERE notes_fts MATCH 'python'"
+ ).fetchall()
+ assert len(rows) > 0
+
+
+def test_sync_populates_tags(seeded_vault):
+ rows = seeded_vault.db.execute(
+ "SELECT DISTINCT tag FROM tags ORDER BY tag"
+ ).fetchall()
+ tags = [r["tag"] for r in rows]
+ assert "python" in tags
+ assert "rust" in tags
+ assert "concurrency" in tags
+
+
+def test_sync_populates_links(seeded_vault):
+ rows = seeded_vault.db.execute(
+ "SELECT source_id, target_ref, target_id FROM links"
+ ).fetchall()
+ assert len(rows) > 0
+
+ # Check that existing notes are resolved
+ resolved = [r for r in rows if r["target_id"] is not None]
+ assert len(resolved) > 0
+
+ # Check that nonexistent-topic is unresolved
+ broken = [r for r in rows if r["target_ref"] == "nonexistent-topic"]
+ assert len(broken) == 1
+ assert broken[0]["target_id"] is None
+
+
+def test_sync_excludes_hyperresearch_dir(tmp_vault):
+ """Files in .hyperresearch/ should never be synced."""
+ (tmp_vault.root / ".hyperresearch" / "test.md").write_text("---\ntitle: Bad\n---\nShould not sync")
+ plan = compute_sync_plan(tmp_vault)
+ assert all(".hyperresearch" not in str(p) for p in plan.to_add)
diff --git a/tests/test_core/test_vault.py b/tests/test_core/test_vault.py
new file mode 100644
index 0000000..9f80aa8
--- /dev/null
+++ b/tests/test_core/test_vault.py
@@ -0,0 +1,67 @@
+"""Tests for vault initialization and discovery."""
+
+from pathlib import Path
+
+import pytest
+
+from hyperresearch.core.vault import Vault, VaultError
+
+
+def test_init_creates_structure(tmp_path: Path):
+ vault = Vault.init(tmp_path / "kb", name="My KB")
+ assert vault.is_initialized
+ assert (vault.root / ".hyperresearch").is_dir()
+ assert (vault.root / ".hyperresearch" / "config.toml").exists()
+ assert (vault.root / ".hyperresearch" / "hyperresearch.db").exists()
+ assert (vault.root / ".hyperresearch" / "templates").is_dir()
+ assert (vault.root / ".hyperresearch" / "exports").is_dir()
+ # One visible directory
+ assert vault.research_dir.is_dir()
+ assert vault.notes_dir.is_dir()
+ assert vault.index_dir.is_dir()
+
+
+def test_init_custom_dir(tmp_path: Path):
+ vault = Vault.init(tmp_path / "kb", name="Custom", research_dir="docs/wiki")
+ assert (vault.root / "docs" / "wiki" / "notes").is_dir()
+ assert vault.config.research_dir == "docs/wiki"
+
+
+def test_init_double_init_raises(tmp_path: Path):
+ Vault.init(tmp_path / "kb")
+ with pytest.raises(VaultError, match="already initialized"):
+ Vault.init(tmp_path / "kb")
+
+
+def test_discover_finds_vault(tmp_path: Path):
+ vault = Vault.init(tmp_path / "kb")
+ # Discover from a subdirectory
+ sub = vault.notes_dir / "deep"
+ sub.mkdir(parents=True)
+ found = Vault.discover(start=sub)
+ assert found.root == vault.root
+
+
+def test_discover_raises_when_no_vault(tmp_path: Path):
+ with pytest.raises(VaultError, match="No hyperresearch vault"):
+ Vault.discover(start=tmp_path)
+
+
+def test_config_loaded(tmp_vault: Vault):
+ assert tmp_vault.config.name == "Test Vault"
+ assert tmp_vault.config.auto_sync is True
+
+
+def test_agent_docs_created(tmp_path: Path):
+ vault = Vault.init(tmp_path / "kb")
+ assert (vault.root / "CLAUDE.md").exists()
+ content = (vault.root / "CLAUDE.md").read_text()
+ assert "hyperresearch" in content
+
+
+def test_agent_docs_all(tmp_path: Path):
+ vault = Vault.init(tmp_path / "kb-all", agents=["claude", "agents", "gemini", "copilot"])
+ assert (vault.root / "CLAUDE.md").exists()
+ assert (vault.root / "AGENTS.md").exists()
+ assert (vault.root / "GEMINI.md").exists()
+ assert (vault.root / ".github" / "copilot-instructions.md").exists()
diff --git a/tests/test_graph/__init__.py b/tests/test_graph/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_graph/test_links.py b/tests/test_graph/test_links.py
new file mode 100644
index 0000000..dc67713
--- /dev/null
+++ b/tests/test_graph/test_links.py
@@ -0,0 +1,77 @@
+"""Tests for link parsing and graph operations."""
+
+from hyperresearch.core.note import WIKI_LINK_RE, CODE_BLOCK_RE, INLINE_CODE_RE
+
+
+def test_wiki_link_regex_simple():
+ matches = WIKI_LINK_RE.findall("See [[python-async]] for details.")
+ assert len(matches) == 1
+ assert matches[0] == "python-async"
+
+
+def test_wiki_link_regex_with_display():
+ text = "Check [[python-async|Python Async Guide]] here."
+ matches = WIKI_LINK_RE.findall(text)
+ assert len(matches) == 1
+ # Group 1 is the target
+ assert "python-async" in matches[0]
+
+
+def test_wiki_link_regex_multiple():
+ text = "See [[note-a]], [[note-b]], and [[note-c|Note C]]."
+ matches = WIKI_LINK_RE.findall(text)
+ assert len(matches) == 3
+
+
+def test_wiki_link_not_in_code_block():
+ text = "```python\n[[not-a-link]]\n```\n\n[[real-link]]"
+ cleaned = CODE_BLOCK_RE.sub("", text)
+ matches = WIKI_LINK_RE.findall(cleaned)
+ assert len(matches) == 1
+ assert "real-link" in matches[0]
+
+
+def test_wiki_link_not_in_inline_code():
+ text = "Use `[[not-a-link]]` but also [[real-link]]"
+ cleaned = INLINE_CODE_RE.sub("", text)
+ matches = WIKI_LINK_RE.findall(cleaned)
+ assert len(matches) == 1
+ assert "real-link" in matches[0]
+
+
+def test_backlinks_populated(seeded_vault):
+ """Concurrency links to python-async-patterns, so python-async-patterns should have a backlink."""
+ rows = seeded_vault.db.execute(
+ "SELECT source_id FROM links WHERE target_id = 'python-async-patterns'"
+ ).fetchall()
+ source_ids = [r["source_id"] for r in rows]
+ assert "concurrency" in source_ids
+
+
+def test_broken_links_detected(seeded_vault):
+ """The concurrency note links to nonexistent-topic which should be broken."""
+ rows = seeded_vault.db.execute(
+ "SELECT target_ref FROM links WHERE target_id IS NULL"
+ ).fetchall()
+ broken_refs = [r["target_ref"] for r in rows]
+ assert "nonexistent-topic" in broken_refs
+
+
+def test_orphan_detection(seeded_vault):
+ """The orphan note should have no links in or out."""
+ rows = seeded_vault.db.execute("""
+ SELECT n.id FROM notes n
+ WHERE n.type NOT IN ('index', 'raw')
+ AND n.id NOT IN (SELECT DISTINCT target_id FROM links WHERE target_id IS NOT NULL)
+ AND n.id NOT IN (SELECT DISTINCT source_id FROM links)
+ """).fetchall()
+ orphan_ids = [r["id"] for r in rows]
+ assert "orphan-note" in orphan_ids
+
+
+def test_hub_detection(seeded_vault):
+ """python-async-patterns should be a hub (linked from multiple notes)."""
+ row = seeded_vault.db.execute(
+ "SELECT COUNT(*) as c FROM links WHERE target_id = 'python-async-patterns'"
+ ).fetchone()
+ assert row["c"] >= 2
diff --git a/tests/test_search/__init__.py b/tests/test_search/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_search/test_fts.py b/tests/test_search/test_fts.py
new file mode 100644
index 0000000..68869fb
--- /dev/null
+++ b/tests/test_search/test_fts.py
@@ -0,0 +1,58 @@
+"""Tests for full-text search."""
+
+from hyperresearch.search.fts import search_fts, preprocess_query
+from hyperresearch.search.filters import SearchFilters
+
+
+def test_preprocess_simple_query():
+ assert '"python"*' in preprocess_query("python")
+
+
+def test_preprocess_quoted_phrase():
+ result = preprocess_query('"async await"')
+ assert '"async await"' in result
+
+
+def test_preprocess_passthrough_operators():
+ query = "python AND async"
+ assert preprocess_query(query) == query
+
+
+def test_search_returns_results(seeded_vault):
+ results = search_fts(seeded_vault.db, "python")
+ assert len(results) > 0
+ assert any(r["id"] == "python-async-patterns" for r in results)
+
+
+def test_search_with_tag_filter(seeded_vault):
+ filters = SearchFilters(tags=["rust"])
+ results = search_fts(seeded_vault.db, "memory", filters=filters)
+ assert all("rust" in r["tags"] for r in results)
+
+
+def test_search_with_status_filter(seeded_vault):
+ filters = SearchFilters(status="draft")
+ results = search_fts(seeded_vault.db, "orphan", filters=filters)
+ assert all(r["status"] == "draft" for r in results)
+
+
+def test_search_no_results(seeded_vault):
+ results = search_fts(seeded_vault.db, "zzzznonexistenttermzzzz")
+ assert len(results) == 0
+
+
+def test_search_limit(seeded_vault):
+ results = search_fts(seeded_vault.db, "concurrency", limit=1)
+ assert len(results) <= 1
+
+
+def test_filter_by_date(seeded_vault):
+ filters = SearchFilters(after="2020-01-01")
+ results = search_fts(seeded_vault.db, "python", filters=filters)
+ assert len(results) > 0
+
+
+def test_filter_by_path_glob(seeded_vault):
+ filters = SearchFilters(path_glob="notes/python/*")
+ results = search_fts(seeded_vault.db, "python", filters=filters)
+ assert all("python" in r["path"] for r in results)