beeweave 0.1.0__tar.gz

beeweave-0.1.0/.env.example

@@ -0,0 +1,110 @@
+# =============================================================================
+# BeeWeave — Environment Configuration
+# Copy this to .env and set your vault path
+# =============================================================================
+
+# --- Required ---
+
+# Path to your Obsidian vault. setup expands this to an absolute path and
+# creates the compiled knowledge layer at the location you choose.
+BEEWEAVE_VAULT_PATH=./vault
+
+# --- Optional ---
+
+# GitHub remote for vault sync (set by setup.sh when you enable GitHub sync)
+# wiki-sync uses this to push committed vault changes
+VAULT_GITHUB_REMOTE=
+
+# Comma-separated source directories to ingest documents from.
+# The workbench is the creation layer; ingest pending inputs and stable
+# drafts/research from here.
+BEEWEAVE_SOURCES_DIR=./workbench
+
+# Workbench inbox for unprocessed captures and web clippings.
+BEEWEAVE_INBOX_DIR=./workbench/inbox
+
+# Wiki categories (directories created in the vault)
+BEEWEAVE_CATEGORIES=concepts,entities,skills,references,synthesis,projects
+
+# Max pages to create/update per ingest operation
+BEEWEAVE_MAX_PAGES_PER_INGEST=15
+
+# Projects to exclude from history ingest (claude/codex/hermes/… history-ingest skills).
+# Comma-separated substrings matched against the project directory name. A project
+# dir whose name contains any of these is skipped during scan, delta, and manifest steps.
+# Example: WIKI_SKIP_PROJECTS=archived,scratch,sandbox
+WIKI_SKIP_PROJECTS=
+
+# Claude conversation history path (auto-discovered from ~/.claude if empty)
+CLAUDE_HISTORY_PATH=
+
+# Codex history path (defaults to ~/.codex if empty)
+CODEX_HISTORY_PATH=
+
+# Pi agent session history path (defaults to ~/.pi/agent/sessions if empty)
+PI_HISTORY_PATH=
+
+# Lint schedule: daily | weekly | manual
+LINT_SCHEDULE=weekly
+
+# Internal link format for generated/updated pages
+# wikilink (default) → [[concepts/foo]] or [[concepts/foo|display text]]
+# markdown           → [display text](relative/path.md)
+# Only affects future writes — existing vault content is never migrated automatically.
+BEEWEAVE_LINK_FORMAT=wikilink
+
+# --- QMD Semantic Search (optional) ---
+#
+# QMD indexes your wiki and sources for fast semantic search.
+# Install: https://github.com/tobi/qmd
+# After installing, point these at your QMD collection names (set when you ran `qmd index`).
+#
+# Without QMD: wiki-ingest and wiki-query fall back to Grep/Glob — fully functional, just slower.
+# With QMD: semantic search replaces grep passes, enabling concept-level matches and cross-collection queries.
+
+# Name of the QMD collection indexing your compiled wiki pages (BEEWEAVE_VAULT_PATH)
+QMD_WIKI_COLLECTION=
+
+# Name of the QMD collection indexing your source documents (BEEWEAVE_SOURCES_DIR)
+QMD_PAPERS_COLLECTION=
+
+# QMD integration transport: mcp | cli
+# mcp preserves the original behavior and uses an agent-configured QMD MCP server.
+# cli runs the local qmd command directly; useful for agents without QMD MCP support.
+QMD_TRANSPORT=mcp
+
+# CLI search quality mode: quality | balanced | fast
+# quality: qmd query with reranking (best relevance, slowest on CPU)
+# balanced: qmd query --no-rerank (good hybrid results, faster)
+# fast: qmd vsearch (semantic only) or qmd search when exact terms matter
+QMD_CLI_SEARCH_MODE=quality
+
+# Optional qmd binary override if qmd is not on PATH.
+QMD_CLI=qmd
+
+# --- Vault Skill Factory (optional) ---
+#
+# vault-skill-factory turns mature curated pages into portable Agent Skills.
+# Generated skills land in a REVIEW directory — never auto-installed, never written to .skills/.
+#
+# Where generated skills are written (default: <BEEWEAVE_VAULT_PATH>/_generated-skills — a
+# vault-level excluded dir like _meta/_staging, NOT the skills/ knowledge category).
+SKILL_FACTORY_OUTPUT_DIR=
+# Which lifecycle states count as "mature" enough to harvest (pages with tier: core also qualify).
+SKILL_FACTORY_MATURITY=reviewed,verified
+# --- PageIndex: structure-aware long-PDF preprocessing (optional) ---
+#
+# For long PDFs (books, reports), build a table-of-contents tree (section titles +
+# summaries + page ranges) before ingest, so the agent reads only relevant sections.
+# Install: clone https://github.com/VectifyAI/PageIndex, create a venv (uv), and put an
+# LLM key in <repo>/.env (LiteLLM; e.g. deepseek/deepseek-v4-flash or openai/glm-4.6).
+# See wiki-ingest/references/pageindex.md. Without it: wiki-ingest reads PDFs directly.
+#
+# Path to the PageIndex repo (enables the wiki-ingest long-PDF branch).
+PAGEINDEX_REPO=
+# LiteLLM model id PageIndex uses (default openai/glm-4.6).
+PAGEINDEX_MODEL=openai/glm-4.6
+# Only preprocess PDFs with at least this many pages.
+PAGEINDEX_MIN_PAGES=30
+# Optional cache dir for *_structure.json (default: <PAGEINDEX_REPO>/results).
+PAGEINDEX_WORKSPACE=

beeweave-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,162 @@
+# BeeWeave — Copilot Context
+
+BeeWeave is an **agent-native creation workbench** for building a creative data
+flywheel: collect source material, create with agents, distill durable
+knowledge, reuse that knowledge as context, then collect better material for
+the next loop.
+
+This repository contains the Python CLI, bundled skills, bootstrap templates,
+browser extension assets, tests, and documentation used to install and maintain
+BeeWeave workspaces.
+
+## Project Overview
+
+- **Purpose:** Help agents and humans move material through a structured loop:
+  `collect -> create -> distill -> reuse context -> collect better`.
+- **Runtime model:** `workbench/` is the staging and drafting area; `vault/` is
+  the compiled markdown knowledge base.
+- **CLI:** The public console command is `bwe`.
+- **Package:** Python package code lives under `beeweave/`; package metadata and
+  the CLI entrypoint live in `pyproject.toml`.
+- **Skills:** Source skills live under `.skills/wiki/` and
+  `.skills/workbench/`. Each skill folder uses a `SKILL.md` workflow file.
+- **Bootstrap:** Agent-facing setup templates live under `bootstrap/`.
+- **Extension:** Browser capture assets live under `extensions/brain-capture/`.
+
+## Key Concepts
+
+- BeeWeave is a loop, not a one-way archive.
+- Raw inputs, drafts, captures, web clips, and source libraries belong in
+  `workbench/`.
+- Stable reusable knowledge belongs in `vault/` as markdown with metadata and
+  Obsidian-style `[[wikilinks]]`.
+- The vault is a compiled artifact: concepts, entities, references, project
+  notes, synthesis pages, and graph-ready relationships distilled from higher
+  signal material.
+- Setup-generated runtime `vault/` and `workbench/` directories should not be
+  committed to this repository.
+
+## Runtime Layout
+
+BeeWeave setup creates this structure inside a user-selected workspace:
+
+```text
+project/
++-- vault/                  # durable markdown knowledge
+|   +-- concepts/
+|   +-- entities/
+|   +-- skills/
+|   +-- references/
+|   +-- synthesis/
+|   +-- projects/
+|   +-- _meta/
+|   +-- _archives/
+|   +-- _staging/
+|   +-- .obsidian/
++-- workbench/              # staging and drafting area
+    +-- inbox/
+    |   +-- captures/
+    |   +-- web/
+    |   +-- archived/
+    |   +-- rejected/
+    +-- articles/
+    |   +-- drafts/
+    |   +-- published/
+    +-- library/
+```
+
+Keep repository development files separate from this runtime layout.
+
+## Install and Configuration Model
+
+- Users install from PyPI with `pip install beeweave`, then run `bwe setup`.
+- Source-checkout setup is also supported with `bash setup.sh`.
+- Global config is written under `~/.beeweave/config`.
+- BeeWeave config uses `BEEWEAVE_*` names such as `BEEWEAVE_VAULT_PATH`,
+  `BEEWEAVE_REPO`, and `BEEWEAVE_VERSION`.
+- Named vault routing uses request-local `@name` overrides that resolve to
+  files such as `~/.beeweave/config.work`.
+
+## Skill Install Policy
+
+Global installs are intentionally small.
+
+Always global by default:
+
+- `beeweave-update`: sync useful project knowledge into the vault
+- `beeweave-query`: answer questions from the compiled vault
+- `beeweave-ingest`: process source material into durable notes
+
+Optional advanced global skills include:
+
+- `beeweave-capture`
+- `beeweave-context-pack`
+- `beeweave-digest`
+- `beeweave-status`
+- `beeweave-memory-bridge`
+
+All other BeeWeave skills remain project-local by default. When changing setup
+behavior, preserve this split unless the README and tests are updated together.
+
+## Important Skills
+
+- `.skills/wiki/beeweave-setup/`: initialize a BeeWeave workspace.
+- `.skills/wiki/beeweave-ingest/`: distill source material into durable vault
+  notes.
+- `.skills/wiki/beeweave-query/`: answer from the compiled vault.
+- `.skills/wiki/beeweave-update/`: preserve durable decisions or lessons from
+  current project work.
+- `.skills/wiki/beeweave-synthesize/`: find cross-cutting connections after
+  the vault has grown.
+- `.skills/wiki/beeweave-status/`: inspect ingest status and vault health.
+- `.skills/workbench/beeweave-article-writer/`: draft long-form articles from
+  workbench material.
+- `.skills/workbench/beeweave-social-writer/`: turn findings into short-form
+  social writing.
+
+## Repository Layout
+
+```text
+beeweave/        # Python CLI and helpers
+.skills/         # source skill definitions
+bootstrap/       # user-project bootstrap templates and agent rules
+extensions/      # browser extension assets
+tests/           # pytest suite
+openspec/        # proposed and active change specs
+setup.sh         # source-checkout setup path
+pyproject.toml   # package metadata and bwe entrypoint
+```
+
+## Coding and Documentation Conventions
+
+- Prefer existing CLI, setup, bootstrap, and skill patterns over new
+  abstractions.
+- Keep implementation changes scoped to the active request.
+- Preserve the public CLI command as `bwe`.
+- Keep generated user-project instructions in `bootstrap/AGENTS.md`, not the
+  repository root `AGENTS.md`.
+- Do not generate `.hermes.md`; Hermes uses `HERMES.md`.
+- Do not recreate runtime `vault/` or `workbench/` directories in the repo root.
+- Do not commit project-local generated skill mirrors such as
+  `.claude/skills/`.
+- When creating vault pages in skills or docs, use YAML frontmatter and
+  Obsidian `[[wikilinks]]`.
+- Do not modify `.obsidian/` except through explicit graph-related behavior
+  such as `beeweave-graph-colorize`.
+
+## Verification
+
+Use focused checks for small documentation-only edits. When behavior changes,
+run:
+
+```bash
+uv run pytest
+uv run bwe setup --help
+uv run bwe info
+```
+
+For OpenSpec-backed changes, also run:
+
+```bash
+openspec validate <change-name> --strict
+```

beeweave-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,74 @@
+name: publish
+
+# Build and publish beeweave to PyPI when a version tag is pushed.
+#
+# Setup (one-time): on PyPI, add a Trusted Publisher for this repo with
+# workflow `publish.yml` and environment `pypi`. No API token needed — the
+# `id-token: write` permission below mints a short-lived OIDC credential.
+#
+# Release: bump `version` in pyproject.toml, commit, then
+#   git tag v0.1.0 && git push origin v0.1.0
+
+on:
+  push:
+    tags:
+      - "v*"
+  # Allow a manual build (artifacts only, no publish) for verification.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Verify wheel bundles the skills
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+          wheel=$(ls dist/*.whl)
+          echo "Inspecting $wheel"
+          if ! python -m zipfile -l "$wheel" | grep -q "beeweave/_data/skills/wiki/beeweave-setup/SKILL.md"; then
+            echo "::error::wheel is missing bundled skills under beeweave/_data/skills/"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Only publish on a real tag push, not workflow_dispatch.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+      contents: write  # required for creating GitHub Releases
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" dist/* \
+            --repo "${{ github.repository }}" \
+            --title "${{ github.ref_name }}" \
+            --generate-notes

beeweave-0.1.0/.github/workflows/setup.yml

@@ -0,0 +1,29 @@
+name: setup
+
+# Guards setup.sh against the regression where it rewrites committed
+# relative symlinks with absolute paths (or any other modification to
+# tracked files). See #52 for the original bug.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  install-leaves-tree-clean:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run setup.sh
+        # stdin closed so the vault-path prompt returns empty rather than hang
+        run: bash setup.sh < /dev/null
+      - name: Working tree must be unchanged
+        run: |
+          if ! git diff --exit-code; then
+            echo "::error::setup.sh modified tracked files. Likely cause: an" \
+                 "in-repo symlink mirror is being written with an absolute" \
+                 "target instead of a relative one. See install_skills() in setup.sh."
+            exit 1
+          fi
+      - name: Re-run is idempotent
+        run: bash setup.sh < /dev/null && git diff --exit-code

beeweave-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+.env
+.DS_Store
+.venv/
+.pytest_cache/
+*.pyc
+__pycache__/
+tmp/
+
+# Python build artifacts (pyproject.toml / `python -m build`)
+/dist/
+/build/
+*.egg-info/
+
+# Agent skill symlinks (created by setup.sh) — these are just pointers to .skills/
+# We track them so cloners get the symlinks too, but if your git doesn't
+# preserve symlinks, run `bash setup.sh` after cloning.
+
+.serena/
+openspec/
+
+# Obsidian local workspace/cache files inside the monorepo vault
+/vault/.obsidian/workspace.json
+/vault/.obsidian/workspace-mobile.json
+/vault/.obsidian/cache/
+/vault/.trash/
+
+# Local render/output byproducts; keep source drafts in workbench tracked
+/workbench/exports/*
+!/workbench/exports/.gitkeep

beeweave-0.1.0/.skills/README.md

@@ -0,0 +1,154 @@
+# BeeWeave Skills
+
+BeeWeave skills are markdown instructions that agents read when a workflow is
+triggered. They live under `.skills/` and are installed in two different ways:
+
+- **Project-local skills**: the full skill set, installed into a project agent
+  directory such as `.claude/skills/`, `.codex/skills/`, or `.agents/skills/`.
+- **Global skills**: a small portable subset, installed into global agent
+  directories such as `~/.claude/skills/` or `~/.codex/skills/`.
+
+The global set is intentionally small. Too many globally visible skills make
+agents harder to predict and users harder to orient.
+
+## Global Skill Policy
+
+By default, BeeWeave installs only three global skills:
+
+```text
+beeweave-update
+beeweave-query
+beeweave-ingest
+```
+
+These are the core cross-project workflows:
+
+| Skill | What it does | Why global |
+|---|---|---|
+| `beeweave-update` | Sync the current project's durable knowledge into the vault | Useful from any codebase |
+| `beeweave-query` | Ask questions against the compiled vault | Read-only and useful anywhere |
+| `beeweave-ingest` | Distill documents, URLs, exports, logs, and inbox captures into wiki pages | General source-ingest entrypoint |
+
+Advanced users can explicitly add a few recommended extra global skills:
+
+```bash
+bwe setup --global-extra beeweave-capture,beeweave-context-pack
+bash setup.sh --global-extra beeweave-capture,beeweave-context-pack
+```
+
+Supported extras:
+
+| Skill | What it does | Notes |
+|---|---|---|
+| `beeweave-capture` | Save current-session findings to inbox/wiki | Prefer quick capture to inbox, then promote with `beeweave-ingest` |
+| `beeweave-context-pack` | Package vault context for another agent or task | Pulls knowledge from vault; it does not save the current chat |
+| `beeweave-digest` | Generate a daily, weekly, monthly, or custom-period knowledge digest | Useful for review workflows |
+| `beeweave-status` | Show ingest status, pending delta, and vault health | Operational overview |
+| `beeweave-memory-bridge` | Browse and compare knowledge by source agent | Most useful after importing multiple agent histories |
+
+## Install Shape
+
+Interactive setup shows the same shape:
+
+```text
+Global skills
+  Always installed:
+    [x] beeweave-update
+    [x] beeweave-query
+    [x] beeweave-ingest
+
+  Optional advanced global skills:
+    [ ] beeweave-capture
+    [ ] beeweave-context-pack
+    [ ] beeweave-digest
+    [ ] beeweave-status
+    [ ] beeweave-memory-bridge
+
+Workbench/project-local skills:
+  beeweave-article-writer — long-form articles, blog posts, essays, and opinion pieces
+  beeweave-social-writer  — X/Twitter posts, threads, short takes, and social copy
+```
+
+After global skill selection, setup asks which agents to install for.
+
+## Wiki Skills
+
+Everything below lives under `.skills/wiki/`. Project-local installs get the
+full set.
+
+| Skill | What it does | Global recommendation |
+|---|---|---|
+| `beeweave-update` | Sync durable knowledge from the current project into the vault: architecture decisions, patterns, key abstractions, trade-offs, and project context | Default global |
+| `beeweave-query` | Search and synthesize answers from the compiled vault, including multi-hop relationship queries and fast summary-only lookup | Default global |
+| `beeweave-ingest` | Distill external sources into interconnected wiki pages: documents, folders, PDFs, URLs, logs, transcripts, exports, raw text, and `workbench/inbox` captures | Default global |
+| `beeweave-capture` | Preserve the current conversation or session findings as structured wiki knowledge; quick mode stages files under `workbench/inbox/captures/` | Optional extra |
+| `beeweave-context-pack` | Produce a token-bounded context pack from vault pages for another agent, skill, or downstream task | Optional extra |
+| `beeweave-digest` | Generate a human-readable knowledge digest for a day, week, month, or custom period | Optional extra |
+| `beeweave-status` | Report what has been ingested, what is pending, source delta, token footprint, and graph structure insights | Optional extra |
+| `beeweave-memory-bridge` | Browse and diff wiki knowledge by source tool, such as Claude vs Codex vs Hermes | Optional extra |
+| `beeweave-core` | Explain the underlying LLM Wiki pattern, vault schema, frontmatter, relationships, retrieval primitives, and config resolution protocol | Project-local |
+| `beeweave-setup` | Initialize vault structure, special files, Obsidian config, `.env`, and optional capture hooks | Project-local |
+| `beeweave-switch` | Manage named vault profiles under `~/.beeweave/config.NAME` and switch the active default vault | Project-local |
+| `beeweave-lint` | Audit vault health: orphan pages, broken links, missing frontmatter, missing summaries, stale content, contradictions, and optional consolidation | Project-local |
+| `beeweave-cross-linker` | Scan the vault and insert missing `[[wikilinks]]` to strengthen the knowledge graph | Project-local |
+| `beeweave-tag-taxonomy` | Audit and normalize tags using the controlled vocabulary in `_meta/taxonomy.md` | Project-local |
+| `beeweave-dedup` | Detect identity collisions and merge duplicate pages under different names | Project-local |
+| `beeweave-rebuild` | Archive, rebuild, or restore the vault | Project-local |
+| `beeweave-daily-update` | Run a daily maintenance pass: source freshness, index refresh, hot cache update, and optional cron/notification setup | Project-local |
+| `beeweave-stage-commit` | Review and promote staged pages from `_staging/` when `WIKI_STAGED_WRITES=true` | Project-local |
+| `beeweave-impl-validator` | Validate whether an implementation or skill output matches its stated goal; often used as a helper subagent | Project-local |
+| `beeweave-graph-colorize` | Rewrite Obsidian graph color groups by tag, folder, category, or visibility | Project-local |
+| `beeweave-dashboard` | Create Obsidian Bases or Dataview dashboard views over vault content | Project-local |
+| `beeweave-synthesize` | Discover synthesis opportunities across concepts and create `synthesis/` pages | Project-local |
+| `beeweave-research` | Run multi-round web research and file the results into the vault | Project-local |
+| `beeweave-export` | Export the vault graph to JSON, GraphML, Neo4j Cypher, browser HTML, or OKF markdown bundle | Project-local |
+| `beeweave-import` | Import from `graph.json` stubs or an OKF markdown bundle into the current vault | Project-local |
+| `beeweave-vault-skill-factory` | Generate a portable Agent Skill from mature vault pages into a review directory | Project-local |
+| `beeweave-skill-creator` | Create, edit, package, benchmark, and improve Agent Skills | Project-local |
+| `beeweave-history-ingest` | Route agent-history ingestion requests to the specialized history skill for the selected tool | Project-local |
+| `beeweave-agent` | Search a specific agent's raw history by topic, ingest the relevant sessions, and return a synthesized answer | Project-local |
+| `beeweave-claude-ingest` | Mine Claude Code and Claude desktop history, memory files, sessions, and audit logs into the vault | Project-local |
+| `beeweave-codex-ingest` | Mine Codex CLI sessions, rollout logs, and session indexes into the vault | Project-local |
+| `beeweave-copilot-ingest` | Mine GitHub Copilot CLI and VS Code Copilot Chat history into the vault | Project-local |
+| `beeweave-hermes-ingest` | Mine Hermes memories and sessions into the vault | Project-local |
+| `beeweave-openclaw-ingest` | Mine OpenClaw `MEMORY.md`, daily notes, and session logs into the vault | Project-local |
+| `beeweave-pi-ingest` | Mine Pi coding agent session history into the vault | Project-local |
+
+## Workbench Skills
+
+Creation-specific skills live under `.skills/workbench/`. They are installed
+project-locally with the full skill set, not globally.
+
+| Skill | What it does |
+|---|---|
+| `beeweave-article-writer` | Long-form articles, blog posts, essays, and opinion pieces |
+| `beeweave-social-writer` | X/Twitter posts, threads, short takes, and social copy |
+
+## Why Most Skills Stay Local
+
+Many BeeWeave skills are powerful maintenance or migration tools. They are
+useful, but they should only appear when the user is intentionally working on
+the vault or workbench.
+
+Keep these local by default:
+
+- **High-impact writes**: `beeweave-rebuild`, `beeweave-dedup`, `beeweave-import`, `beeweave-stage-commit`
+- **Vault maintenance**: `beeweave-lint`, `beeweave-cross-linker`, `beeweave-tag-taxonomy`, `beeweave-synthesize`
+- **Machine setup**: `beeweave-setup`, `beeweave-switch`, `beeweave-daily-update`
+- **Agent history mining**: `beeweave-history-ingest`, `beeweave-agent`, and all agent-specific history ingest skills
+- **Skill development**: `beeweave-skill-creator`, `beeweave-vault-skill-factory`, `beeweave-impl-validator`
+- **Obsidian-specific UI/config**: `beeweave-graph-colorize`, `beeweave-dashboard`
+
+This keeps the global surface area small while preserving the full BeeWeave
+toolbox inside project-local installs.
+
+## OKF
+
+OKF means **Open Knowledge Format** in BeeWeave's export/import workflow.
+
+- `beeweave-export` can create an OKF markdown bundle.
+- `beeweave-import` can import an OKF bundle into another vault.
+- Unlike `graph.json`, which is mostly a graph skeleton, OKF preserves full
+  markdown page bodies and is better for vault-to-vault transfer.
+
+Use OKF when you want to move knowledge, not just inspect the graph.