bikky 0.4.0 → 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

@@ -59,7 +59,7 @@ We aim for **focused, fast unit tests** that lock in behaviour without being a m
 
 We deliberately **do not** test:
 
-- LLM prompt quality or extraction accuracy. Those live in the separate [`bikky-evals`](https://github.com/bikky-dev/bikky-evals) repo, which uses DeepEval for prompt-level scoring.
+- 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.
 

package/README.md

@@ -77,6 +77,8 @@ 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
@@ -130,6 +132,8 @@ For hosted models, custom providers, multiple profiles, or advanced tuning, use
 
 > 📖 **Full configuration guide:** [docs/configuration.md][configuration-guide]
 >
+> 🔒 **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
@@ -141,6 +145,7 @@ Most installs use one Qdrant destination. If you need clean separation later, re
   "destinations": [
     {
       "name": "platform",
+      "description": "Shared platform engineering memory.",
       "qdrant_url": "https://platform.cloud.qdrant.io:6333",
       "qdrant_api_key": "...",
       "collection": "bikky-platform",
@@ -148,15 +153,17 @@ Most installs use one Qdrant destination. If you need clean separation later, re
     },
     {
       "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. Existing single-Qdrant configs continue to work.
+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)
 
@@ -165,6 +172,7 @@ That is enough for explicit selection in the UI and tools. Add routing rules onl
 [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
 
 ---
@@ -212,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.
+

package/dist/config.d.ts

@@ -95,6 +95,8 @@ export interface DestinationMatch {
 export interface Destination {
     /** Stable, unique name. Used as the `destination` override on tool calls. */
     name: string;
+    /** Human-readable guidance for LLMs/users about when to use this destination. */
+    description?: string;
     qdrant_url: string;
     qdrant_api_key: string | null;
     collection: string;
@@ -103,6 +105,15 @@ export interface Destination {
     /** Routing rules. Omit for a destination that is only reachable by override. */
     match?: DestinationMatch;
 }
+export type SearchScopeTarget = "routed" | "all" | string | string[];
+export interface SearchScopeDefinition {
+    /** Stable scope name that MCP clients can pass as `search_scope`. */
+    name: string;
+    /** Guidance for LLMs/users about when this scope should be used. */
+    description: string;
+    /** Destination selector: "routed", "all", a destination name, or destination names. */
+    destinations: SearchScopeTarget;
+}
 export interface BikkyConfig {
     /**
      * Top-level Qdrant fields. When `destinations` is empty, a single default
@@ -118,6 +129,14 @@ export interface BikkyConfig {
      * default flag → first entry.
      */
     destinations: Destination[];
+    /**
+     * Default read/search scope. "routed" preserves historical behavior
+     * (one destination via routing rules); "all" fans out to every destination;
+     * a destination name or list searches only those destinations.
+     */
+    default_search_scope: SearchScopeTarget;
+    /** Optional named search scopes exposed to MCP clients with descriptions. */
+    search_scopes: SearchScopeDefinition[];
     aws_profile: string | null;
     embedding: EmbeddingConfig;
     llm: LLMConfig;

package/dist/config.js

@@ -29,6 +29,8 @@ const DEFAULTS = {
     qdrant_api_key: null,
     collection: "bikky",
     destinations: [],
+    default_search_scope: "routed",
+    search_scopes: [],
     aws_profile: null,
     embedding: {
         provider: "ollama",
@@ -185,17 +187,29 @@ const destinationMatchSchema = z.object({
 }).passthrough();
 const destinationFileSchema = z.object({
     name: z.string().min(1),
+    description: z.string().optional(),
     qdrant_url: z.string().min(1),
     qdrant_api_key: z.string().nullable().optional(),
     collection: z.string().min(1),
     default: z.boolean().optional(),
     match: destinationMatchSchema.optional(),
 }).passthrough();
+const searchScopeTargetSchema = z.union([
+    z.string().min(1),
+    z.array(z.string().min(1)).min(1),
+]);
+const searchScopeDefinitionFileSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    destinations: searchScopeTargetSchema,
+}).passthrough();
 const configFileSchema = z.object({
     qdrant_url: z.string().nullable().optional(),
     qdrant_api_key: z.string().nullable().optional(),
     collection: z.string().optional(),
     destinations: z.array(destinationFileSchema).optional(),
+    default_search_scope: searchScopeTargetSchema.optional(),
+    search_scopes: z.array(searchScopeDefinitionFileSchema).optional(),
     aws_profile: z.string().nullable().optional(),
     embedding: embeddingConfigFileSchema.optional(),
     llm: llmConfigFileSchema.optional(),
@@ -363,6 +377,63 @@ export function validateConfigObject(raw) {
             issues.push({ severity: "error", path: "destinations", message: `at most one destination may set 'default: true' (found ${defaultCount})` });
         }
     }
+    const destinationNames = new Set();
+    if (Array.isArray(raw.destinations)) {
+        for (const entry of raw.destinations) {
+            if (isObject(entry) && typeof entry.name === "string" && entry.name.trim() !== "") {
+                destinationNames.add(entry.name);
+            }
+        }
+    }
+    const searchScopeNames = new Set();
+    if (Array.isArray(raw.search_scopes)) {
+        for (const entry of raw.search_scopes) {
+            if (isObject(entry) && typeof entry.name === "string" && entry.name.trim() !== "") {
+                searchScopeNames.add(entry.name);
+            }
+        }
+    }
+    const validateSearchScopeTarget = (target, pathName) => {
+        const values = Array.isArray(target) ? target : [target];
+        for (const [idx, value] of values.entries()) {
+            const valuePath = Array.isArray(target) ? `${pathName}[${idx}]` : pathName;
+            if (typeof value !== "string" || value.trim() === "")
+                continue;
+            const normalized = value.trim();
+            if (normalized === "all" || normalized === "routed" || destinationNames.size === 0)
+                continue;
+            if (searchScopeNames.has(normalized))
+                continue;
+            if (!destinationNames.has(normalized)) {
+                issues.push({
+                    severity: "warning",
+                    path: valuePath,
+                    message: `references unknown destination '${normalized}'`,
+                });
+            }
+        }
+    };
+    if (Object.prototype.hasOwnProperty.call(raw, "default_search_scope")) {
+        validateSearchScopeTarget(raw.default_search_scope, "default_search_scope");
+    }
+    if (Array.isArray(raw.search_scopes)) {
+        const seenScopeNames = new Set();
+        raw.search_scopes.forEach((entry, idx) => {
+            const base = `search_scopes[${idx}]`;
+            if (!isObject(entry)) {
+                issues.push({ severity: "error", path: base, message: "must be an object" });
+                return;
+            }
+            const name = entry.name;
+            if (typeof name === "string" && name.trim() !== "") {
+                if (seenScopeNames.has(name)) {
+                    issues.push({ severity: "error", path: `${base}.name`, message: `duplicate search scope name '${name}'` });
+                }
+                seenScopeNames.add(name);
+            }
+            validateSearchScopeTarget(entry.destinations, `${base}.destinations`);
+        });
+    }
     const embedding = childObject(raw, "embedding");
     if (embedding)
         validateUrlLike(embedding.base_url, "embedding.base_url", issues);
@@ -599,6 +670,7 @@ export function getEffectiveDestinations(config = loadConfig()) {
         return [];
     return [{
             name: "default",
+            description: "Default Qdrant destination synthesized from the top-level qdrant_url, qdrant_api_key, and collection settings.",
             qdrant_url: config.qdrant_url,
             qdrant_api_key: config.qdrant_api_key,
             collection: config.collection,

package/dist/daemon/extraction.d.ts

@@ -1,12 +1,14 @@
 /**
- * Events-based memory extraction — reads Copilot CLI events.jsonl transcripts,
+ * Events-based memory extraction — reads supported coding-agent transcripts,
  * extracts facts via LLM, and stores them in Qdrant with source: "system".
  *
  * Uses a JSON file for extraction state (high-water byte offsets) instead of SQLite.
- * Active session detection scans ~/.copilot/session-state/ for lock files.
+ * Copilot session detection uses lock files. Claude Code detection uses
+ * top-level JSONL transcripts under ~/.claude/projects.
  */
 import type { BikkyConfig } from "../config.js";
 import type { LogFn } from "./qdrant.js";
+import { type TranscriptSource } from "./transcript-sources.js";
 export declare const setLogger: (fn: LogFn) => void;
 export declare const DEFAULT_EXTRACTION_PROMPT = "You are Bikky's memory extraction agent for open-source coding agents. Extract durable, reusable facts that help a future agent continue work without rereading the whole transcript.\n\n## Core rule\nExtract fewer, sharper memories. A candidate fact must be independently useful after the session is gone.\n\n## Quality gate\nEvery fact must pass at least one gate:\n1. GREPPABLE: names a file path, package, symbol, config key, CLI flag, issue/PR, service, or API a future agent can search for.\n2. RUNNABLE: contains a command, URL, setting, port, or procedure that can be executed or checked.\n3. NAVIGABLE: tells a future agent where to look and what that location means.\n4. DECISIVE: records a durable decision, rationale, constraint, convention, or preference.\n5. DIAGNOSTIC: captures a repeatable failure mode, root cause, or troubleshooting gotcha.\n\n## Ontology\n- domain is the activity profile. For coding-agent captures use \"software_engineering\".\n- category is subject matter: engineering | product | human | system.\n- kind is object shape. For this prompt, emit only kind=\"fact\".\n- memory_subtype must be one of:\n  codebase_map | architecture_decision | infra_topology | access_pattern | operational_procedure | domain_rule | product_decision | product_requirement | user_workflow | roadmap_item | success_metric | market_insight | troubleshooting_gotcha | preference | person_profile | ownership_note | working_agreement | activity_event.\n\n## Examples\nGOOD:\n- \"The UI smoke tests live in packages/ui/tests/smoke.spec.ts and run through npm run test:e2e with mocked /api/memory/* responses.\"\n- \"Use workspace_id as the tenancy/access boundary; domain is reserved for activity profile such as software_engineering.\"\n- \"If Qdrant order_by fails with a missing index error, create a datetime payload index for the sorted field before retrying.\"\n- \"The memory page should show categories and concrete subtype chips directly; a sub-tab layer makes the ontology harder to understand.\"\n- \"Saber prefers Node's built-in test runner for root tests; do not add Jest just for daemon unit tests.\"\n- \"Saber merged PR #85 after approving the subtype UX copy changes.\"\n\nBAD:\n- \"The tests were fixed.\" (status only)\n- \"We reviewed the code.\" (session narration)\n- \"The deployment succeeded.\" (transient and not reusable)\n- \"The agent used npm.\" (tool narration)\n- \"There was an error.\" (no root cause or reusable detail)\n\n## Output format\nReturn strict JSON:\n{\"facts\":[\n  {\n    \"content\":\"One self-contained durable fact.\",\n    \"category\":\"engineering\",\n    \"memory_subtype\":\"codebase_map\",\n    \"action_actor\":\"optional actor for activity_event only\",\n    \"action_type\":\"optional action verb for activity_event only\",\n    \"action_object\":\"optional durable object for activity_event only\",\n    \"action_outcome\":\"optional durable outcome for activity_event only\",\n    \"entities\":[\"repo-or-tool\",\"specific-module\"],\n    \"confidence\":0.9,\n    \"importance\":0.7,\n    \"quality_score\":0.8,\n    \"confidence_reason\":\"Explicitly stated in the transcript.\",\n    \"repo\":\"optional/repo-or-package\",\n    \"branch\":\"optional-branch\",\n    \"task_key\":\"optional issue/PR/task key\",\n    \"workstream_key\":\"optional stable workstream key\"\n  }\n]}\n\nScoring:\n- confidence: 0.9 explicit, 0.7 strong inference, 0.55 weak but useful inference.\n- importance: 0.8+ for decisions, infra, procedures, access, recurring failures, product requirements, ownership, and state-changing activity events; 0.6+ for useful codebase maps/preferences.\n- quality_score: 0.8+ passes multiple gates, 0.6+ passes one strong gate, below 0.6 should usually be omitted.\n\nIf nothing passes the quality gate, return {\"facts\":[]}.";
 export type Volatility = "stable" | "evolving" | "transient" | "ephemeral";
@@ -60,5 +62,13 @@ export interface ExtractionHealth {
     active_session_count: number;
     /** Configured copilot watcher path at the time of the tick. */
     watcher_path: string;
+    /** Per-source health, including non-Copilot watchers. */
+    sources?: Record<TranscriptSource, ExtractionSourceHealth>;
+}
+export interface ExtractionSourceHealth {
+    enabled: boolean;
+    watcher_path: string;
+    active_session_count: number;
+    last_active_session_at: string | null;
 }
 //# sourceMappingURL=extraction.d.ts.map