# Setup

1. **Clone and install** — `git clone <repo> && cd knowtation && npm install`. (If you are copying this seed to a new repo instead, see [COPY-TO-REPO.md](../COPY-TO-REPO.md).)
2. **Config** — Copy `config/local.example.yaml` to `config/local.yaml` and set `vault_path` (absolute path to `vault/`, e.g. `$(pwd)/vault`). For search without Qdrant: set `vector_store: sqlite-vec` and `data_dir: data/`. Optionally set `qdrant_url` and embedding provider. Do not commit `config/local.yaml`.
3. **Secrets** — Copy `.env.example` to `.env` and set API keys. `.env` is gitignored and loaded automatically.
   - **Two lanes:** **Embeddings** (Meaning search / `knowtation index`) and **chat** (Hub proposal Enrich, review hints, `completeChat` in [`lib/llm-complete.mjs`](../lib/llm-complete.mjs)) use **different** providers in config/env. Anthropic powers **chat only** (Messages API); it does **not** offer a public embeddings API for vectors.
   - **Embeddings:** `config/local.yaml` → `embedding: { provider, model }`, optionally overridden by **`EMBEDDING_PROVIDER`** / **`EMBEDDING_MODEL`**. Providers: **`ollama`** (default), **`openai`** (`OPENAI_API_KEY`), **`voyage`** (`VOYAGE_API_KEY`, good cloud option if you want non–OpenAI vectors). Changing embed model or dimension requires a **full re-index** (existing sqlite-vec / Qdrant dimensions must match).
   - **Chat:** `OPENAI_API_KEY` is tried first, then `ANTHROPIC_API_KEY`, then Ollama (`OLLAMA_URL` + chat model). Set **`KNOWTATION_CHAT_PREFER_ANTHROPIC=1`** (or `true`) to try **Anthropic before OpenAI** when **both** keys are set (with OpenAI as fallback if Claude fails).
   - **Transcription** still uses `OPENAI_API_KEY` when using Whisper (see step 8).
4. **Vault** — Open your vault folder (see `vault_path` in config) in Obsidian or any Markdown editor.
5. **Index (for semantic search)** — Run once: `knowtation index` or `npm run index` or `node scripts/index-vault.mjs`. You need:
   - **Vector store** (pick one in `config/local.yaml`): **`sqlite-vec`** + `data_dir: data/` — vectors live in a local SQLite file (no extra server; easiest for self-hosted). **Or** **`qdrant`** + `qdrant_url` — vectors live in a separate Qdrant service (Docker or cloud).
   - **Embeddings** (pick one): **Ollama** — install [ollama.ai](https://ollama.ai), run `ollama pull nomic-embed-text`, set `embedding: { provider: ollama, model: nomic-embed-text }` in config. **Or** **OpenAI** — set `OPENAI_API_KEY` in `.env` and `embedding: { provider: openai, model: text-embedding-3-small }` in config. **Or** **Voyage** — [Voyage AI](https://www.voyageai.com/) embeddings API: set `VOYAGE_API_KEY` and `embedding: { provider: voyage, model: voyage-4-lite }` (or another [Voyage model](https://docs.voyageai.com/docs/embeddings)); you can also set `EMBEDDING_PROVIDER=voyage` and `EMBEDDING_MODEL=voyage-4-lite` in `.env`.
   After indexing, CLI and Hub semantic search have data. Listing notes in the Hub works without indexing; **Search vault** needs this step on self-hosted.
6. **CLI** — From repo root: `node cli/index.mjs --help`, `node cli/index.mjs list-notes`, `node cli/index.mjs get-note <path>`, `node cli/index.mjs index`, `node cli/index.mjs search "query"`, `write`, `export`, `import`. Use `--json` for machine output.
7. **Capture (optional)** — File-based: `echo "Note" | node scripts/capture-file.mjs --source file --source-id id123`. Webhook: `node scripts/capture-webhook.mjs --port 3131` then POST `/capture` with JSON. See [docs/CAPTURE-CONTRACT.md](./CAPTURE-CONTRACT.md).
8. **Transcription (optional)** — `node cli/index.mjs import audio ./recording.mp3` (requires OPENAI_API_KEY in `.env`). See [docs/PHASE7-MANUAL-TEST.md](./PHASE7-MANUAL-TEST.md).
9. **Memory (optional)** — Set `memory.enabled: true` in config to store last search and export provenance. Query with `knowtation memory query last_search` or `last_export`.
10. **Agents** — The skill in `.cursor/skills/knowtation/SKILL.md` is auto-discovered by Cursor when this repo is open. For global use, copy that skill folder to `~/.cursor/skills/knowtation/`. For **MCP** (Cursor, Claude Desktop), run `node cli/index.mjs mcp` or `npm run mcp` and configure per [docs/AGENT-ORCHESTRATION.md](./AGENT-ORCHESTRATION.md).
11. **Hub (optional)** — Self-hosted API + OAuth + JWT for shared vault and proposals. From repo root: `cd hub && npm install && cd ..`, set `KNOWTATION_VAULT_PATH` and `HUB_JWT_SECRET`, then `npm run hub`. Open **`http://localhost:3333/`** in a browser (Rich Hub UI is served by the same server). Log in with Google/GitHub if OAuth env vars are set; otherwise use the API only. See [hub/README.md](../hub/README.md) and [docs/HUB-API.md](./HUB-API.md). CLI: `knowtation hub status --hub http://localhost:3333`, `knowtation propose <path> --hub <url> --intent "..."` (requires `KNOWTATION_HUB_TOKEN`).

**Hosted admin (operators):** On the hosted product (knowtation.store), admins are designated by setting **`HUB_ADMIN_USER_IDS`** in the gateway's env (comma-separated user IDs, e.g. `google:108077705743543803349`). Users in that list get role **admin** (Edit, Team tab); others get **member**. See [hub/gateway/README.md](../hub/gateway/README.md).