wayfind 2.0.69 → 2.0.71

package/README.md

@@ -1,68 +1,55 @@
 # Wayfind
 
-**Team decision trail for AI-assisted development.**
+**Team memory for AI-assisted engineering.**
 
-> AI makes individual engineers faster. Nobody has solved coherent, maintainable software built by a *team* over time. Every handoff loses context. Wayfind captures it.
+Your AI coding assistant forgets everything between sessions. Wayfind gives it a memory — for you and your whole team.
+
+Plain markdown files. No infrastructure. Works with any MCP client.
 
 [![CI](https://github.com/usewayfind/wayfind/actions/workflows/ci.yml/badge.svg)](https://github.com/usewayfind/wayfind/actions/workflows/ci.yml)
-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/wayfind)](https://www.npmjs.com/package/wayfind)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
----
-
-## Install
-
-### Claude Code plugin (recommended)
+**Works with:** Claude Code | Cursor | Any MCP client
 
-In a Claude Code session:
+---
 
-```
-/plugin marketplace add usewayfind/wayfind
-/plugin install wayfind@usewayfind
-```
+## The Problem
 
-Then initialize a repo:
+AI coding assistants are stateless. Every session starts cold. The decisions you made yesterday, the architecture you agreed on last week, the reason you chose Postgres over Mongo — gone. You re-explain, or the AI guesses wrong.
 
-```
-/wayfind:init-memory
-```
+Now multiply that across a team. Five engineers, each with their own AI sessions, none of them aware of what the others decided. Your PM reads the standup notes, but the AI that writes the code doesn't.
 
-Your AI sessions now resume where you left off instead of cold-starting.
+## What Wayfind Does
 
-### npm CLI
+**For you:** Sessions resume where they left off. Decisions are extracted automatically and become searchable history. Drift detection flags when work veers from the stated goal.
 
-The plugin includes the CLI, but you can also install it standalone:
+**For your team:** A daily digest summarizes what everyone shipped, decided, and discovered — tailored per role (engineering, product, design, strategy). Team members who use AI tools get session memory directly. Everyone else gets a Slack digest.
 
-```bash
-npm install -g wayfind
-wayfind init
-```
+**For your AI tools:** An MCP server exposes your team's full decision history as tools. Claude, Cursor, or any MCP client can search decisions, browse by date, and retrieve context — no file reading or guessing.
 
-The CLI is required for digest generation, Slack bot, signal connectors, and team management. The plugin handles session hooks and slash commands.
+<!-- TODO: demo GIF here — see #175 -->
 
 ---
 
-## What It Does
+## Quick Start
 
-### For You (solo engineer)
+### Option A: Claude Code plugin
 
-- **Persistent memory** — sessions pick up where the last one ended
-- **Automatic journal** — decisions and rationale extracted from every session
-- **Searchable history** — `wayfind search-journals "auth refactor"`
-- **Drift detection** — AI flags when work drifts from the stated goal
-
-### For Your Team
-
-- **Digests** — weekly summaries tailored per role (engineering, product, design, strategy)
-- **Slack bot** — anyone on the team asks `@wayfind` and gets answers from the decision trail
-- **Signal connectors** — pull context from GitHub, Intercom, and Notion into digests
-- **Context shift detection** — surfaces significant pivots and architecture changes
+```
+/plugin marketplace add usewayfind/wayfind
+/plugin install wayfind@usewayfind
+/wayfind:init-memory
+```
 
-Only the engineer installs anything. Everyone else sees a Slack digest.
+### Option B: npm (works with any AI tool)
 
+```bash
+npm install -g wayfind
+wayfind init
 ```
-/wayfind:init-team     # Set up team context, journals, and digests
-```
+
+Your next AI session has memory. That's it.
 
 ---
 
@@ -85,118 +72,72 @@ All context is plain markdown in directories you control:
 
 No proprietary formats. No vendor lock-in. `grep` works if Wayfind breaks.
 
-### The Session Protocol
-
-**Start:** AI reads state files, summarizes context, asks "What's the goal?"
-
-**Mid-session:** If work drifts from the goal, the AI flags it.
+### The Session Loop
 
-**End:** Decisions are extracted, written as journal entries, and synced to the team repo — automatically via hooks.
+1. **Start** — AI reads state files, summarizes context, asks "What's the goal?"
+2. **Mid-session** — If work drifts from the goal, the AI flags it.
+3. **End** — Decisions are extracted, written as journal entries, and synced to the team repo — automatically via hooks.
 
-### Digests
+### Team Digests
 
-Each role sees the same underlying data through a different lens:
+Each role sees the same data through a different lens:
 
-- **Engineering**: What shipped, what drifted, patterns
+- **Engineering**: What shipped, what drifted, what patterns emerged
 - **Product**: What shipped vs. planned, discovery signals
-- **Design**: UX decisions, implementation gaps vs. design intent
 - **Strategy**: Cross-team patterns, drift trends, capability gaps
 
-### Signal Connectors
+The digest posts to Slack. Anyone on the team — engineer, PM, CEO — who uses an AI tool gets session memory. Everyone else gets the digest.
 
-```bash
-wayfind pull github       # Issues, PRs, Actions status
-wayfind pull intercom     # Support conversations, tags, response times
-wayfind pull notion       # Pages, databases, comments
-wayfind pull --all        # All configured channels
-```
+### MCP Server
 
----
+Wayfind includes an MCP server that exposes team context to any MCP-compatible AI tool. Auto-registered during `wayfind init`.
 
-## Commands
-
-### Plugin skills (in Claude Code)
-
-| Skill | Description |
-|-------|-------------|
-| `/wayfind:init-memory` | Initialize context for the current repo |
-| `/wayfind:init-team` | Set up team context, journals, and digests |
-| `/wayfind:doctor` | Check installation health |
-| `/wayfind:standup` | Daily standup summary |
-| `/wayfind:journal` | Weekly journal digest and drift detection |
-| `/wayfind:review-prs` | Review overnight PRs |
-
-### CLI commands
-
-| Command | Description |
-|---------|-------------|
-| `wayfind init` | Install for your AI tool |
-| `wayfind doctor` | Check installation health |
-| `wayfind update` | Update hooks and commands |
-| `wayfind status` | Cross-project status |
-| `wayfind team create` | Create a new team |
-| `wayfind team join` | Join an existing team |
-| `wayfind digest` | Generate persona-specific digests |
-| `wayfind digest --deliver` | Generate and post to Slack |
-| `wayfind bot` | Start the Slack bot |
-| `wayfind reindex` | Index journals + conversations |
-| `wayfind search-journals <q>` | Search decision history |
-| `wayfind pull <channel>` | Pull signals from a source |
-| `wayfind journal sync` | Sync journals to team repo |
-| `wayfind onboard <repo>` | Generate onboarding context pack |
-| `wayfind deploy init` | Scaffold Docker deployment |
-| `wayfind deploy --team <id>` | Scaffold per-team Docker deployment |
-| `wayfind deploy set-endpoint <url>` | Set container endpoint for team search |
-| `wayfind deploy list` | List running team containers |
-| `wayfind deploy status` | Check container health |
-| `wayfind migrate-to-plugin` | Remove old hooks (after plugin install) |
-
-Run `wayfind help` for the full list.
+**Tools:**
 
----
+| Tool | What it does |
+|------|-------------|
+| `search_context` | Search decisions by query, date range, author, or repo. Semantic or browse mode. |
+| `get_entry` | Retrieve the full content of a specific entry. |
+| `get_signals` | Recent GitHub, Intercom, and Notion activity. |
+| `get_team_status` | Current team state: who's working on what, active projects, blockers. |
+| `add_context` | Capture a decision or blocker from the current session. |
+| `record_feedback` | Rate whether a result was useful (improves future retrieval). |
 
-## MCP Server
+Each team member's MCP server searches their local content store — journals synced from the shared team repo, with local embeddings generated automatically. No infrastructure required.
 
-Wayfind includes an MCP server (`wayfind-mcp`) that exposes team context to any MCP-compatible AI tool.
+---
 
-**Tools:** `search_context`, `get_entry`, `list_recent`, `get_signals`, `get_team_status`, `get_personas`, `record_feedback`, `add_context`
+## Signal Connectors
 
-Auto-registered during `wayfind init`. When a team container is running, the local MCP server proxies semantic search to it automatically — no config needed beyond the team-context repo.
+Pull external context into digests:
 
----
-
-## Environment Variables
+```bash
+wayfind pull github       # Issues, PRs, Actions status
+wayfind pull intercom     # Support conversations, tags, response times
+wayfind pull notion       # Pages, databases, comments
+wayfind pull --all        # All configured channels
+```
 
-### For digests and bot
+---
 
-| Variable | Description |
-|----------|-------------|
-| `ANTHROPIC_API_KEY` | Digest generation and bot answers |
-| `SLACK_BOT_TOKEN` | Slack bot token (`xoxb-...`) |
-| `SLACK_APP_TOKEN` | Slack app-level token (`xapp-...`) |
-| `GITHUB_TOKEN` | Signal data and journal sync |
+## Team Setup
 
-### Optional
+```
+/wayfind:init-team
+```
 
-| Variable | Description |
-|----------|-------------|
-| `OPENAI_API_KEY` | Upgrade semantic search to OpenAI embeddings (Xenova local model is used by default — no key needed) |
-| `TEAM_CONTEXT_LLM_MODEL` | LLM for digests (default: `claude-sonnet-4-5-20250929`) |
-| `TEAM_CONTEXT_DIGEST_SCHEDULE` | Cron schedule (default: `0 8 * * 1` — Monday 8am) |
-| `TEAM_CONTEXT_EXCLUDE_REPOS` | Repos to exclude from digests |
-| `TEAM_CONTEXT_TELEMETRY` | `true` for anonymous usage telemetry |
+This walks you through creating a team, setting up profiles, creating a shared team-context repo, and configuring Slack digest delivery. Multi-team support built in — bind repos to different teams, each with isolated context.
 
 ---
 
 ## Tool Support
 
-| Tool | Status | Setup |
-|------|--------|-------|
-| Claude Code | Full support (plugin) | `/plugin marketplace add usewayfind/wayfind` |
-| Claude Code | Full support (npm) | `wayfind init` |
-| Cursor | Session protocol | `wayfind init-cursor` |
-| Generic | Manual | See `specializations/generic/` |
-| Any MCP client | Full support (MCP) | `wayfind init` auto-registers |
+| Tool | How | Setup |
+|------|-----|-------|
+| **Claude Code** | Plugin (full support) | `/plugin marketplace add usewayfind/wayfind` |
+| **Cursor** | MCP server | `wayfind init` auto-registers |
+| **Any MCP client** | MCP server | `wayfind init` auto-registers |
+| **Slack** | Bot + digests | `wayfind bot --configure` |
 
 ---
 
@@ -206,27 +147,23 @@ Everything that runs on your machine is open source (Apache 2.0).
 
 | Open Source (this repo) | Commercial (future) |
 |---|---|
-| CLI and all commands | Cloud-hosted team aggregation |
+| CLI, plugin, and all commands | Cloud-hosted team aggregation |
 | Session protocol and journal extraction | Managed digest delivery |
-| Content store and search | Web dashboard |
+| Content store, semantic search, MCP server | Web dashboard |
 | Signal connectors (GitHub, Intercom, Notion) | SSO and tenant isolation |
 | Digest generation (your API key) | |
 | Slack bot (self-hosted) | |
 | Multi-team support | |
-| MCP server (local + container proxy) | |
-| Per-team content store isolation | |
-
-See [LICENSING.md](LICENSING.md) for details.
 
 ---
 
 ## Architecture
 
 - [Data Flow](docs/architecture/data-flow.md) — sessions to digests
-- [Principles](docs/architecture/architecture-principles.md) — the eight constraints
+- [Query Path](docs/architecture/query-path.md) — how queries reach the content store
 - [Content Store](docs/architecture/content-store.md) — indexing, search, schema
+- [Principles](docs/architecture/architecture-principles.md) — the eight constraints
 - [Signal Channels](docs/architecture/architecture-signal-channels.md) — connector architecture
-- [Signal Roadmap](docs/architecture/signal-source-roadmap.md) — planned connectors
 
 ---
 
@@ -242,4 +179,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). Good first contributions:
 
 ## License
 
-Apache 2.0. See [LICENSE](LICENSE) and [LICENSING.md](LICENSING.md).
+Apache 2.0. See [LICENSE](LICENSE).

package/bin/connectors/llm.js

@@ -302,6 +302,92 @@ async function call(config, systemPrompt, userContent) {
   }
 }
 
+// ── Tool-use relay ──────────────────────────────────────────────────────────
+
+/**
+ * Call the Anthropic API with tool-use support, looping until the model stops.
+ * @param {Object} config - Provider configuration (must be Anthropic)
+ * @param {string} systemPrompt - System prompt
+ * @param {string} userContent - User message text
+ * @param {Array} tools - Anthropic tool-use format tool definitions
+ * @param {Function} handleToolCall - async (name, input) => result
+ * @returns {Promise<string>} - Final text response
+ */
+async function callWithTools(config, systemPrompt, userContent, tools, handleToolCall) {
+  const apiKey = process.env[config.api_key_env];
+  if (!apiKey) {
+    throw new Error(`Anthropic: Missing API key. Set ${config.api_key_env} environment variable.`);
+  }
+
+  const headers = {
+    'x-api-key': apiKey,
+    'anthropic-version': ANTHROPIC_VERSION,
+  };
+
+  const MAX_ITERATIONS = 10;
+  let messages = [{ role: 'user', content: userContent }];
+
+  for (let i = 0; i < MAX_ITERATIONS; i++) {
+    const payload = JSON.stringify({
+      model: config.model,
+      max_tokens: config.max_tokens || DEFAULT_MAX_TOKENS,
+      system: systemPrompt,
+      messages,
+      tools,
+    });
+
+    const res = await httpPost(ANTHROPIC_API_URL, headers, payload);
+    checkResponse(res, 'Anthropic');
+
+    let data;
+    try {
+      data = JSON.parse(res.body);
+    } catch {
+      throw new Error('Anthropic: Failed to parse response JSON.');
+    }
+
+    if (!data.content || !Array.isArray(data.content)) {
+      throw new Error('Anthropic: Response missing content array.');
+    }
+
+    // If the model is done, extract and return the final text
+    if (data.stop_reason !== 'tool_use') {
+      const textBlock = data.content.find(b => b.type === 'text');
+      return textBlock ? textBlock.text : '';
+    }
+
+    // Process tool calls
+    const toolUseBlocks = data.content.filter(b => b.type === 'tool_use');
+    if (toolUseBlocks.length === 0) {
+      // stop_reason is tool_use but no tool_use blocks — treat as done
+      const textBlock = data.content.find(b => b.type === 'text');
+      return textBlock ? textBlock.text : '';
+    }
+
+    // Build tool results
+    const toolResults = [];
+    for (const block of toolUseBlocks) {
+      let result;
+      try {
+        result = await handleToolCall(block.name, block.input);
+      } catch (err) {
+        result = { error: err.message };
+      }
+      toolResults.push({
+        type: 'tool_result',
+        tool_use_id: block.id,
+        content: typeof result === 'string' ? result : JSON.stringify(result),
+      });
+    }
+
+    // Append assistant message + tool results, then loop
+    messages.push({ role: 'assistant', content: data.content });
+    messages.push({ role: 'user', content: toolResults });
+  }
+
+  throw new Error('Anthropic: Tool-use loop exceeded maximum iterations (10).');
+}
+
 // ── Auto-detect available provider ───────────────────────────────────────────
 
 /**
@@ -535,6 +621,7 @@ async function generateEmbeddingAzure(text, options = {}) {
 
 module.exports = {
   call,
+  callWithTools,
   detect,
   generateEmbedding,
   getEmbeddingProviderInfo,

package/bin/content-store.js

@@ -610,7 +610,7 @@ async function indexJournals(options = {}) {
 
 /**
  * Search journals using semantic similarity.
- * Falls back to searchText() if no embeddings available.
+ * Falls back to queryMetadata() browse if no embeddings available.
  * @param {string} query - Search query
  * @param {Object} [options]
  * @param {string} [options.storePath] - Content store directory
@@ -633,7 +633,11 @@ async function searchJournals(query, options = {}) {
   const hasEmbeddings = Object.keys(embeddings).length > 0;
 
   if (!hasEmbeddings) {
-    return searchText(query, options);
+    const browseResults = queryMetadata(options);
+    return browseResults.slice(0, limit).map(r => ({
+      ...r, score: null,
+      _hint: 'Semantic search unavailable — showing recent entries by date. Run "wayfind reindex" to enable semantic search.',
+    }));
   }
 
   // Generate query embedding
@@ -641,8 +645,12 @@ async function searchJournals(query, options = {}) {
   try {
     queryVec = await llm.generateEmbedding(query);
   } catch {
-    // Fall back to text search if embedding fails
-    return searchText(query, options);
+    // Fall back to browse if embedding generation fails
+    const browseResults = queryMetadata(options);
+    return browseResults.slice(0, limit).map(r => ({
+      ...r, score: null,
+      _hint: 'Semantic search unavailable — showing recent entries by date. Run "wayfind reindex" to enable semantic search.',
+    }));
   }
 
   // Score all entries
@@ -662,143 +670,6 @@ async function searchJournals(query, options = {}) {
   return results.slice(0, limit);
 }
 
-/**
- * Full-text search across journal entries.
- * Works without any API key. Matches query words against title, repo, tags.
- * @param {string} query - Search query
- * @param {Object} [options]
- * @param {string} [options.storePath] - Content store directory
- * @param {number} [options.limit] - Max results (default: 10)
- * @param {string} [options.repo] - Filter by repo
- * @param {string} [options.since] - Filter by date (YYYY-MM-DD)
- * @param {string} [options.until] - Filter by date (YYYY-MM-DD)
- * @param {boolean} [options.drifted] - Filter by drift status
- * @returns {Array<{ id: string, score: number, entry: Object }>}
- */
-function searchText(query, options = {}) {
-  const storePath = options.storePath || resolveStorePath();
-  const journalDir = options.journalDir || DEFAULT_JOURNAL_DIR;
-  const limit = options.limit || 10;
-
-  const index = getBackend(storePath).loadIndex();
-  if (!index) return [];
-
-  // Normalize: split on whitespace, hyphens, underscores
-  const queryWords = query.toLowerCase().split(/[\s\-_]+/).filter(w => w.length > 1);
-  if (queryWords.length === 0) return [];
-
-  // Pre-load journal content for full-text search (cache by date+user key)
-  const journalCache = {};
-  function getJournalContent(date, user) {
-    const cacheKey = user ? `${date}-${user}` : date;
-    if (journalCache[cacheKey] !== undefined) return journalCache[cacheKey];
-    if (!journalDir) { journalCache[cacheKey] = null; return null; }
-    // Try authored filename first, then plain date filename
-    const candidates = user
-      ? [path.join(journalDir, `${date}-${user}.md`), path.join(journalDir, `${date}.md`)]
-      : [path.join(journalDir, `${date}.md`)];
-    let content = null;
-    for (const filePath of candidates) {
-      try {
-        content = fs.readFileSync(filePath, 'utf8').toLowerCase();
-        break;
-      } catch {
-        // Try next candidate
-      }
-    }
-    journalCache[cacheKey] = content;
-    return content;
-  }
-
-  const results = [];
-  for (const [id, entry] of Object.entries(index.entries)) {
-    if (!applyFilters(entry, options)) continue;
-
-    // Build searchable text from entry metadata (normalize hyphens/underscores)
-    let searchable = [
-      entry.title,
-      entry.repo,
-      entry.date,
-      entry.user,
-      ...(entry.tags || []),
-    ].filter(Boolean).join(' ').toLowerCase().replace(/[-_]/g, ' ');
-
-    // For signal entries, read content directly from the signal file
-    if (entry.source === 'signal') {
-      const signalsDir = options.signalsDir || resolveSignalsDir();
-      if (signalsDir) {
-        // Signal files live at signalsDir/<channel>/<date>.md or signalsDir/<channel>/<owner>/<repo>/<date>.md
-        // The repo field tells us the path: "signals/<channel>" or "<owner>/<repo>"
-        const repo = entry.repo || '';
-        const candidates = [];
-        if (repo.startsWith('signals/')) {
-          const channel = repo.replace('signals/', '');
-          candidates.push(path.join(signalsDir, channel, `${entry.date}.md`));
-          candidates.push(path.join(signalsDir, channel, `${entry.date}-summary.md`));
-        } else if (repo.includes('/')) {
-          // owner/repo format — find which channel it's under
-          for (const channel of ['github', 'intercom', 'notion']) {
-            candidates.push(path.join(signalsDir, channel, repo, `${entry.date}.md`));
-          }
-        }
-        for (const fp of candidates) {
-          try {
-            const content = fs.readFileSync(fp, 'utf8').toLowerCase();
-            searchable += ' ' + content.replace(/[-_]/g, ' ');
-            break;
-          } catch {
-            // Try next candidate
-          }
-        }
-      }
-    }
-
-    // Also include the full journal entry content if available
-    const journalContent = entry.source !== 'signal' ? getJournalContent(entry.date, entry.user) : null;
-    if (journalContent) {
-      // Find this entry's section in the journal file.
-      // Try exact match first, then normalize hyphens/spaces for fuzzy match.
-      const repoTitle = `${entry.repo} — ${entry.title}`.toLowerCase();
-      let idx = journalContent.indexOf(repoTitle);
-      if (idx === -1) {
-        // Normalize both sides: collapse hyphens, underscores, em-dashes, and extra spaces
-        const norm = (s) => s.replace(/[-_\u2014\u2013]/g, ' ').replace(/\s+/g, ' ').trim();
-        const normalized = norm(repoTitle);
-        // Search through journal headers for a normalized match
-        const headerRegex = /\n## (.+)/g;
-        let match;
-        while ((match = headerRegex.exec(journalContent)) !== null) {
-          const headerNorm = norm(match[1]);
-          if (headerNorm.includes(normalized) || normalized.includes(headerNorm)) {
-            idx = match.index + 1; // skip the \n
-            break;
-          }
-        }
-      }
-      if (idx !== -1) {
-        // Extract from header to next header (or end of file)
-        const nextHeader = journalContent.indexOf('\n## ', idx + 1);
-        const section = nextHeader !== -1 ? journalContent.slice(idx, nextHeader) : journalContent.slice(idx);
-        searchable += ' ' + section.replace(/[-_]/g, ' ');
-      }
-    }
-
-    // Score: count of matching query words
-    let matches = 0;
-    for (const word of queryWords) {
-      if (searchable.includes(word)) matches++;
-    }
-
-    if (matches > 0) {
-      const score = Math.round((matches / queryWords.length) * 1000) / 1000;
-      results.push({ id, score, entry });
-    }
-  }
-
-  results.sort((a, b) => b.score - a.score);
-  return results.slice(0, limit);
-}
-
 /**
  * Apply metadata filters to an entry.
  * @param {Object} entry
@@ -2480,7 +2351,6 @@ module.exports = {
   applyContextShiftToState,
   generateOnboardingPack,
   searchJournals,
-  searchText,
   queryMetadata,
   extractInsights,
   computeQualityProfile,