knowledge-gateway 0.7.4__tar.gz

knowledge_gateway-0.7.4/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+# Keep the SHA-pinned GitHub Actions and the Python/uv dependency tree current.
+# Dependabot opens small PRs; CI (and branch protection) gate them.
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: deps

knowledge_gateway-0.7.4/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: ci
+
+# Test on every PR and on pushes to main (so the published default branch and
+# every release tag are known-green). No secrets, no network beyond pip.
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      # The committed lockfile must stay consistent with pyproject.
+      - run: uv lock --check
+      # search/backlinks/list_tags shell out to ripgrep; install it so those
+      # tools and their tests actually run in CI (not silently skipped).
+      - run: sudo apt-get update && sudo apt-get install -y ripgrep
+      - run: uv venv --python ${{ matrix.python-version }}
+      - run: uv pip install -e ".[dev]"
+      - run: uv run pytest -q --cov=gateway --cov-report=term-missing

knowledge_gateway-0.7.4/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: release
+
+# On a vX.Y.Z tag: build, publish a GitHub Release, then publish to PyPI via Trusted
+# Publishing (OIDC, no token). CI (ci.yml) also runs on tags, so a release is only cut
+# from a known-green tree. The GitHub Release runs before PyPI so a not-yet-configured
+# Trusted Publisher cannot block it.
+# One-time setup on pypi.org: add a pending publisher for project `knowledge-gateway` ->
+# owner fszalaj, repo knowledge-gateway, workflow release.yml, environment pypi.
+# (Renamed from `obsidian-gateway`; the old project's publisher no longer matches the dist name.)
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - run: uv build
+      - name: Publish GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${{ github.ref_name }}" dist/* --title "${{ github.ref_name }}" --generate-notes
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

knowledge_gateway-0.7.4/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Live config - NEVER commit (paths + bearer tokens live only on the host)
+vaults.yaml
+tokens.yaml

knowledge_gateway-0.7.4/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to knowledge-gateway. Consumers track the moving **`stable`** branch
+(`uvx --refresh --from git+...@stable`); each release moves `stable` and auto-propagates on
+next launch (no per-repo re-pin). Every release is also an immutable `vX.Y.Z` tag for
+pinning/audit.
+
+## v0.7.4 - 2026-06-27
+
+### Changed
+- GitHub repo renamed to **`knowledge-gateway`**; all URLs now point to
+  `github.com/fszalaj/knowledge-gateway` (the old `obsidian-gateway` URL redirects, so existing
+  `@stable` configs keep working). First release cut under the `knowledge-gateway` PyPI Trusted
+  Publisher.
+
+## v0.7.3 - 2026-06-27
+
+### Fixed
+- Swept the last `obsidian-gateway` references in `gateway/` code: the tempfile-fallback lock-dir
+  name and the fcntl-unavailable warning in `gateway/locks.py`, and the `knowledge-gateway-graph`
+  CLI docstring. `git grep obsidian-gateway -- gateway/**` is now empty (the name survives only in
+  the repo URL, the "formerly" note, and CHANGELOG history).
+
+## v0.7.2 - 2026-06-27
+
+### Fixed
+- Three stray `obsidian-gateway` references missed in the rename (caught by review): the
+  `importlib.metadata.version("obsidian-gateway")` lookup in `gateway/__init__.py` (was silently
+  falling back to the wrong version), the `knowledge-gateway-graph` CLI `prog` name, and the git
+  lock-dir name in `gateway/locks.py`.
+
+## v0.7.1 - 2026-06-27
+
+### Changed
+- **Dropped the obsidian-gateway back-compat aliases** (pre-1.0 dev): removed the `obsidian-gateway`
+  console scripts and renamed the `OBSIDIAN_GATEWAY_*` env vars to `KNOWLEDGE_GATEWAY_*`. The only
+  names now are `knowledge-gateway` (the git repo URL stays `.../obsidian-gateway` until the repo is
+  renamed). Swept the README + deploy units; renamed the `deploy/*.service`/`.timer` unit files.
+
+## v0.7.0 - 2026-06-27
+
+### Changed
+- **Renamed `obsidian-gateway` -> `knowledge-gateway`** - it is no longer just a vault wrapper but a
+  knowledge gateway (vault + code-graph + convert). The distribution, CLI, MCP display name, and
+  `server.json` are now `knowledge-gateway`; the import package stays `gateway`, and the MCP server
+  is still keyed `wiki` in client configs.
+- **Back-compat:** the old `obsidian-gateway` / `obsidian-gateway-graph` console scripts remain as
+  aliases, and `OBSIDIAN_GATEWAY_VAULT`/`_LOCAL` env vars are still read - existing `uvx --from
+  git+...@stable obsidian-gateway` configs keep working during the transition.
+- README repositioned (vault + code-graph + convert), `server.py` instructions list the graph/convert tools.
+
+### PyPI
+- Trusted Publishing must be reconfigured for the new project name: add a pending publisher for
+  `knowledge-gateway` (owner fszalaj, repo knowledge-gateway, workflow release.yml, environment pypi).
+
+## v0.6.0 - 2026-06-27
+
+### Added
+- **Code graph (optional `[graph]` / `[graph-all]`)**: a `gateway/codegraph/` package builds a
+  NetworkX graph of a source tree - Python (`ast`), Ansible (PyYAML walker: roles/tasks/handlers/
+  `include_role`/`import_tasks`/`notify` + `task -> filter plugin` edges), and an optional broad
+  tree-sitter pass (JS/TS/Go/Rust/Terraform/bash/PowerShell/...). New read-only MCP tools
+  `list_graphs`, `graph_query`, `graph_neighbors`, `god_nodes`, `graph_shortest_path`,
+  `graph_stats`; a local-only `graph_build`; and a `obsidian-gateway-graph` CLI.
+- **Document conversion (optional `[convert]`)**: `convert_to_markdown` turns a vault file
+  (PDF/Office/image/HTML/...) into Markdown via markitdown.
+
+### Security
+- Graph files live in the vault's `.graph/` and are vault-contained (resolved + `is_relative_to`
+  the vault, so a symlinked `.graph` cannot escape). Malformed graphs map to `graph_invalid:`.
+  Optional deps (networkx, tree-sitter-language-pack, markitdown) are imported lazily, so the core
+  gateway requires none of them.
+
+## v0.5.1 - 2026-06-16
+
+### Changed
+- **Server instructions**: point agents at `_templates/<type>.md` before creating a page
+  (the folder is already reachable via `list_notes`/`read_note` - no new tools).
+
+### Distribution
+- **PyPI Trusted Publishing**: `release.yml` publishes to PyPI on a `vX.Y.Z` tag via OIDC
+  (no token). First PyPI release - consumers can `uvx obsidian-gateway` (alongside `@stable`).
+- **MCP Registry**: `server.json` manifest + a `mcp-name` marker in the README, for listing
+  in the official MCP Registry.
+
+## v0.5.0 - 2026-06-15
+
+### Features (MCP-FEAT)
+- **Attachments**: `list_attachments` + `read_attachment` - read binary vault files (images
+  return as an inline `Image`; PDF/audio/video as a `File`), path-guarded, 25 MiB cap.
+- **Obsidian Canvas**: `list_canvases` + `read_canvas` + `write_canvas` - read/write `.canvas`
+  JSON (nodes including `group` nodes, edges, `color` fields), so agents can work with groups
+  and colors.
+
+## v0.4.2 - 2026-06-15
+
+### Concurrency (CONC-1)
+- **Per-repo write lock** (`fcntl.flock`): serializes read-modify-write tools
+  (`patch_note` / `patch_frontmatter`) and concurrent commits across threads and processes on
+  one host, fixing lost-update and mixed-commit races on the shared server. Taken once at the
+  tool boundary (the inner commit never re-locks); degrades to a no-op (one-time warning) where
+  fcntl/flock is unavailable, rather than failing the write.
+- **Path-scoped commits**: each mutating op commits only its own files (`commit(paths=...)`),
+  so a `commit=True` op cannot sweep and mis-attribute a concurrent op's pending change.
+  `GIT_LITERAL_PATHSPECS=1` on every git call.
+
+## v0.4.1 - 2026-06-15
+
+### Docs
+- README rewritten (enterprise style; architecture + `stable`-distribution mermaid diagrams; documents the `stable` "update once" model; AI-setup prompt fixed to `@stable` + `--local`).
+
+### Changed
+- The FastMCP server ships an `instructions` prompt describing the tools + Obsidian/git conventions to connecting agents.
+- Reference deploy artifacts for the `@stable` model: `deploy/obsidian-gateway.service` (uv-tool binary) + `deploy/obsidian-gateway-update.{service,timer}` + `deploy/auto-update.sh`.
+
+### Dependencies
+- `ruamel.yaml` allowed up to `<0.20` (lock 0.19.1; Dependabot).
+
+## v0.4.0 - 2026-06-15
+
+### Security
+- Server-mode **error masking**: the HTTP server runs `mask_error_details=True`; the
+  gateway's expected client-facing failures surface as `ToolError`, while unexpected OS/git
+  errors are hidden from the client.
+
+### Features
+- **`--local` vault auto-detect**: `--local` / `OBSIDIAN_GATEWAY_LOCAL` auto-detects the
+  cwd's vault (cwd-is-vault, `./wiki`, a real `*-obsidian-vault`, a child with `.obsidian/`),
+  so one global codex/antigravity MCP config works in any repo. Explicit `--vault` still
+  wins; a bare invocation still runs the HTTP server.
+
+### Distribution
+- Introduced the moving **`stable`** branch for "update once" rollout (see the header).
+
+## v0.3.0 - 2026-06-15
+
+Security, supply-chain, Obsidian-correctness and test coverage. Re-baselines the project
+after the old `v0.2.0` tag was removed; pin this release's commit SHA (or a future PyPI
+`==0.3.0`).
+
+### Security & supply chain
+- Runtime deps bounded to the current major (`fastmcp>=3,<4`, `pyyaml>=6,<7`, `ruamel.yaml>=0.18,<0.19`); `uv.lock` committed and CI-verified (`uv lock --check`).
+- `tokens.yaml` is refused at load time if it is group/world-readable.
+- `atomic_write` preserves an existing note's file mode (a new note is 0644, not mkstemp's 0600).
+- systemd unit hardened with seccomp/capability/rlimit sandboxing (safe for a `--user` unit).
+- CI: Node 24 SHA-pinned actions, Python 3.11-3.13 matrix, ripgrep installed, coverage; Dependabot for github-actions + uv.
+
+### Features & correctness
+- `backlinks` and `rename_note` match the flat note name **case-insensitively** (Obsidian resolves links that way) and accept a trailing `.md` and `^block`.
+- `read_note` rejects a note over 10 MiB; `query_notes` handles a scalar frontmatter `tags:`.
+- `__version__` is sourced from package metadata.
+
+### Tests
+- Coverage 54% -> 82%; added end-to-end tool tests plus rename / gitops / search / security suites.
+
+### Planned
+- PyPI Trusted Publishing, so consumers can `uvx obsidian-gateway==<version>` without a git fetch.
+- Server-mode concurrency hardening (per-note locks, path-scoped commits) and error masking.
+
+## v0.2.0 - removed
+
+Initial release: local stdio + HTTP server, 14 git/Obsidian-aware tools, per-vault ACL,
+path guards. This tag was deleted; use v0.3.0 or later.

knowledge_gateway-0.7.4/LICENSE

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

knowledge_gateway-0.7.4/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: knowledge-gateway
+Version: 0.7.4
+Summary: Filesystem/git-native FastMCP knowledge gateway: serve an Obsidian vault over MCP, plus optional code-graph and doc-to-markdown tools (formerly obsidian-gateway)
+Project-URL: Homepage, https://github.com/fszalaj/knowledge-gateway
+Project-URL: Repository, https://github.com/fszalaj/knowledge-gateway
+Project-URL: Issues, https://github.com/fszalaj/knowledge-gateway/issues
+Author: Filip Szalaj
+License: MIT
+License-File: LICENSE
+Keywords: ansible,code-graph,fastmcp,git,knowledge-base,knowledge-graph,markdown,mcp,obsidian,tree-sitter,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: fastmcp<4,>=3
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: ruamel-yaml<0.20,>=0.18
+Provides-Extra: all
+Requires-Dist: markitdown>=0.1; extra == 'all'
+Requires-Dist: networkx<4,>=3.4; extra == 'all'
+Requires-Dist: tree-sitter-language-pack>=0.7; extra == 'all'
+Provides-Extra: convert
+Requires-Dist: markitdown>=0.1; extra == 'convert'
+Provides-Extra: dev
+Requires-Dist: networkx<4,>=3.4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: networkx<4,>=3.4; extra == 'graph'
+Provides-Extra: graph-all
+Requires-Dist: networkx<4,>=3.4; extra == 'graph-all'
+Requires-Dist: tree-sitter-language-pack>=0.7; extra == 'graph-all'
+Description-Content-Type: text/markdown
+
+# knowledge-gateway
+
+<!-- mcp-name: io.github.fszalaj/knowledge-gateway -->
+
+> Formerly **obsidian-gateway**. Renamed because it is no longer just a vault wrapper - it is a
+> filesystem- and git-native **knowledge gateway** for AI agents. The package, CLI, and MCP
+> display name are now `knowledge-gateway`; the MCP server is still keyed `wiki` in client configs.
+
+A single MCP server that gives agents (Claude Code, Codex, Cursor, Gemini, Copilot, Antigravity)
+three capabilities over one connection:
+
+- **Vault** - read, search, and **edit** a git-backed Markdown/Obsidian vault (no Obsidian GUI), git as the source of truth.
+- **Code graph** *(optional `[graph]` / `[graph-all]`)* - build and query a code/Ansible knowledge graph of a repo (functions, calls, roles, tasks, handlers, `task -> filter` edges); AST-only, local, no LLM.
+- **Convert** *(optional `[convert]`)* - turn PDF / Office / image / HTML files into Markdown.
+
+The vault layer exists because the Obsidian *Local REST API* plugin serves only the one vault open
+in a running desktop instance, writes without a lock (silent lost updates), needs a token in every
+client, and treats git as secondary. This gateway operates on the files directly, with git as the
+system of record - and adds the graph + convert tools the same way: one server, opt-in extras, no
+new servers to wire.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph clients [Agents]
+        A1[Claude Code]
+        A2[Codex]
+        A3[Antigravity / Cursor]
+    end
+    A1 --- M(( MCP ))
+    A2 --- M
+    A3 --- M
+    M -->|stdio, per repo, no auth| L[Local gateway]
+    M -->|HTTP + bearer + ACL| S[Shared gateway]
+    L --> V[/Vault: Markdown files/]
+    S --> V
+    V <-->|atomic write + scoped commit| G[(git)]
+```
+
+Both modes run the **same** tool implementation over the **same** path guards; they differ in
+transport, authentication/ACL, vault loading, and error masking.
+
+## Two ways to run
+
+| | **Local mode** (per repo) | **Shared server** (team) |
+|---|---|---|
+| Use when | a repo wants its own vault for its agents | many people/vaults behind one always-on endpoint |
+| Transport | stdio subprocess (launched by `.mcp.json`) | HTTP (put behind Tailscale/HTTPS) |
+| Secrets / tokens | **none** - nothing to generate | per-user bearer tokens (admin-generated) |
+| Trust boundary | local filesystem access you already have | tailnet + HTTPS + per-vault ACL |
+| Obsidian needed | no | no |
+
+Most repos want **Local mode**. The shared server is only for a central, always-on team gateway.
+
+## Distribution - the `stable` branch ("update once")
+
+The gateway ships from one moving branch, so a release reaches every consumer and server
+without re-pinning anything by hand.
+
+```mermaid
+flowchart LR
+    PR[merge PR to main] --> TAG[tag vX.Y.Z]
+    TAG --> MV[move stable -> vX.Y.Z]
+    MV --> C["Consumers<br/>uvx --refresh @stable<br/>(updates next session)"]
+    MV --> S["Servers<br/>daily uv tool reinstall<br/>(restart if stable moved)"]
+```
+
+- **Consumers** pin `@stable` with `uvx --refresh` -> the ref is re-fetched on every launch, so
+  a new release auto-propagates the next time an agent starts. No per-repo re-pin.
+- **Servers** (long-running) run a pinned `uv tool install @stable` plus a daily job that
+  reinstalls + restarts only when `stable` actually moves.
+- Every release is **also** an immutable `vX.Y.Z` tag - pin a tag instead of `stable` when you
+  need a frozen, auditable version.
+
+> A moving *tag* does not work (uvx caches the resolved commit); a *branch* + `--refresh` does.
+
+## Quickstart - local mode (zero secrets)
+
+Add this to the repo's `.mcp.json` at the repo root:
+
+```jsonc
+{
+  "mcpServers": {
+    "wiki": {
+      "command": "uvx",
+      "args": ["--refresh", "--from", "git+https://github.com/fszalaj/knowledge-gateway@stable",
+               "knowledge-gateway", "--local"]
+    }
+  }
+}
+```
+
+- `--local` auto-detects the vault in the cwd, in order: the cwd itself if it has `.obsidian/`,
+  then `./wiki`, then a single `*-obsidian-vault/`, then a single child dir with `.obsidian/`
+  (ambiguous matches error). Pass `--vault ./<dir>` to be explicit.
+- `--refresh` re-fetches `@stable` each launch, so releases auto-apply (adds ~1-2s to start).
+- Commits are scoped to the vault's git subdir and attributed to your own
+  `git config user.name/email`. No token: the trust boundary is local filesystem access.
+
+Open the repo in your agent, approve the `wiki` server once, done.
+
+## Tools
+
+| Tool | |
+|---|---|
+| `list_vaults` | vaults reachable here |
+| `list_notes` | Markdown paths in a vault |
+| `read_note` | raw note content |
+| `list_attachments` / `read_attachment` | list / read binary attachments (image -> inline Image, else File) |
+| `list_canvases` / `read_canvas` / `write_canvas` | list / read / write Obsidian Canvas (nodes, groups, colors) |
+| `search` | ripgrep literal/regex full-text |
+| `backlinks` | notes that `[[wikilink]]` to a note |
+| `list_tags` | inline `#tags` with counts |
+| `query_notes` | find notes by frontmatter `type` / `tag` (headless Dataview-lite) |
+| `write_note` | atomic write (+ optional commit) |
+| `patch_note` | insert after a heading or at top/bottom, no full rewrite (+ commit) |
+| `patch_frontmatter` | update YAML frontmatter keys, body intact (+ commit) |
+| `delete_note` | delete a note (+ optional commit) |
+| `rename_note` | rename/move + rewrite inbound flat `[[wikilinks]]` when the name changes (+ optional commit) |
+| `git_status` / `git_commit` | pending changes / commit (subdir-scoped, attributed) |
+| `list_graphs` / `graph_query` / `graph_neighbors` / `god_nodes` / `graph_shortest_path` / `graph_stats` | query a built code graph (optional `[graph]`) |
+| `graph_build` | build a code/Ansible graph from a source tree into `.graph/<name>.json` (local mode only) |
+| `convert_to_markdown` | convert a file (PDF/Office/image/HTML/...) in the vault to Markdown (optional `[convert]`) |
+
+Edits are atomic (temp file + `rename`). Every path goes through `safe_note_path`, which blocks
+traversal, symlink escape, hidden/dotfiles, non-`.md` targets, and `.git`/`.obsidian` - a caller
+can never read or write outside the vault's notes.
+
+## Code graph and conversion (optional)
+
+Two opt-in capabilities, gated behind extras so the core install stays dependency-free:
+
+| Extra | Adds |
+|---|---|
+| `[graph]` | Python (`ast`) + Ansible (PyYAML) code graph + the query tools |
+| `[graph-all]` | the above plus a broad tree-sitter pass (JS/TS/Go/Rust/Terraform/bash/PowerShell/...) |
+| `[convert]` | attachment -> Markdown via markitdown |
+
+**Build a graph** (AST-only - local, no network, no LLM) where the code lives:
+
+```bash
+knowledge-gateway-graph /path/to/code-repo -o /path/to/vault/.graph/myrepo.json
+# in a local-mode session the graph_build tool does the same, writing .graph/<name>.json
+```
+
+**Query it** over MCP with `graph_query` / `graph_neighbors` / `god_nodes` /
+`graph_shortest_path` / `graph_stats`. The graph captures functions/classes/imports/calls and -
+uniquely for Ansible - roles, tasks, handlers, `include_role`/`import_tasks`/`notify`, and
+`task -> filter plugin` edges. Graph files live in the vault's `.graph/`, are vault-contained
+(resolved + checked to stay inside the vault), and are read-only to the gateway - the vault tools
+never depend on them.
+
+## Shared server mode
+
+Run this only for a central, always-on gateway reachable over the network.
+
+**1. Map vaults** - `cp vaults.example.yaml vaults.yaml`, then set `name -> path / repo_root /
+subdir`. `repo_root` + `subdir` pathspec-scope commits to a vault that lives inside a larger repo.
+
+**2. Mint a token per user** (the admin does this):
+
+```bash
+cp tokens.example.yaml tokens.yaml
+openssl rand -hex 32          # once PER user -> the key
+chmod 0600 tokens.yaml        # refused at load if group/world-readable
+```
+
+```yaml
+tokens:
+  "8f3c…hex…":
+    sub: alice                # identity recorded on that user's commits
+    vaults: [teamwiki]        # the ONLY vaults this token may see/touch
+    write: true               # false = read-only
+```
+
+A token sees only the vaults in its `vaults` list; anything else returns an opaque
+`vault_forbidden`. `vaults.yaml` + `tokens.yaml` are gitignored.
+
+**3. Run** - `uv run knowledge-gateway` (127.0.0.1:8765, path `/mcp/`). For a team box, run it as
+a service behind Tailscale Serve - see `deploy/` and *Operate* below.
+
+**4. Connect** - the admin shares the token over a password manager (not chat):
+
+```bash
+claude mcp add --transport http --scope project teamwiki \
+  https://YOUR-HOST.<tailnet>.ts.net/mcp/ --header "Authorization: Bearer $GW_TOKEN"
+```
+
+## Security model
+
+- **No secrets in the repo.** `vaults.yaml` / `tokens.yaml` are gitignored; only
+  `*.example.yaml` ship. `tokens.yaml` is refused at load if group/world-readable.
+- **Local mode has no credential surface** - a local stdio subprocess; the trust boundary is
+  filesystem access the user already has.
+- **Server mode is defense in depth, not a public endpoint** - tailnet ACL + HTTPS + per-user
+  `StaticTokenVerifier` bearer token + per-vault ACL. The bearer layer is a shared secret for
+  use **behind a trusted tailnet**; do not expose the server publicly.
+- **Path guards on all note I/O** via `safe_note_path` (traversal, symlink, hidden/dotfiles
+  incl. `.env`, non-`.md`, `.git`/`.obsidian`). Search/backlinks/tags are bounded to `*.md`.
+- **Server-mode error masking** - the HTTP server runs `mask_error_details=True`: only the
+  gateway's own expected failures surface as `ToolError`; unexpected OS/git errors are hidden.
+  Local mode keeps details visible.
+- **Commits are attributed** to the requesting user (server) or the local git identity (local),
+  and pathspec-scoped to the vault subdir.
+
+## Set it up with an AI
+
+Paste this into an agent at a repo's root to wire in local mode:
+
+```
+Add the knowledge-gateway to this repo so agents can read/edit our vault over MCP with zero
+tokens:
+1. Create or merge `.mcp.json` at the repo root with an mcpServers."wiki" entry that runs:
+   uvx --refresh --from git+https://github.com/fszalaj/knowledge-gateway@stable knowledge-gateway --local
+   (`--local` auto-detects the vault: ./wiki, a *-obsidian-vault dir, or a dir with .obsidian/.
+   If detection is ambiguous, use `--vault ./<vault dir>` instead of `--local`.)
+2. Verify: `uvx --refresh --from git+https://github.com/fszalaj/knowledge-gateway@stable \
+   knowledge-gateway --help` resolves; then in the agent, call list_vaults and read one note.
+Branch + PR, no direct push, no AI attribution.
+```
+
+For the shared server, ask your gateway admin for a token, then run the `claude mcp add …` from
+*Connect* above.
+
+## Operate (servers)
+
+A server runs the `@stable` release as a `uv tool`, with a daily job that reinstalls and
+restarts only when `stable` moved. Reference units are in `deploy/`:
+
+```bash
+uv tool install --from git+https://github.com/fszalaj/knowledge-gateway@stable knowledge-gateway
+# the binary lives in the uv cache, so point config at the live files via env:
+#   KNOWLEDGE_GATEWAY_VAULTS=<dir>/vaults.yaml   KNOWLEDGE_GATEWAY_TOKENS=<dir>/tokens.yaml
+```
+
+- `deploy/knowledge-gateway.service` - the service (systemd `--user`).
+- `deploy/knowledge-gateway-update.{service,timer}` + `deploy/auto-update.sh` - the daily auto-update.
+
+Update now instead of waiting for the timer: `uv tool install --reinstall --from
+git+https://github.com/fszalaj/knowledge-gateway@stable knowledge-gateway`, then restart the
+service. Health: `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8765/mcp/` -> `401`.
+
+## Release (maintainers)
+
+1. PR -> merge to `main` (CI: `uv lock --check`, pytest matrix).
+2. Bump `pyproject.toml` version + `CHANGELOG.md`.
+3. Tag `vX.Y.Z` and push the tag (the release workflow builds it).
+4. Move `stable`: `git branch -f stable vX.Y.Z && git push --force-with-lease origin stable`.
+
+Consumers pick it up next session; servers within a day (or restart now).
+
+## Develop
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+uv run pytest                              # ACL + path guards + edit/frontmatter + detect + masking
+```