synto 0.1.0__tar.gz

synto-0.1.0/.github/FUNDING.yml

@@ -0,0 +1,6 @@
+# These are supported funding model platforms
+
+github: kytmanov
+liberapay: kytmanov
+buy_me_a_coffee: kytmanov
+custom: ["https://tip.md/kytmanov"]

synto-0.1.0/.github/workflows/benchmark.yml

@@ -0,0 +1,41 @@
+name: Benchmarks
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  benchmark:
+    name: Offline micro-benchmarks
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run benchmarks
+        run: |
+          uv run pytest tests/test_benchmarks.py \
+            --benchmark-only \
+            --benchmark-json=benchmark-results.json \
+            -v
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark-results.json
+          retention-days: 90
+

synto-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    name: pytest + ruff
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check src/ tests/
+
+      - name: Run tests
+        run: uv run pytest --tb=short -q

synto-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    name: Tests must pass
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Tests
+        run: uv run pytest --tb=short -q
+
+  release:
+    name: Create GitHub Release
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          make_latest: true
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC trusted publishing — no API token needed
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

synto-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.log
+
+# Vault artifacts (not part of the tool itself)
+.chroma/
+*.db
+.olw-compare/
+
+# Test artifacts
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Claude Code local settings (user-specific, never commit)
+.claude/
+
+# Ruff cache
+.ruff_cache/
+
+# Local planning/review artifacts
+CONTEXT.md
+REQUIREMENTS.md
+IMPLEMENTATION_PLAN.md
+IMPLEMENTAION_PLAN.md
+REVIEW.md

synto-0.1.0/CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install (editable, auto-detects uv/pip)
+python install.py
+
+# Dependencies
+uv sync --group dev
+
+# Tests (all offline, no Ollama required)
+uv run pytest
+uv run pytest tests/test_ingest.py::test_function_name -v   # single test
+uv run pytest --cov=src/synto                   # with coverage
+
+# Lint & format
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run ruff format src/ tests/        # auto-fix
+
+# Smoke tests (user preference: run against LM Studio with gemma4:e4b)
+# Requires LM Studio server at http://localhost:1234/v1 with gemma4:e4b loaded.
+PROVIDER=lm_studio FAST_MODEL=gemma4:e4b HEAVY_MODEL=gemma4:e4b bash scripts/smoke_test.sh
+PROVIDER=lm_studio FAST_MODEL=gemma4:e4b HEAVY_MODEL=gemma4:e4b bash scripts/compare_smoke.sh
+# If LM Studio rejects the alias, use the exact loaded id it reports, e.g.
+# PROVIDER=lm_studio FAST_MODEL=google/gemma-4-e4b HEAVY_MODEL=google/gemma-4-e4b bash scripts/smoke_test.sh
+# The main smoke can take 15+ minutes with gemma4:e4b; use a long command timeout.
+```
+
+## Architecture
+
+Three-stage local LLM pipeline turning Obsidian raw notes into a synthesized wiki via Ollama.
+
+**Data flow:** `raw/*.md` → **ingest** (fast model → AnalysisResult) → **compile** (heavy model → SingleArticle drafts) → **approve** (publish to `wiki/`)
+
+**Vault structure:** `raw/` (immutable user notes), `wiki/` (published articles), `wiki/.drafts/`, `wiki/sources/`, `wiki/queries/`, `wiki/synthesis/`, `.synto/state.db`
+
+### Query synthesis
+
+- `synto query --save` writes dated Q&A notes to `wiki/queries/`
+- `synto query --synthesize` writes published synthesis articles to `wiki/synthesis/`
+- synthesis rows are tracked in `wiki_articles` with `kind="synthesis"`, `question_hash`, `synthesis_sources`, and `synthesis_source_hashes`
+- duplicate syntheses are keyed by normalized question hash
+- `update_in_place` must respect manual-edit protection by comparing the on-disk body hash with the DB `content_hash`
+- compare runs must not create or mutate active `wiki/synthesis/` content
+
+### Key modules (`src/synto/`)
+
+- `cli.py` — Click-based CLI entry point, all commands registered here
+- `config.py` / `global_config.py` — Two-tier config: per-vault `synto.toml` + user-level `~/.config/synto/config.toml`
+- `models.py` — Pydantic v2 schemas for LLM I/O (AnalysisResult, SingleArticle, PageSelection, QueryAnswer) and internal state (RawNoteRecord, WikiArticleRecord)
+- `state.py` — SQLite state DB tracking note lifecycle (new → ingested → compiled → published/failed), concepts, and articles
+- `ollama_client.py` — Thin httpx wrapper around Ollama HTTP API (no langchain)
+- `structured_output.py` — 3-tier JSON extraction fallback: native `format=json` → regex extraction → retry with error feedback
+- `vault.py` — Frontmatter parsing (python-frontmatter), wikilink extraction, atomic writes
+- `indexer.py` — Generates `wiki/index.md` and append-only operation log
+- `git_ops.py` — Auto-commit with `[synto]` prefix, safe undo via `git revert`
+- `watcher.py` — Debounced file watcher (watchdog + threading.Timer)
+
+### Pipeline stages (`pipeline/`)
+
+- `ingest.py` — Fast model analyzes raw notes, extracts concepts, creates source summary pages
+- `compile.py` — Default: concept-driven (one article per concept, incremental). Legacy: two-step LLM planning (`--legacy`). Manual-edit protection via content_hash comparison
+- `query.py` — Index-based page routing (no embeddings), fast model selects pages, heavy model answers
+- `lint.py` — Static health checks (orphans, broken links, stale articles, missing frontmatter)
+
+## Conventions
+
+- **Two LLM tiers:** fast model (gemma4:e4b, 8K ctx) for analysis/routing, heavy model (qwen2.5:14b, 16K ctx) for writing. For manual/smoke testing, use gemma4:e4b for both fast and heavy
+- **Pydantic models for LLM output:** Keep schemas small and flat (no nested lists of objects) for 4B model reliability. JSON schema is injected into system prompts
+- **Atomic writes:** `vault.atomic_write()` uses temp file + rename for crash safety
+- **Content hashing:** SHA256 on note body (excluding frontmatter) for dedup and manual-edit detection
+- **Concept normalization:** Case-insensitive matching against existing canonical names during ingest
+- **Config loading order:** `--vault` flag → `SYNTO_VAULT` env var → global config default vault → error
+- **Git safety:** All auto-operations use `[synto]`-prefixed commits; undo uses `git revert` (never destructive)
+- **Error handling:** LLM failures log + mark note as "failed" + continue (no crash). Config loading returns None on failure (fail open)
+- **Code comments:** Add comments only when the reason or invariant is non-obvious from the code itself. Prefer tests and commit messages for routine explanation; use comments for safeguards, provider quirks, heuristics, and tradeoffs that future agents or humans could otherwise misread.
+- **Testing:** All 200 tests mock OllamaClient via MagicMock, use tmp_path vaults and in-memory SQLite. Fixtures in `tests/fixtures/`. Integration tests marked with `@pytest.mark.integration`
+- **Python 3.11+:** Uses `tomllib` (stdlib), `from __future__ import annotations`, full type hints
+- **Ruff config:** rules E, F, I, UP; line-length 100

synto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kytmanov
+
+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.

synto-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: synto
+Version: 0.1.0
+Summary: Turn private notes into local knowledge packs and synthesized wikis
+Project-URL: Homepage, https://github.com/kytmanov/synto
+Project-URL: Repository, https://github.com/kytmanov/synto
+Project-URL: Issues, https://github.com/kytmanov/synto/issues
+Author: kytmanov
+License: MIT
+License-File: LICENSE
+Keywords: knowledge-management,llm,local-ai,obsidian,ollama,wiki
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: python-ulid>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: watchdog>=4.0
+Provides-Extra: mcp
+Requires-Dist: mcp<2.0,>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Synto
+
+<p align="center">
+     <a href="https://github.com/kytmanov/synto/commits/master"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/kytmanov/obsidian-llm-wiki-local?style=flat"></a> 
+     <a href="https://github.com/kytmanov/synto/actions/workflows/ci.yml"><img alt="CI status" src="https://img.shields.io/github/actions/workflow/status/kytmanov/synto/ci.yml?style=flat&amp;label=CI"></a> 
+     <a href="https://pypi.org/project/synto/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/synto?style=flat"></a>
+</p>
+
+**Turn your raw notes into a self-improving, interlinked wiki — powered by a local LLM.**
+
+Synto is a knowledge compiler. Point it at any source of expertise and it produces a portable wiki pack any AI agent can install and query.
+
+
+**Local-first, provider-flexible.** Runs 100% locally with Ollama or LM Studio. Switch to a cloud provider — Groq, OpenRouter, Mistral — when you need more power. Your notes and source material never leave your machine unless you choose.
+
+Synto succeeds [obsidian-llm-wiki-local](https://github.com/kytmanov/obsidian-llm-wiki-local) (608 ★, 9k+ downloads) — same proven local pipeline, redesigned for distributable knowledge packs.
+
+<p align=center>
+<img width="341" height="463" alt="image" src="https://github.com/user-attachments/assets/b3e13203-bb4a-42a4-a16d-0d4d93404f71" />
+</p>
+
+---
+
+## Why it exists
+
+AI agents are only as good as the context you give them. A folder of notes or a raw PDF is not context — it's noise. Synto processes your source material through a local LLM pipeline, extracts concepts, writes cross-linked articles, and exports a structured directory: articles, an index, a concept graph, and agent-readable metadata. The pack installs like a package. Any agent gets a domain expert layer, not a file dump.
+
+---
+
+## Use cases
+
+**Architectural reference from a textbook**
+
+[Dobryakov took Tanenbaum's *Distributed Systems*](https://www.facebook.com/dobryakov/posts/pfbid021pwPPJZ77KsyWMs3zTdMQEbgpmxgeE9wzoX1SDFE12y5vC3HtdFZV5i5HnS2dUAul), compiled it into a cross-linked wiki, and installed it into Claude/Cursor. Instead of generic suggestions, the AI started reasoning from established distributed systems principles — recommending consistent hashing and two-phase commit instead of "use a shared database." Any technical book, spec, or documentation set becomes a live context layer for your AI.
+
+**Karpathy's LLM Wiki**
+
+[Andrej Karpathy's](https://karpathy.ai) neural-network series is 20 hours of dense, high-quality material. Compile the transcripts and blog posts into a Synto pack and the content becomes queryable: any agent in your project can explain backpropagation, walk through the attention mechanism, or cite a specific lecture — from the source, not from model weights.
+
+**Your own research notes**
+
+Works today with Markdown. Drop notes in `raw/`, run `synto run`, and get a cross-linked wiki exported as an agent-ready pack. Expose it via `synto serve` as a local MCP server, or ship the pack directory for any file-aware agent to use.
+
+---
+
+## How it works
+
+Three stages, two LLM tiers:
+
+1. **Ingest** — fast model reads each source, extracts concepts and summaries
+2. **Compile** — heavy model writes one cross-linked article per concept
+3. **Export** — `synto pack export` produces an agent-ready directory
+
+The fast model handles analysis (4B parameters is enough). The heavy model handles writing (14B+ recommended locally, or any cloud model). Both tiers are configurable independently.
+
+---
+
+## Install
+
+```bash
+pip install synto
+# or
+uv tool install synto
+```
+
+For MCP server support:
+
+```bash
+pip install "synto[mcp]"
+```
+
+---
+
+## Quick start
+
+```bash
+synto setup                                   # configure LLM provider
+synto init ~/my-vault                         # create vault
+
+# add Markdown notes to ~/my-vault/raw/
+synto run --vault ~/my-vault                  # ingest + compile into wiki/.drafts/
+synto review --vault ~/my-vault               # inspect drafts interactively
+# or: synto approve --all --vault ~/my-vault
+
+synto pack export --target agents --vault ~/my-vault
+synto serve --vault ~/my-vault                # expose as MCP server (requires [mcp])
+```
+
+If you want a one-command flow, use `synto run --auto-approve --vault ~/my-vault`.
+That skips draft review and publishes directly into `wiki/`.
+
+---
+
+## What's in a pack
+
+```
+pack/
+  articles/           one Markdown file per concept
+  index/INDEX.json    machine-readable index with stable article IDs
+  agent/
+    manifest.json     capabilities, pack metadata
+    concepts.json     concept registry
+    sources.json      source provenance
+  AGENTS.md           agent-readable entrypoint
+  CLAUDE.md           Claude Code context file
+```
+
+Any file-aware agent can read the articles directly. `INDEX.json` enables fast concept lookup without a database. `synto serve` exposes `list_articles`, `read_article`, and `find_concept` as MCP tools.
+
+---
+
+## What ships now
+
+- Full ingest → compile → approve pipeline; currently supports Markdown notes and Obsidian vaults
+- `synto pack export --target agents` — portable knowledge pack with INDEX.json and agent metadata
+- `synto serve` — read-only MCP server (`list_articles`, `read_article`, `find_concept`)
+- `synto query` — index-routed Q&A with optional synthesis to `wiki/synthesis/`
+- `synto review` — interactive draft review: approve, reject, edit, or diff before publishing
+- `synto watch` — file watcher: auto-ingest and compile on every save
+- `synto maintain` — wiki health check, stub creation, orphan cleanup
+- `synto eval` — offline structural evaluation (coverage, citation support, link resolution)
+- `synto compare` — A/B model comparison without touching your vault
+- Multi-language: notes are ingested and compiled in their source language
+- 20+ LLM providers supported via OpenAI-compatible API
+
+---
+
+## Data & Privacy
+
+- **Local by default.** Ollama and LM Studio process all content on your machine — notes never leave it.
+- **Cloud providers.** If you configure an OpenAI-compatible cloud provider, note content and wiki text are sent to that service. Review their privacy policy before use.
+- **No remote analytics.** Synto does not send usage analytics anywhere. Local runtime and cost metrics stay in your vault database.
+- **Pack exports.** Exported packs include raw notes, sources, wiki articles, queries, and synthesis by default. Review your vault before sharing a pack.
+- **API keys.** Stored in `~/.config/synto/config.toml` (user-owned, not inside the vault). Never commit that file.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- An LLM provider: Ollama (local), LM Studio, or any OpenAI-compatible endpoint
+
+Recommended local setup: a 4B model for ingest (e.g. Gemma 4), a 14B+ model for compilation (e.g. Qwen 2.5 14B). Works entirely offline.
+
+---
+
+## Migrate from obsidian-llm-wiki-local
+
+**Existing obsidian-llm-wiki-local vaults must be migrated first.** Run `migrate-olw` to copy `wiki.toml` and `.olw/` into the current Synto layout before using normal commands.
+
+```bash
+synto migrate-olw --vault ~/my-old-vault
+```
+
+Copies `wiki.toml` → `synto.toml` and `.olw/` → `.synto/`. Notes and articles are untouched. Old files are preserved — delete them once you've verified everything works.

synto-0.1.0/README.md

@@ -0,0 +1,155 @@
+# Synto
+
+<p align="center">
+     <a href="https://github.com/kytmanov/synto/commits/master"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/kytmanov/obsidian-llm-wiki-local?style=flat"></a> 
+     <a href="https://github.com/kytmanov/synto/actions/workflows/ci.yml"><img alt="CI status" src="https://img.shields.io/github/actions/workflow/status/kytmanov/synto/ci.yml?style=flat&amp;label=CI"></a> 
+     <a href="https://pypi.org/project/synto/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/synto?style=flat"></a>
+</p>
+
+**Turn your raw notes into a self-improving, interlinked wiki — powered by a local LLM.**
+
+Synto is a knowledge compiler. Point it at any source of expertise and it produces a portable wiki pack any AI agent can install and query.
+
+
+**Local-first, provider-flexible.** Runs 100% locally with Ollama or LM Studio. Switch to a cloud provider — Groq, OpenRouter, Mistral — when you need more power. Your notes and source material never leave your machine unless you choose.
+
+Synto succeeds [obsidian-llm-wiki-local](https://github.com/kytmanov/obsidian-llm-wiki-local) (608 ★, 9k+ downloads) — same proven local pipeline, redesigned for distributable knowledge packs.
+
+<p align=center>
+<img width="341" height="463" alt="image" src="https://github.com/user-attachments/assets/b3e13203-bb4a-42a4-a16d-0d4d93404f71" />
+</p>
+
+---
+
+## Why it exists
+
+AI agents are only as good as the context you give them. A folder of notes or a raw PDF is not context — it's noise. Synto processes your source material through a local LLM pipeline, extracts concepts, writes cross-linked articles, and exports a structured directory: articles, an index, a concept graph, and agent-readable metadata. The pack installs like a package. Any agent gets a domain expert layer, not a file dump.
+
+---
+
+## Use cases
+
+**Architectural reference from a textbook**
+
+[Dobryakov took Tanenbaum's *Distributed Systems*](https://www.facebook.com/dobryakov/posts/pfbid021pwPPJZ77KsyWMs3zTdMQEbgpmxgeE9wzoX1SDFE12y5vC3HtdFZV5i5HnS2dUAul), compiled it into a cross-linked wiki, and installed it into Claude/Cursor. Instead of generic suggestions, the AI started reasoning from established distributed systems principles — recommending consistent hashing and two-phase commit instead of "use a shared database." Any technical book, spec, or documentation set becomes a live context layer for your AI.
+
+**Karpathy's LLM Wiki**
+
+[Andrej Karpathy's](https://karpathy.ai) neural-network series is 20 hours of dense, high-quality material. Compile the transcripts and blog posts into a Synto pack and the content becomes queryable: any agent in your project can explain backpropagation, walk through the attention mechanism, or cite a specific lecture — from the source, not from model weights.
+
+**Your own research notes**
+
+Works today with Markdown. Drop notes in `raw/`, run `synto run`, and get a cross-linked wiki exported as an agent-ready pack. Expose it via `synto serve` as a local MCP server, or ship the pack directory for any file-aware agent to use.
+
+---
+
+## How it works
+
+Three stages, two LLM tiers:
+
+1. **Ingest** — fast model reads each source, extracts concepts and summaries
+2. **Compile** — heavy model writes one cross-linked article per concept
+3. **Export** — `synto pack export` produces an agent-ready directory
+
+The fast model handles analysis (4B parameters is enough). The heavy model handles writing (14B+ recommended locally, or any cloud model). Both tiers are configurable independently.
+
+---
+
+## Install
+
+```bash
+pip install synto
+# or
+uv tool install synto
+```
+
+For MCP server support:
+
+```bash
+pip install "synto[mcp]"
+```
+
+---
+
+## Quick start
+
+```bash
+synto setup                                   # configure LLM provider
+synto init ~/my-vault                         # create vault
+
+# add Markdown notes to ~/my-vault/raw/
+synto run --vault ~/my-vault                  # ingest + compile into wiki/.drafts/
+synto review --vault ~/my-vault               # inspect drafts interactively
+# or: synto approve --all --vault ~/my-vault
+
+synto pack export --target agents --vault ~/my-vault
+synto serve --vault ~/my-vault                # expose as MCP server (requires [mcp])
+```
+
+If you want a one-command flow, use `synto run --auto-approve --vault ~/my-vault`.
+That skips draft review and publishes directly into `wiki/`.
+
+---
+
+## What's in a pack
+
+```
+pack/
+  articles/           one Markdown file per concept
+  index/INDEX.json    machine-readable index with stable article IDs
+  agent/
+    manifest.json     capabilities, pack metadata
+    concepts.json     concept registry
+    sources.json      source provenance
+  AGENTS.md           agent-readable entrypoint
+  CLAUDE.md           Claude Code context file
+```
+
+Any file-aware agent can read the articles directly. `INDEX.json` enables fast concept lookup without a database. `synto serve` exposes `list_articles`, `read_article`, and `find_concept` as MCP tools.
+
+---
+
+## What ships now
+
+- Full ingest → compile → approve pipeline; currently supports Markdown notes and Obsidian vaults
+- `synto pack export --target agents` — portable knowledge pack with INDEX.json and agent metadata
+- `synto serve` — read-only MCP server (`list_articles`, `read_article`, `find_concept`)
+- `synto query` — index-routed Q&A with optional synthesis to `wiki/synthesis/`
+- `synto review` — interactive draft review: approve, reject, edit, or diff before publishing
+- `synto watch` — file watcher: auto-ingest and compile on every save
+- `synto maintain` — wiki health check, stub creation, orphan cleanup
+- `synto eval` — offline structural evaluation (coverage, citation support, link resolution)
+- `synto compare` — A/B model comparison without touching your vault
+- Multi-language: notes are ingested and compiled in their source language
+- 20+ LLM providers supported via OpenAI-compatible API
+
+---
+
+## Data & Privacy
+
+- **Local by default.** Ollama and LM Studio process all content on your machine — notes never leave it.
+- **Cloud providers.** If you configure an OpenAI-compatible cloud provider, note content and wiki text are sent to that service. Review their privacy policy before use.
+- **No remote analytics.** Synto does not send usage analytics anywhere. Local runtime and cost metrics stay in your vault database.
+- **Pack exports.** Exported packs include raw notes, sources, wiki articles, queries, and synthesis by default. Review your vault before sharing a pack.
+- **API keys.** Stored in `~/.config/synto/config.toml` (user-owned, not inside the vault). Never commit that file.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- An LLM provider: Ollama (local), LM Studio, or any OpenAI-compatible endpoint
+
+Recommended local setup: a 4B model for ingest (e.g. Gemma 4), a 14B+ model for compilation (e.g. Qwen 2.5 14B). Works entirely offline.
+
+---
+
+## Migrate from obsidian-llm-wiki-local
+
+**Existing obsidian-llm-wiki-local vaults must be migrated first.** Run `migrate-olw` to copy `wiki.toml` and `.olw/` into the current Synto layout before using normal commands.
+
+```bash
+synto migrate-olw --vault ~/my-old-vault
+```
+
+Copies `wiki.toml` → `synto.toml` and `.olw/` → `.synto/`. Notes and articles are untouched. Old files are preserved — delete them once you've verified everything works.