bikky 0.3.13 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to bikky are documented here.
+
+This project uses npm package versions for release tracking:
+
+- `bikky` — core CLI, MCP server, and daemon.
+- `bikky-ui` — local web dashboard.
+
+## Unreleased
+
+- Public OSS readiness cleanup: package metadata, support docs, public maintainer ownership, package tarball hygiene, and privacy/transcript-capture documentation.
+- Added package verification CI and a privacy-first quickstart for local storage/local model setups.
+
+## 0.4.0
+
+- Added multi-destination Qdrant routing and configurable read/search scopes.
+- Added Claude Code user-scoped MCP setup support.
+- Added Claude Code transcript ingestion for daemon memory extraction.
+- Refreshed README screenshots, setup guidance, and configuration docs.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,80 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+the bikky community a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behaviour that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologising to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behaviour:
+
+- The use of sexualised language or imagery, and sexual attention or advances
+  of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards
+of acceptable behaviour and will take appropriate and fair corrective action in
+response to any behaviour that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces (issues, PRs,
+Discussions, Discord/Slack if any), and also applies when an individual is
+officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
+reported to the project maintainers via the GitHub Security Advisories private
+reporting flow at:
+https://github.com/bikky-dev/bikky/security/advisories/new
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All maintainers are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Maintainers will follow these Community Impact Guidelines in determining the
+consequences for any action they deem in violation of this Code of Conduct:
+
+1. **Correction** — Private, written warning. A public apology may be requested.
+2. **Warning** — A warning with consequences for continued behaviour.
+3. **Temporary ban** — A temporary ban from any sort of interaction or public
+   communication with the community.
+4. **Permanent ban** — Permanent ban from any sort of public interaction within
+   the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/), version 2.1,
+available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

package/CONTRIBUTING.md

@@ -0,0 +1,206 @@
+# Contributing to bikky
+
+Thanks for your interest in bikky! We welcome PRs of all sizes — from typo fixes to new daemon features. This document covers the practical bits: how the repo is laid out, how to run the tests, and what we look for in a contribution.
+
+## Repository layout
+
+bikky is a small monorepo:
+
+```
+.
+├── src/                  # Core CLI + MCP server + daemon (published as `bikky`)
+│   ├── cli/              # `bikky <subcommand>` entrypoints
+│   ├── daemon/           # Background workers: extraction, consolidation, staleness, …
+│   ├── mcp/              # MCP server (the surface AI agents call into)
+│   ├── prompts/          # Versioned LLM prompt registry
+│   └── llm/              # Provider adapters (OpenAI, Bedrock, Ollama, Portkey)
+│       ├── embedding/    #   embedding registry + providers
+│       └── inference/    #   chat-completion registry + providers
+└── packages/
+    └── ui/               # Local web UI (`bikky-ui`) — Hono server + React frontend
+        ├── src/lib/      #   - config, qdrant client, embeddings
+        ├── src/routes/   #   - REST API routes
+        └── app/          #   - React/Vite frontend
+```
+
+## Setup
+
+```bash
+git clone https://github.com/bikky-dev/bikky.git
+cd bikky
+npm install
+cd packages/ui && npm install && cd ../..
+```
+
+## Running the tests
+
+We use the Node.js built-in test runner ([`node:test`](https://nodejs.org/api/test.html)) — no Jest, no Vitest, no extra dependencies.
+
+```bash
+# Core (CLI, daemon, MCP server) — 300+ tests
+npm test
+
+# UI server + libraries — 50+ tests
+cd packages/ui && npm test
+```
+
+Both packages compile TypeScript into `dist/` first and then run the compiled `*.test.js` files. The UI test suite uses `--test-isolation=process --test-concurrency=1` because several tests share `~/.bikky/config.json` on the developer's machine; running them in isolation avoids flakiness.
+
+> **Note on `~/.bikky/config.json`** — UI tests back up your real config in `before()` and restore it in `after()`. If a test crashes mid-run the file *should* survive, but if you ever see odd behaviour after a failed test run, just delete the file and re-run `bikky setup`.
+
+### What we test
+
+We aim for **focused, fast unit tests** that lock in behaviour without being a maintenance tax:
+
+- Pure functions (filter builders, hashers, parsers) — exhaustive cases.
+- Stateful modules (config loaders, lifecycle/PID, daemons) — happy path + a couple of failure modes.
+- Network clients (Qdrant, embeddings, LLM providers) — mock `globalThis.fetch` and assert on the request, never call a real backend.
+- HTTP routes (Hono) — exercise via `app.fetch(new Request(...))` against the real router with mocked underlying calls.
+
+We deliberately **do not** test:
+
+- LLM prompt quality or extraction accuracy. Prompt-level evals live outside the default unit-test suite so day-to-day contributor tests stay fast and deterministic.
+- Implementation details (private function internals, exact log strings) — these change often and tests that pin them slow contributors down.
+- The React frontend — the testable surface there is small; we rely on type-checking and manual smoke tests.
+
+### Adding a new test
+
+Tests live alongside the source as `*.test.ts`:
+
+```
+src/foo.ts       # source
+src/foo.test.ts  # tests
+```
+
+Use the [`node:test`](https://nodejs.org/api/test.html) `describe/it/before/after` API and `node:assert/strict`. For mocking, prefer **dependency injection** (e.g. the `StaleDeps` pattern in `src/daemon/staleness.ts`) over module mocking — it keeps tests deterministic and the production code easier to reason about.
+
+Good references for new tests:
+
+| Pattern                          | Reference                              |
+|----------------------------------|----------------------------------------|
+| Filesystem with backup/restore   | `src/lifecycle.test.ts`                |
+| Temp dir with `mkdtemp`          | `src/logger.test.ts`                   |
+| Env-based path override          | `src/llm/telemetry.test.ts`            |
+| Dependency injection for daemons | `src/daemon/staleness.test.ts`         |
+| Mocking `globalThis.fetch`       | `src/mcp/api.test.ts`, `packages/ui/src/lib/qdrant.test.ts` |
+| Hono route via `app.fetch`       | `packages/ui/src/routes/memory.test.ts` |
+
+### Integration tests (opt-in, real Qdrant)
+
+The default `npm test` mocks every external call. We also ship one **opt-in** end-to-end smoke test that talks to a real Qdrant instance (Cloud, local Docker, or self-hosted) and a real embedding provider — it's the only thing that catches filter-shape rejections, payload-index mismatches, vector-dimension drift, and whether the dedup similarity thresholds (`THRESHOLD_DUPLICATE`, `THRESHOLD_RELATED`) actually correspond to near-duplicates against your embedding model.
+
+```bash
+# Uses your existing ~/.bikky/config.json + QDRANT_URL (and QDRANT_API_KEY if your Qdrant requires it).
+BIKKY_INTEGRATION=1 npm run test:integration
+```
+
+What it does:
+
+1. Creates a throwaway collection named `bikky-it-<short-uuid>` with the real payload indexes.
+2. Exercises `memory_store` (insert, exact-dup, near-duplicate paraphrase), `memory_recall`, `memory_entity`, and `memory_forget` against live Qdrant + your real embeddings.
+3. Drops the collection in `after()` regardless of pass/fail.
+
+Cost is negligible — a handful of small embedding calls per run (≈ $0.0001 on OpenAI's `text-embedding-3-small`, free on Ollama). Files end in `.itest.ts` so the default `*.test.js` glob never picks them up.
+
+If the near-duplicate paraphrase doesn't reinforce on your embedding model, the test logs the actual similarity score so you can re-tune `THRESHOLD_DUPLICATE` rather than failing outright.
+
+## Adding an embedding or LLM provider
+
+The most common contribution is **adding a new embedding or LLM provider**. Each provider is a single file. The registry dispatches by `provider.name`, so no central edits are required beyond adding one import line to the barrel.
+
+### Embedding provider
+
+1. Create `src/llm/embedding/providers/<name>.ts`:
+
+   ```ts
+   import {
+     registerEmbeddingProvider,
+     type EmbeddingProvider,
+     type ResolvedEmbeddingConfig,
+   } from "../registry.js";
+
+   export const myProvider: EmbeddingProvider = {
+     name: "myprovider",
+     label: "My Provider",
+     browserCompatible: true, // false if it needs a server-only SDK
+     defaults: {
+       model: "default-model",
+       dimensions: 1024,
+       baseUrl: "https://api.example.com", // omit if SDK-only
+     },
+     async embed(text, cfg) {
+       // cfg.{model,baseUrl,apiKey,extra} are pre-resolved
+       const resp = await fetch(`${cfg.baseUrl}/v1/embeddings`, { /* … */ });
+       // throw on programmer error; return number[] on success
+       return [/* embedding vector */];
+     },
+   };
+
+   registerEmbeddingProvider(myProvider);
+   ```
+
+2. Add a side-effect import in `src/llm/embedding/providers/index.ts`:
+
+   ```ts
+   import "./myprovider.js";
+   ```
+
+3. Add a small unit test next to your provider (`<name>.test.ts`). Mock
+   `globalThis.fetch` (see `ollama.test.ts` for the pattern). Cover at minimum:
+   - success path (verifies URL, headers, body shape)
+   - non-OK response handling
+   - any provider-specific behaviour (auth, extra headers, fallback fields)
+
+4. If your provider is browser-friendly, mirror it under
+   `packages/ui/src/lib/embedding/providers/<name>.ts` so the UI can use it.
+
+5. Configure it in `~/.bikky/config.json`:
+
+   ```json
+   {
+     "embedding": {
+       "provider": "myprovider",
+       "model": "my-model",
+       "api_key": "…",
+       "extra": { "any-key": "any-value" }
+     }
+   }
+   ```
+
+   Or via env: `BIKKY_EMBEDDING_EXTRA_<KEY>=value` flows into `extra`.
+
+### Inference (LLM) provider
+
+Same pattern, under `src/llm/inference/providers/`. The interface is
+`InferenceProvider` (see `src/llm/inference/types.ts`), the key method is
+`chat(opts, cfg, log)`, and providers should **return `null`** on recoverable
+errors (HTTP error, missing key, network failure) so the orchestrator can fall
+back to `cfg.fallback` if configured. Throw only for programmer errors.
+
+Configure a fallback chain via `llm.fallback_provider` in config (or
+`LLM_FALLBACK_PROVIDER` env).
+
+## Submitting changes
+
+1. **Open an issue first** for non-trivial changes so we can align on the approach.
+2. **Branch** from `main` (`git checkout -b your-feature-name`).
+3. **Run the tests** in both packages before pushing.
+4. **Open a PR** referencing the issue (`Closes #123`). CI will re-run tests on push.
+5. We aim to review within a few business days — ping the issue if it goes quiet.
+
+## Style
+
+- TypeScript strict mode is on; no `any` unless interfacing with external SDK types (use a focused local interface to constrain the surface area).
+- We prefer small, pure functions and clear module boundaries to elaborate abstractions.
+- Tests live next to the source they cover (`foo.ts` + `foo.test.ts`).
+- Providers must not call `process.exit`, log to stdout, or modify global state beyond their own module-scope cache.
+- Heavy SDKs (e.g. `@aws-sdk/*`) **must be `await import(...)`-loaded inside the provider's `embed`/`chat`** so users on lighter providers don't pay the bundle cost.
+- Comments explain *why*, not *what* — the code shows the *what*.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's [AGPL-3.0-or-later](LICENSE) license.
+
+## Code of conduct
+
+Be kind. We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

package/README.md

@@ -1,25 +1,25 @@
 <h1 align="center">bikky</h1>
 
-<p align="center"><b>Persistent memory for AI coding agents — for teams, and for solo power users.</b></p>
+<p align="center"><b>Persistent memory for AI coding agents — built for teams and multi-agent engineering workflows.</b></p>
 
-bikky gives AI coding agents (GitHub Copilot, Claude Code, Cursor, and other MCP clients) long-term memory that persists across sessions, across tools, and across your whole team. Whether you're a team that wants every engineer's agent to start from the same knowledge base, or a solo power dev running a dozen agentic sessions a day, bikky captures what's learned *during* sessions so future sessions start smarter.
+bikky gives AI coding agents (GitHub Copilot, Claude Code, Cursor, and other MCP clients) long-term memory that persists across sessions, across tools, and across your whole team. When multiple engineers, agents, or repos need to build on the same knowledge base, bikky captures what's learned *during* sessions so future sessions start smarter.
 
 ### Who it's for
 
 - 👥 **Teams & software factories** — What one engineer's agent learns today, every agent on the team can recall tomorrow. Shared memory turns institutional knowledge into something queryable instead of tribal — onboarding accelerates, conventions stop drifting, and the same lesson never gets re-learned twice.
-- 🧑‍💻 **Solo AI power devs** — You run multiple Cursor / Claude Code / Copilot sessions every day and you're tired of re-explaining the codebase, the conventions, and last week's decisions to each new agent. bikky remembers across every session and every tool.
+- 🤖 **Multi-agent engineering workflows** — Multiple Cursor / Claude Code / Copilot sessions can share codebase context, conventions, and recent decisions instead of re-learning them from scratch.
 
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/bikky@latest/docs/diagrams/team-memory.svg" alt="Memory — facts flow from individual sessions into a self-curating knowledge store, shared across your team (or kept just for you)" width="720" />
+  <img src="https://cdn.jsdelivr.net/npm/bikky@latest/docs/diagrams/team-memory.svg" alt="Memory — facts flow from individual sessions into a self-curating knowledge store shared across your team" width="720" />
 </p>
 
-<p align="center"><i>Knowledge flows from every session into a store that curates itself over time — deduplicating, distilling, and decaying stale facts — so every future session starts smarter. Share it across a team, or keep it solo.</i></p>
+<p align="center"><i>Knowledge flows from every session into a store that curates itself over time — deduplicating, distilling, and decaying stale facts — so every future session starts smarter across the team.</i></p>
 
 ---
 
 ### The problem
 
-The most valuable things you and your agents learn — why a config value exists, which deploy step matters, what broke last quarter, the convention you settled on yesterday — happen *during* sessions. And then they vanish when the session closes. Whether you're a team — where knowledge lives in heads, chat threads, and closed PRs, and every new engineer's agent has to learn it from scratch — or a solo power dev juggling dozens of agentic sessions a day across multiple tools that don't remember each other, it's the same wall. Hand-written docs drift the moment they're published.
+The most valuable things you and your agents learn — why a config value exists, which deploy step matters, what broke last quarter, the convention you settled on yesterday — happen *during* sessions. And then they vanish when the session closes. Across teams, repos, and tools, knowledge still lives in heads, chat threads, and closed PRs, and every new agent session has to learn it from scratch. Hand-written docs drift the moment they're published.
 
 ### How bikky solves it
 
@@ -30,6 +30,7 @@ bikky gives your agent memory tools and runs a small background service after `b
 - **Recall** — Every new session, yours or a teammate's, recalls from the same store via semantic search.
 - **Curate** — bikky merges duplicates, fades stale facts, resolves contradictions, distills recurring patterns, and builds an entity graph over time.
 - **Compound** — Session 50 is dramatically better than session 1 because memory accumulates.
+- **Route** — Optionally keep team, client, or environment-specific memory in separate Qdrant destinations from one install. See [separate memory stores](#optional-separate-memory-stores).
 
 Subtypes keep recall precise without making setup harder:
 
@@ -42,7 +43,7 @@ Subtypes keep recall precise without making setup harder:
 
 ## Quick start
 
-This quick start uses **local Qdrant + hosted models**: Qdrant runs on your machine, while hosted embeddings and LLM calls provide strong extraction and recall quality without running local LLMs.
+This is the fastest path to a working memory store: Qdrant runs locally, while hosted embeddings and LLM calls provide strong extraction and recall quality without running local models.
 
 ```bash
 # 1. Pull and run Qdrant (vector store)
@@ -76,15 +77,17 @@ JSON
 bikky setup            # writes MCP config for Copilot + Claude Code, then starts the daemon
 ```
 
+`npm install -g bikky` runs a best-effort postinstall setup hook for convenience. It never fails the install, and you should still run `bikky setup` after writing your config to make setup explicit and repeatable.
+
 Restart your editor. The memory tools appear automatically in supported MCP clients.
 
 ```bash
 bikky status           # confirms Qdrant, embeddings, daemon, and UI health
 ```
 
-That's it. You can keep Qdrant local forever, or move the vector store to Qdrant Cloud later.
+That's it. You can keep Qdrant local forever, or move the vector store to Qdrant Cloud later for a shared team setup.
 
-For 100% local and account-free setup, use the [local and free config](docs/config/local.md). It is best for private testing rather than long-term team use, and extraction, embedding, and curation performance depends on the local models and hardware you run.
+For other deployment shapes — fully hosted, 100% local, or hosted Qdrant with local models — see [Setup options](#setup-options).
 
 ---
 
@@ -104,24 +107,73 @@ bikky supports four common setup shapes. Pick based on where you want Qdrant to
 
 Both `embedding.provider` and `llm.provider` accept the same values: `ollama`, `openai`, `bedrock`, or `portkey`.
 
+> ⚠️ **Qdrant Cloud free tier does not include automatic backups.** Deleted collections cannot be recovered. If your memory data is valuable, use a paid Qdrant Cloud plan (which includes daily backups), run Qdrant locally with your own backup strategy, or periodically export snapshots via the [Qdrant snapshots API](https://qdrant.tech/documentation/concepts/snapshots/).
+
 ### Choose a setup
 
 | Setup                            | Best for                                                       | Config                                                                    |
 | -------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| **Fully hosted**                 | Best performance and teams; managed vector storage and models  | [Fully hosted config](docs/config/fully-hosted.md)                        |
-| **Local Qdrant + hosted models** | Local vector storage with hosted extraction and embedding      | [Hosted models config](docs/config/hosted-models.md)                      |
-| **Local and free**               | Private/free testing; quality depends on local models          | [Local config guide](docs/config/local.md)                                |
-| **Hosted Qdrant + local Ollama** | Shared vector storage while keeping model calls local          | [Hosted Qdrant + local models](docs/config/hosted-qdrant-local-models.md) |
+| **Fully hosted**                 | Best performance and teams; managed vector storage and models  | [Fully hosted config][fully-hosted-config]                              |
+| **Local Qdrant + hosted models** | Local vector storage with hosted extraction and embedding      | [Hosted models config][hosted-models-config]                            |
+| **Local and free**               | Local evaluation; quality depends on local models              | [Local config guide][local-config]                                      |
+| **Hosted Qdrant + local Ollama** | Shared vector storage while keeping model calls local          | [Hosted Qdrant + local models][hosted-qdrant-local-models-config]       |
+
+### Configuration basics
+
+Pick the setup guide above for the copy-paste config. All setup shapes use the same three building blocks:
 
-### Configure
+- **Qdrant** — where vectors and memory payloads are stored.
+- **Embeddings** — how facts become searchable vectors.
+- **LLM** — how session transcripts are extracted, curated, and distilled.
 
-Pick the setup guide above for the copy-paste config. Config lives at `~/.bikky/config.json`, and you can also set `QDRANT_URL` and `QDRANT_API_KEY` as environment variables.
+Config lives at `~/.bikky/config.json`, or at `BIKKY_HOME/config.json` when `BIKKY_HOME` is set. You can keep credentials out of the file with environment variables such as `QDRANT_URL`, `QDRANT_API_KEY`, and provider API keys.
 
 For hosted models, custom providers, multiple profiles, or advanced tuning, use the full configuration guide.
 
-> 📖 **Full configuration guide:** [docs/configuration.md](docs/configuration.md)
+> 📖 **Full configuration guide:** [docs/configuration.md][configuration-guide]
 >
-> 🛠 Want to add a new embedding or LLM provider (Vertex, OpenRouter, etc.)? See **[CONTRIBUTING.md](CONTRIBUTING.md)** — it's a single-file change.
+> 🔒 **Privacy-first setup:** [local storage, local models, and transcript-capture controls][privacy-quickstart]
+>
+> 🛠 Want to add a new embedding or LLM provider (Vertex, OpenRouter, etc.)? See **[CONTRIBUTING.md][contributing]** — it's a single-file change.
+
+#### Optional: separate memory stores
+
+Most installs use one Qdrant destination. If you need clean separation later, replace the single `qdrant_url` / `collection` fields with named `destinations[]`:
+
+```jsonc
+{
+  "destinations": [
+    {
+      "name": "platform",
+      "description": "Shared platform engineering memory.",
+      "qdrant_url": "https://platform.cloud.qdrant.io:6333",
+      "qdrant_api_key": "...",
+      "collection": "bikky-platform",
+      "default": true
+    },
+    {
+      "name": "client-a",
+      "description": "Client A project memory.",
+      "qdrant_url": "https://client-a.cloud.qdrant.io:6333",
+      "qdrant_api_key": "...",
+      "collection": "bikky-client-a"
+    }
+  ],
+  "default_search_scope": "routed"
+}
+```
+
+That is enough for explicit selection in the UI and tools. Add routing rules only when you want automatic placement by cwd, entity, content, or metadata. Search tools can also use `search_scope: "all"` or a named/listed scope when context may span stores. Existing single-Qdrant configs continue to work.
+
+> 📖 **Details:** [multi-destination configuration](docs/configuration.md#multi-destination-routing)
+
+[fully-hosted-config]: https://cdn.jsdelivr.net/npm/bikky@latest/docs/config/fully-hosted.md
+[hosted-models-config]: https://cdn.jsdelivr.net/npm/bikky@latest/docs/config/hosted-models.md
+[local-config]: https://cdn.jsdelivr.net/npm/bikky@latest/docs/config/local.md
+[hosted-qdrant-local-models-config]: https://cdn.jsdelivr.net/npm/bikky@latest/docs/config/hosted-qdrant-local-models.md
+[configuration-guide]: https://cdn.jsdelivr.net/npm/bikky@latest/docs/configuration.md
+[privacy-quickstart]: https://cdn.jsdelivr.net/npm/bikky@latest/docs/privacy-first.md
+[contributing]: https://cdn.jsdelivr.net/npm/bikky@latest/CONTRIBUTING.md
 
 ---
 
@@ -137,17 +189,17 @@ bikky-ui              # opens http://localhost:1422
 ```
 
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/bikky@latest/docs/screenshots/dashboard.png" alt="Dashboard — overview stats, category breakdown, recent facts" width="720" />
+  <img src="docs/screenshots/dashboard.png" alt="Dashboard — overview stats, category breakdown, recent facts" width="720" />
 </p>
 <p align="center"><i>Dashboard — memory stats, category breakdown, and recent facts at a glance</i></p>
 
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/bikky@latest/docs/screenshots/memory.png" alt="Memory browser — search, filter, and browse all stored facts" width="720" />
+  <img src="docs/screenshots/memory.png" alt="Memory browser — search, filter, and browse all stored facts" width="720" />
 </p>
 <p align="center"><i>Memory browser — search, filter by category/kind/source, and browse all stored facts</i></p>
 
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/bikky@latest/docs/screenshots/graph.png" alt="Entity graph — interactive visualization of entity relationships" width="720" />
+  <img src="docs/screenshots/graph.png" alt="Entity graph — interactive visualization of entity relationships" width="720" />
 </p>
 <p align="center"><i>Entity graph — interactive visualization of how concepts, people, and services relate</i></p>
 
@@ -168,6 +220,28 @@ bikky render    # render a prompt to JSON (for eval harnesses & debugging)
 
 `bikky status` is the first thing to run when setup feels wrong. It checks the config, Qdrant, embeddings, background daemon, and local UI health, then tells you what needs attention. Use `bikky status --json` for automation.
 
+## Privacy and transcript capture
+
+bikky stores memory in the Qdrant destination you configure. The daemon runs locally and reads supported coding-agent transcript locations so it can extract durable facts for future sessions:
+
+- GitHub Copilot session state: `~/.copilot/session-state`
+- Claude Code project transcripts: `~/.claude/projects`
+
+Only the configured daemon process reads these files. Extracted facts are redacted before storage, but they are still sent to your configured LLM provider for extraction unless you use a local provider such as Ollama. To disable transcript capture, set the relevant watcher to `false` in `~/.bikky/config.json`:
+
+```json
+{
+  "watchers": {
+    "copilot": { "enabled": false },
+    "claude": { "enabled": false }
+  }
+}
+```
+
+You can also set `daemon.extract_every_sec` to `0` to disable background extraction while keeping MCP recall tools available.
+
+For a local-storage, local-model setup that minimizes what leaves your machine, see the [privacy-first quickstart][privacy-quickstart].
+
 ## License
 
 AGPL-3.0 — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,58 @@
+# Security Policy
+
+Thanks for helping keep bikky and its users safe.
+
+## Supported Versions
+
+Security fixes land on the latest minor release of each package:
+
+| Package    | Supported versions       |
+| ---------- | ------------------------ |
+| `bikky`    | latest minor (`0.4.x`)   |
+| `bikky-ui` | latest minor (`0.1.x`)   |
+
+Older versions are not patched. If you're on an old version, please upgrade before reporting a vulnerability that may already be fixed.
+
+## Reporting a Vulnerability
+
+**Please do not open a public GitHub issue for security reports.**
+
+Use GitHub's private vulnerability reporting:
+
+1. Go to https://github.com/bikky-dev/bikky/security/advisories/new
+2. Fill in the details — include reproduction steps, affected versions, and impact.
+3. Submit. We'll get an email and respond from there.
+
+If you can't use GitHub for any reason, open a regular issue titled "Security contact request" (no details) and we'll arrange a private channel.
+
+## What to Expect
+
+| When                                | What happens                                                                  |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| Within **3 business days**          | We acknowledge the report and confirm we can reproduce (or ask for more info). |
+| Within **7 business days**          | We share an initial assessment: severity, affected versions, intended fix.    |
+| Within **90 days** (typical)        | We ship a patched release and publish a GitHub Security Advisory with credit.  |
+
+For critical issues actively being exploited, we'll move faster and coordinate disclosure timing with you.
+
+## Scope
+
+In scope:
+- The `bikky` npm package (CLI, MCP server, daemon).
+- The `bikky-ui` npm package (local web UI server + frontend).
+- The default daemon, postinstall scripts, and any code shipped in either tarball.
+
+Out of scope:
+- Vulnerabilities in dependencies that are already tracked upstream (please report to the upstream maintainer).
+- Vulnerabilities that require physical access to the user's machine or already-compromised credentials.
+- Findings from automated scanners with no demonstrated impact.
+- Issues in third-party services bikky integrates with (Qdrant Cloud, OpenAI, etc.) — report those to the respective vendors.
+
+## Safe Harbor
+
+We support good-faith security research. If you make a reasonable effort to comply with this policy, we will:
+- Not pursue legal action against you for the research.
+- Work with you to understand and resolve the issue quickly.
+- Recognise your contribution publicly (with your permission) in the advisory and release notes.
+
+Thank you for helping make bikky safer for everyone.

package/SUPPORT.md

@@ -0,0 +1,22 @@
+# Support
+
+Thanks for using bikky.
+
+## Questions and usage help
+
+Open a GitHub issue using the most relevant template. Include your OS, Node.js version, package version, MCP client, and the output of:
+
+```bash
+bikky status
+```
+
+Please redact API keys, access tokens, local file contents, and any private transcript data before posting.
+
+## Bugs
+
+Use the bug report template and include a minimal reproduction when possible. If the issue involves setup, include whether you installed with `npm install -g bikky`, `npx bikky`, or a local checkout.
+
+## Security reports
+
+Do not open a public issue for vulnerabilities. Follow [SECURITY.md](SECURITY.md) and use GitHub private vulnerability reporting.
+