bikky 0.3.13 → 0.4.0

package/dist/routing.test.js

@@ -0,0 +1,79 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { resolveDestination, buildResolver, DestinationNotFoundError, NoDestinationsConfiguredError, } from "./routing.js";
+const dst = (name, extra = {}) => ({
+    name,
+    qdrant_url: `https://${name}.example`,
+    qdrant_api_key: "k",
+    collection: "bikky",
+    ...extra,
+});
+describe("routing.resolveDestination", () => {
+    it("throws NoDestinationsConfiguredError when list is empty", () => {
+        assert.throws(() => resolveDestination({}, []), NoDestinationsConfiguredError);
+    });
+    it("respects explicit override by name", () => {
+        const a = dst("a");
+        const b = dst("b");
+        assert.equal(resolveDestination({ destination: "b" }, [a, b]).name, "b");
+    });
+    it("throws DestinationNotFoundError when override doesn't match", () => {
+        const a = dst("a");
+        assert.throws(() => resolveDestination({ destination: "ghost" }, [a]), DestinationNotFoundError);
+    });
+    it("matches by cwd regex", () => {
+        const work = dst("work", { match: { cwd: ["/repos/work"] } });
+        const personal = dst("personal", { default: true });
+        assert.equal(resolveDestination({ cwd: "/repos/work/api" }, [work, personal]).name, "work");
+    });
+    it("matches by entity regex", () => {
+        const acme = dst("acme", { match: { entity: ["^acme-"] } });
+        const fallback = dst("fallback", { default: true });
+        assert.equal(resolveDestination({ entities: ["acme-billing"] }, [acme, fallback]).name, "acme");
+    });
+    it("matches by content regex", () => {
+        const secrets = dst("secrets", { match: { content: ["password|secret"] } });
+        const fallback = dst("fallback", { default: true });
+        assert.equal(resolveDestination({ content: "rotated the secret" }, [secrets, fallback]).name, "secrets");
+    });
+    it("matches by metadata regex", () => {
+        const project = dst("project", { match: { metadata: { project: ["^acme$"] } } });
+        const fallback = dst("fallback", { default: true });
+        assert.equal(resolveDestination({ metadata: { project: "acme" } }, [project, fallback]).name, "project");
+    });
+    it("first matching destination wins (array order)", () => {
+        const a = dst("a", { match: { entity: ["foo"] } });
+        const b = dst("b", { match: { entity: ["foo"] } });
+        assert.equal(resolveDestination({ entities: ["foo"] }, [a, b]).name, "a");
+    });
+    it("falls back to default-flagged destination when no match", () => {
+        const a = dst("a", { match: { entity: ["nope"] } });
+        const b = dst("b", { default: true });
+        const c = dst("c");
+        assert.equal(resolveDestination({ entities: ["other"] }, [a, b, c]).name, "b");
+    });
+    it("falls back to first destination when no default flagged", () => {
+        const a = dst("a", { match: { entity: ["nope"] } });
+        const b = dst("b");
+        assert.equal(resolveDestination({ entities: ["other"] }, [a, b]).name, "a");
+    });
+    it("override beats matching", () => {
+        const a = dst("a", { match: { entity: ["foo"] } });
+        const b = dst("b");
+        assert.equal(resolveDestination({ destination: "b", entities: ["foo"] }, [a, b]).name, "b");
+    });
+});
+describe("routing.buildResolver", () => {
+    it("returns a closure that resolves consistently", () => {
+        const a = dst("a", { match: { entity: ["foo"] } });
+        const b = dst("b", { default: true });
+        const resolve = buildResolver([a, b]);
+        assert.equal(resolve({ entities: ["foo"] }).name, "a");
+        assert.equal(resolve({ entities: ["bar"] }).name, "b");
+    });
+    it("closure throws on empty destinations", () => {
+        const resolve = buildResolver([]);
+        assert.throws(() => resolve({}), NoDestinationsConfiguredError);
+    });
+});
+//# sourceMappingURL=routing.test.js.map

package/dist/routing.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.test.js","sourceRoot":"","sources":["../src/routing.test.ts"],"names":[],"mappings":"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"}

package/docs/config/fully-hosted.md

@@ -0,0 +1,57 @@
+# Fully hosted config
+
+Best for performance and teams. This setup uses Qdrant Cloud for managed vector storage and OpenAI-compatible hosted models for extraction, curation, and recall.
+
+## What you need
+
+- A Qdrant Cloud cluster URL.
+- A Qdrant API key.
+- An OpenAI API key, or another hosted provider configured in the full configuration guide.
+
+For both `embedding.provider` and `llm.provider`, possible values are `openai`, `bedrock`, or `portkey` for hosted models. `ollama` is also supported when you want local model calls.
+
+## Config
+
+Save this as `~/.bikky/config.json`:
+
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-qdrant-api-key",
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small",
+    "dimensions": 1536,
+    "api_key": "sk-..."
+  },
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4.1-mini",
+    "api_key": "sk-..."
+  }
+}
+```
+
+`qdrant_api_key` is optional only for unauthenticated self-hosted Qdrant. Qdrant Cloud usually requires it.
+
+Prefer not to store hosted model keys in the config file? Omit `api_key` above and set:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+## Check it
+
+```bash
+bikky status
+```
+
+After changing Qdrant or provider settings, restart long-running processes:
+
+```bash
+bikky stop && bikky start
+```
+
+Then restart your editor so its MCP process reloads.
+
+For Bedrock, Portkey, custom base URLs, or model-specific dimensions, see the [full configuration guide](../configuration.md).

package/docs/config/hosted-models.md

@@ -0,0 +1,50 @@
+# Local Qdrant + hosted models config
+
+This setup keeps Qdrant local while hosted embeddings and LLM calls handle extraction, curation, and recall.
+
+## What you need
+
+- Qdrant running locally, usually with Docker.
+- An OpenAI API key, or another hosted provider configured in the full configuration guide.
+
+For both `embedding.provider` and `llm.provider`, possible values are `openai`, `bedrock`, or `portkey` for hosted models. `ollama` is also supported when you want local model calls.
+
+## Config
+
+Save this as `~/.bikky/config.json`:
+
+```json
+{
+  "qdrant_url": "http://localhost:6333",
+  "qdrant_api_key": "",
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small",
+    "dimensions": 1536,
+    "api_key": "sk-..."
+  },
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4.1-mini",
+    "api_key": "sk-..."
+  }
+}
+```
+
+`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant.
+
+Prefer not to store hosted model keys in the config file? Omit `api_key` above and set:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+## Check it
+
+```bash
+bikky status
+```
+
+If you started from a fresh install, run `bikky setup` after writing the config, then restart your editor so its MCP process reloads.
+
+For Bedrock, Portkey, custom base URLs, or model-specific dimensions, see the [full configuration guide](../configuration.md).

package/docs/config/hosted-qdrant-local-models.md

@@ -0,0 +1,39 @@
+# Hosted Qdrant + local models
+
+Use this path when you want memory shared across machines, but you still want embeddings and background curation to run through local Ollama.
+
+## What you need
+
+- A Qdrant Cloud cluster URL.
+- A Qdrant API key.
+- Ollama installed locally.
+- The default embedding model pulled with `ollama pull qwen3-embedding:0.6b`.
+
+## Config
+
+Save this as `~/.bikky/config.json`:
+
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-qdrant-api-key"
+}
+```
+
+bikky will store memory in hosted Qdrant and keep model calls local through Ollama.
+
+`qdrant_api_key` is optional only for unauthenticated self-hosted Qdrant. Qdrant Cloud usually requires it.
+
+## Check it
+
+```bash
+bikky status
+```
+
+After changing Qdrant settings, restart long-running processes:
+
+```bash
+bikky stop && bikky start
+```
+
+Then restart your editor so its MCP process reloads.

package/docs/config/local.md

@@ -0,0 +1,34 @@
+# Local and free config
+
+Use this path if you want a private, free setup: Qdrant runs on your machine, and Ollama handles local models.
+
+This setup is best for private/free testing rather than long-term team use. Extraction, embedding, and curation performance depends on the local models and hardware you run.
+
+## What you need
+
+- Qdrant running locally, usually with Docker.
+- Ollama installed locally.
+- The default embedding model pulled with `ollama pull qwen3-embedding:0.6b`.
+
+## Config
+
+Save this as `~/.bikky/config.json`:
+
+```json
+{
+  "qdrant_url": "http://localhost:6333",
+  "qdrant_api_key": ""
+}
+```
+
+That's the whole config. bikky uses local Ollama defaults for embeddings and background curation.
+
+`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant.
+
+## Check it
+
+```bash
+bikky status
+```
+
+If you started from a fresh install, run `bikky setup` after writing the config, then restart your editor so its MCP process reloads.

package/docs/configuration.md

@@ -0,0 +1,374 @@
+# Configuration
+
+bikky is designed to keep setup small. The example below keeps Qdrant local and uses hosted models; the focused guides list the other common setup shapes.
+
+```bash
+mkdir -p ~/.bikky
+cat > ~/.bikky/config.json <<'JSON'
+{
+  "qdrant_url": "http://localhost:6333",
+  "qdrant_api_key": "",
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small",
+    "dimensions": 1536,
+    "api_key": "sk-..."
+  },
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4.1-mini",
+    "api_key": "sk-..."
+  }
+}
+JSON
+bikky status
+```
+
+Config lives at `~/.bikky/config.json`, or at `BIKKY_HOME/config.json` when `BIKKY_HOME` is set. Environment variables override the config file.
+
+## Common setups
+
+If you know which path you want, start with the focused guide:
+
+| Setup                         | Best for                                                     | Guide                                                                    |
+| ----------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| Fully hosted                  | Best performance and teams; managed vector storage and models | [Fully hosted config](config/fully-hosted.md)                            |
+| Local Qdrant + hosted models  | Local vector storage with hosted extraction and embedding    | [Hosted models config](config/hosted-models.md)                          |
+| Local and free                | Local evaluation; quality depends on local models            | [Local config guide](config/local.md)                                    |
+| Hosted Qdrant + local models  | Shared vector storage while keeping model calls local        | [Hosted Qdrant + local models](config/hosted-qdrant-local-models.md)     |
+
+### Fully hosted
+
+Best for performance and teams. Qdrant Cloud stores vectors, and hosted embeddings + LLM calls handle extraction, curation, and recall.
+
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-key",
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small",
+    "dimensions": 1536,
+    "api_key": "sk-..."
+  },
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4.1-mini",
+    "api_key": "sk-..."
+  }
+}
+```
+
+`qdrant_api_key` is optional only for unauthenticated self-hosted Qdrant. Qdrant Cloud usually requires it.
+
+### Local Qdrant + hosted models
+
+Best for local vector storage with hosted extraction and embedding quality.
+
+```json
+{
+  "qdrant_url": "http://localhost:6333",
+  "qdrant_api_key": "",
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small",
+    "dimensions": 1536,
+    "api_key": "sk-..."
+  },
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4.1-mini",
+    "api_key": "sk-..."
+  }
+}
+```
+
+`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant. Prefer env vars for hosted model auth? Omit `api_key` above and set `OPENAI_API_KEY` instead.
+
+### Local and free
+
+Use this for local, free, account-free evaluation. Qdrant runs locally and Ollama provides the default embedding + LLM models.
+
+This setup is usually not the best long-term choice for teams. Extraction, embedding, and curation performance depends on the local models and hardware you run.
+
+```json
+{
+  "qdrant_url": "http://localhost:6333",
+  "qdrant_api_key": ""
+}
+```
+
+`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant.
+
+### Hosted Qdrant, local models
+
+Use this when you want the memory database shared across machines, but still want embeddings and LLM calls to stay local.
+
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-key"
+}
+```
+
+`qdrant_api_key` is optional only for unauthenticated self-hosted Qdrant. Qdrant Cloud usually requires it.
+
+After changing Qdrant or provider settings, restart long-running processes:
+
+```bash
+bikky stop && bikky start
+```
+
+Then restart your editor so its MCP server process reloads the config.
+
+## Environment variables
+
+Use env vars when you do not want to write credentials to the config file:
+
+```bash
+export QDRANT_URL="http://localhost:6333"
+export QDRANT_API_KEY="..."  # only needed for Qdrant Cloud or authenticated self-hosted Qdrant
+```
+
+Useful basics:
+
+| Env var          | Config field     | Notes                                                                       |
+| ---------------- | ---------------- | --------------------------------------------------------------------------- |
+| `QDRANT_URL`     | `qdrant_url`     | Required unless set in config                                               |
+| `QDRANT_API_KEY` | `qdrant_api_key` | Optional for local/unauthenticated Qdrant; usually needed for Qdrant Cloud  |
+| `BIKKY_HOME`     | —                | Moves the config/log/state directory from `~/.bikky`                        |
+
+## Provider options
+
+Use these exact values in `embedding.provider` and `llm.provider`. Both fields accept the same provider values, and you can choose them independently.
+
+| Provider value | Works for embeddings | Works for LLM | Best for                             | Auth                              |
+| -------------- | -------------------- | ------------- | ------------------------------------ | --------------------------------- |
+| `ollama`       | Yes                  | Yes           | Local and free defaults              | None                              |
+| `openai`       | Yes                  | Yes           | Simple hosted models                 | `OPENAI_API_KEY` or `api_key`     |
+| `bedrock`      | Yes                  | Yes           | AWS-managed models                   | AWS credentials or IAM role       |
+| `portkey`      | Yes                  | Yes           | Gateway/routing over other providers | Portkey API key                   |
+
+## Advanced configuration
+
+These sections are optional references for custom providers, tuning, scoping, and daemon internals.
+
+### Full setting reference
+
+#### Qdrant
+
+| Setting          | Env var            | Default | Notes                          |
+| ---------------- | ------------------ | ------- | ------------------------------ |
+| `qdrant_url`     | `QDRANT_URL`       | none    | Qdrant REST URL                |
+| `qdrant_api_key` | `QDRANT_API_KEY`   | none    | API key for authenticated Qdrant |
+| `collection`     | `BIKKY_COLLECTION` | `bikky` | Collection name                |
+
+`qdrant_api_key` is optional for local or unauthenticated self-hosted Qdrant. Qdrant Cloud usually requires it.
+
+#### Embeddings
+
+| Setting                | Env var                | Default                  | Notes                                           |
+| ---------------------- | ---------------------- | ------------------------ | ----------------------------------------------- |
+| `embedding.provider`   | `EMBEDDING_PROVIDER`   | `ollama`                 | One of `ollama`, `openai`, `bedrock`, `portkey` |
+| `embedding.model`      | `EMBEDDING_MODEL`      | `qwen3-embedding:0.6b`   | Embedding model name                            |
+| `embedding.dimensions` | `EMBEDDING_DIMENSIONS` | `1024`                   | Must match the selected model output            |
+| `embedding.base_url`   | `EMBEDDING_BASE_URL`   | `http://localhost:11434` | Used by local or OpenAI-compatible providers    |
+| `embedding.api_key`    | `OPENAI_API_KEY`       | —                        | Provider API key; can also be set in config     |
+
+Common model dimensions:
+
+| Provider  | Model                            | Dimensions |
+| --------- | -------------------------------- | ---------- |
+| `ollama`  | `qwen3-embedding:0.6b`           | `1024`     |
+| `ollama`  | `nomic-embed-text`               | `768`      |
+| `openai`  | `text-embedding-3-small`         | `1536`     |
+| `openai`  | `text-embedding-3-large`         | `3072`     |
+| `bedrock` | `amazon.titan-embed-text-v2:0`   | `1024`     |
+
+If you change the embedding model, make sure `embedding.dimensions` matches the model output.
+
+#### LLM
+
+The LLM is used by background maintenance features. Ollama is the default.
+
+| Setting            | Env var                              | Default                  | Notes                                        |
+| ------------------ | ------------------------------------ | ------------------------ | -------------------------------------------- |
+| `llm.provider`     | `LLM_PROVIDER`                       | `ollama`                 | One of `ollama`, `openai`, `bedrock`, `portkey` |
+| `llm.model`        | `LLM_MODEL`                          | `qwen2.5:7b`             | LLM model name                               |
+| `llm.base_url`     | `LLM_BASE_URL`                       | `http://localhost:11434` | Used by local or OpenAI-compatible providers |
+| `llm.api_key`      | `OPENAI_API_KEY`                     | —                        | Provider API key; can also be set in config  |
+| `llm.extra.region` | `AWS_BEDROCK_REGION` / `AWS_REGION`  | `us-east-1`              | AWS Bedrock region                           |
+
+#### Timeouts and retries
+
+| Setting                         | Env var                                  | Default |
+| ------------------------------- | ---------------------------------------- | ------- |
+| `embedding.timeout_ms`          | `BIKKY_EMBEDDING_TIMEOUT_MS`             | `30000` |
+| `embedding.retries`             | `BIKKY_EMBEDDING_RETRIES`                | `2`     |
+| `embedding.retry_base_delay_ms` | `BIKKY_EMBEDDING_RETRY_BASE_DELAY_MS`    | `250`   |
+| `llm.timeout_ms`                | `BIKKY_LLM_TIMEOUT_MS`                   | `30000` |
+| `llm.retries`                   | `BIKKY_LLM_RETRIES`                      | `2`     |
+| `llm.retry_base_delay_ms`       | `BIKKY_LLM_RETRY_BASE_DELAY_MS`          | `250`   |
+
+Retries use jittered exponential backoff for transient errors, rate limits, and timeouts. Authentication and bad-request errors fail fast.
+
+### Portkey and Bedrock examples
+
+#### Portkey gateway
+
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-key",
+  "embedding": {
+    "provider": "portkey",
+    "model": "@openai/text-embedding-3-small",
+    "dimensions": 1536,
+    "api_key": "pk-..."
+  },
+  "llm": {
+    "provider": "portkey",
+    "model": "@openai/gpt-4o-mini",
+    "api_key": "pk-...",
+    "extra": { "virtual_key": "openai-prod" }
+  }
+}
+```
+
+#### AWS Bedrock
+
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-key",
+  "embedding": {
+    "provider": "bedrock",
+    "model": "amazon.titan-embed-text-v2:0",
+    "dimensions": 1024
+  },
+  "llm": {
+    "provider": "bedrock",
+    "model": "us.anthropic.claude-sonnet-4-20250514",
+    "extra": { "region": "us-east-1" }
+  }
+}
+```
+
+Bedrock reads `embedding.extra.region` and `llm.extra.region`. `AWS_BEDROCK_REGION` populates both, falling back to `AWS_REGION`; `aws_profile` or `AWS_PROFILE` selects the shared AWS profile when you are not using direct env credentials.
+
+### Multi-destination routing
+
+Most users only need one Qdrant destination. Use `destinations[]` when you want one bikky install and one editor MCP connection to read or write separate memory stores for different teams, clients, or environments.
+
+Each destination has its own Qdrant credentials and collection. A destination can also include a `match` block with JavaScript `RegExp` strings for `cwd`, `entity`, `content`, or `metadata`. Destinations are evaluated in array order; the first destination with any matching pattern wins. If no pattern matches, bikky uses the destination marked `default: true`, or the first destination.
+
+```jsonc
+{
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small",
+    "dimensions": 1536
+  },
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4.1-mini"
+  },
+  "destinations": [
+    {
+      "name": "client-a",
+      "qdrant_url": "https://client-a.cloud.qdrant.io:6333",
+      "qdrant_api_key": "...",
+      "collection": "bikky-client-a",
+      "match": {
+        "cwd": ["^/Users/me/code/client-a"],
+        "entity": ["^client-a-"],
+        "content": ["client-a", "CLIENTA-\\d+"],
+        "metadata": { "project": ["^client-a$"] }
+      }
+    },
+    {
+      "name": "research-cloud",
+      "qdrant_url": "https://research.cloud.qdrant.io:6333",
+      "qdrant_api_key": "...",
+      "collection": "bikky-research",
+      "match": {
+        "content": ["[Rr]esearch[- ][Ll]ab"]
+      }
+    },
+    {
+      "name": "platform",
+      "qdrant_url": "http://localhost:6333",
+      "qdrant_api_key": "",
+      "collection": "bikky-platform",
+      "default": true
+    }
+  ]
+}
+```
+
+Matching details:
+
+- `match.cwd`, `match.entity`, and `match.content` are lists of JavaScript `RegExp` strings.
+- `match.metadata` maps metadata keys to lists of JavaScript `RegExp` strings matched against that key's value.
+- Matching uses OR logic across fields and within each list; any matching pattern selects the destination.
+- Put the most specific destinations first because first match wins.
+- JavaScript regex flags are not supported in config strings. Use character classes like `[Bb]ikky` for case-insensitive matching.
+- Tool calls can override routing with an explicit destination name, for example `memory_store({ ..., destination: "client-a" })`.
+- All destinations share one embedding provider, so every destination collection must use the same vector dimensions.
+
+Migrating from `workspace_id` pre-v0.4:
+
+- Existing top-level `qdrant_url`, `qdrant_api_key`, and `collection` configs still work as a single synthesized destination.
+- The `workspace_id` argument on memory tools is a no-op for compatibility.
+- Replace `default_workspace` scoping with named destinations when you need isolation.
+
+### Daemon, watchers, and logs
+
+You normally do not need to tune these. `bikky setup` starts the daemon and registers supported MCP clients.
+
+#### Daemon settings
+
+| Setting                              | Default | Description                                      |
+| ------------------------------------ | ------- | ------------------------------------------------ |
+| `daemon.tick_interval_sec`           | `5`     | Seconds between daemon loop ticks                |
+| `daemon.extract_every_sec`           | `300`   | Seconds between extraction runs                  |
+| `daemon.extract_min_events`          | `10`    | Minimum events before extraction                 |
+| `daemon.consolidation_enabled`       | `true`  | Consolidate summaries into durable patterns      |
+| `daemon.relation_inference_enabled`  | `true`  | Infer entity relationships                       |
+| `daemon.entity_typing_enabled`       | `true`  | Classify entities for UI/graph filtering         |
+| `daemon.staleness_threshold_days`    | `30`    | Days before a fact is flagged as stale           |
+
+#### Watcher settings
+
+| Setting                    | Default                    | Description                       |
+| -------------------------- | -------------------------- | --------------------------------- |
+| `watchers.copilot.enabled` | `true`                     | Watch GitHub Copilot session logs |
+| `watchers.copilot.path`    | `~/.copilot/session-state` | Path to Copilot session directory |
+| `watchers.claude.enabled`  | `true`                     | Watch Claude Code project logs    |
+| `watchers.claude.path`     | `~/.claude/projects`       | Path to Claude Code projects      |
+
+#### Logs
+
+bikky writes logs to `~/.bikky/logs/`:
+
+| File         | Written by        |
+| ------------ | ----------------- |
+| `mcp.log`    | MCP server        |
+| `daemon.log` | Background daemon |
+| `llm.jsonl`  | LLM telemetry     |
+
+Pretty-print logs with:
+
+```bash
+tail -f ~/.bikky/logs/daemon.log | npx pino-pretty
+```
+
+## Troubleshooting
+
+Run:
+
+```bash
+bikky status
+```
+
+`bikky status` is read-only. It checks the config, Qdrant connection, collection readiness, embedding connectivity, daemon state, and local UI health. If something is missing or misconfigured, it exits non-zero and prints the next fix to make.