@copilotkit/pathfinder 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/.env.example +20 -0
  2. package/.superpowers/brainstorm/47098-1775507869/content/homepage-mockup.html +324 -0
  3. package/.superpowers/brainstorm/47098-1775507869/state/server-stopped +1 -0
  4. package/.superpowers/brainstorm/47098-1775507869/state/server.log +13 -0
  5. package/.superpowers/brainstorm/47098-1775507869/state/server.pid +1 -0
  6. package/.superpowers/brainstorm/82141-1775511032/content/migration-v2.html +340 -0
  7. package/.superpowers/brainstorm/82141-1775511032/content/migration.html +340 -0
  8. package/.superpowers/brainstorm/82141-1775511032/state/server-stopped +1 -0
  9. package/.superpowers/brainstorm/82141-1775511032/state/server.log +4 -0
  10. package/.superpowers/brainstorm/82141-1775511032/state/server.pid +1 -0
  11. package/CHANGELOG.md +26 -0
  12. package/LICENSE +21 -0
  13. package/README.md +284 -0
  14. package/dist/config.d.ts +32 -0
  15. package/dist/config.d.ts.map +1 -0
  16. package/dist/config.js +180 -0
  17. package/dist/config.js.map +1 -0
  18. package/dist/db/client.d.ts +22 -0
  19. package/dist/db/client.d.ts.map +1 -0
  20. package/dist/db/client.js +134 -0
  21. package/dist/db/client.js.map +1 -0
  22. package/dist/db/queries.d.ts +51 -0
  23. package/dist/db/queries.d.ts.map +1 -0
  24. package/dist/db/queries.js +271 -0
  25. package/dist/db/queries.js.map +1 -0
  26. package/dist/db/schema.d.ts +11 -0
  27. package/dist/db/schema.d.ts.map +1 -0
  28. package/dist/db/schema.js +63 -0
  29. package/dist/db/schema.js.map +1 -0
  30. package/dist/index.d.ts +2 -0
  31. package/dist/index.d.ts.map +1 -0
  32. package/dist/index.js +366 -0
  33. package/dist/index.js.map +1 -0
  34. package/dist/indexing/chunking/code.d.ts +17 -0
  35. package/dist/indexing/chunking/code.d.ts.map +1 -0
  36. package/dist/indexing/chunking/code.js +277 -0
  37. package/dist/indexing/chunking/code.js.map +1 -0
  38. package/dist/indexing/chunking/index.d.ts +6 -0
  39. package/dist/indexing/chunking/index.d.ts.map +1 -0
  40. package/dist/indexing/chunking/index.js +19 -0
  41. package/dist/indexing/chunking/index.js.map +1 -0
  42. package/dist/indexing/chunking/markdown.d.ts +16 -0
  43. package/dist/indexing/chunking/markdown.d.ts.map +1 -0
  44. package/dist/indexing/chunking/markdown.js +283 -0
  45. package/dist/indexing/chunking/markdown.js.map +1 -0
  46. package/dist/indexing/chunking/raw-text.d.ts +11 -0
  47. package/dist/indexing/chunking/raw-text.d.ts.map +1 -0
  48. package/dist/indexing/chunking/raw-text.js +59 -0
  49. package/dist/indexing/chunking/raw-text.js.map +1 -0
  50. package/dist/indexing/embeddings.d.ts +10 -0
  51. package/dist/indexing/embeddings.d.ts.map +1 -0
  52. package/dist/indexing/embeddings.js +78 -0
  53. package/dist/indexing/embeddings.js.map +1 -0
  54. package/dist/indexing/orchestrator.d.ts +69 -0
  55. package/dist/indexing/orchestrator.d.ts.map +1 -0
  56. package/dist/indexing/orchestrator.js +387 -0
  57. package/dist/indexing/orchestrator.js.map +1 -0
  58. package/dist/indexing/source-indexer.d.ts +68 -0
  59. package/dist/indexing/source-indexer.d.ts.map +1 -0
  60. package/dist/indexing/source-indexer.js +379 -0
  61. package/dist/indexing/source-indexer.js.map +1 -0
  62. package/dist/indexing/url-derivation.d.ts +7 -0
  63. package/dist/indexing/url-derivation.d.ts.map +1 -0
  64. package/dist/indexing/url-derivation.js +31 -0
  65. package/dist/indexing/url-derivation.js.map +1 -0
  66. package/dist/mcp/server.d.ts +10 -0
  67. package/dist/mcp/server.d.ts.map +1 -0
  68. package/dist/mcp/server.js +67 -0
  69. package/dist/mcp/server.js.map +1 -0
  70. package/dist/mcp/tools/bash-fs.d.ts +19 -0
  71. package/dist/mcp/tools/bash-fs.d.ts.map +1 -0
  72. package/dist/mcp/tools/bash-fs.js +134 -0
  73. package/dist/mcp/tools/bash-fs.js.map +1 -0
  74. package/dist/mcp/tools/bash-grep.d.ts +29 -0
  75. package/dist/mcp/tools/bash-grep.d.ts.map +1 -0
  76. package/dist/mcp/tools/bash-grep.js +153 -0
  77. package/dist/mcp/tools/bash-grep.js.map +1 -0
  78. package/dist/mcp/tools/bash-related.d.ts +14 -0
  79. package/dist/mcp/tools/bash-related.d.ts.map +1 -0
  80. package/dist/mcp/tools/bash-related.js +54 -0
  81. package/dist/mcp/tools/bash-related.js.map +1 -0
  82. package/dist/mcp/tools/bash-session.d.ts +23 -0
  83. package/dist/mcp/tools/bash-session.d.ts.map +1 -0
  84. package/dist/mcp/tools/bash-session.js +60 -0
  85. package/dist/mcp/tools/bash-session.js.map +1 -0
  86. package/dist/mcp/tools/bash-telemetry.d.ts +26 -0
  87. package/dist/mcp/tools/bash-telemetry.d.ts.map +1 -0
  88. package/dist/mcp/tools/bash-telemetry.js +53 -0
  89. package/dist/mcp/tools/bash-telemetry.js.map +1 -0
  90. package/dist/mcp/tools/bash-virtual-files.d.ts +3 -0
  91. package/dist/mcp/tools/bash-virtual-files.d.ts.map +1 -0
  92. package/dist/mcp/tools/bash-virtual-files.js +65 -0
  93. package/dist/mcp/tools/bash-virtual-files.js.map +1 -0
  94. package/dist/mcp/tools/bash.d.ts +25 -0
  95. package/dist/mcp/tools/bash.d.ts.map +1 -0
  96. package/dist/mcp/tools/bash.js +140 -0
  97. package/dist/mcp/tools/bash.js.map +1 -0
  98. package/dist/mcp/tools/collect.d.ts +13 -0
  99. package/dist/mcp/tools/collect.d.ts.map +1 -0
  100. package/dist/mcp/tools/collect.js +56 -0
  101. package/dist/mcp/tools/collect.js.map +1 -0
  102. package/dist/mcp/tools/search.d.ts +5 -0
  103. package/dist/mcp/tools/search.d.ts.map +1 -0
  104. package/dist/mcp/tools/search.js +68 -0
  105. package/dist/mcp/tools/search.js.map +1 -0
  106. package/dist/types.d.ts +1237 -0
  107. package/dist/types.d.ts.map +1 -0
  108. package/dist/types.js +163 -0
  109. package/dist/types.js.map +1 -0
  110. package/dist/webhooks/github.d.ts +12 -0
  111. package/dist/webhooks/github.d.ts.map +1 -0
  112. package/dist/webhooks/github.js +117 -0
  113. package/dist/webhooks/github.js.map +1 -0
  114. package/package.json +48 -0
package/.superpowers/brainstorm/82141-1775511032/content/migration.html ADDED
@@ -0,0 +1,340 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Migrate from Mintlify to Pathfinder</title>
7
+ <meta name="description" content="Step-by-step guide to migrating from Mintlify's hosted docs to Pathfinder's self-hosted agentic retrieval in 15 minutes.">
8
+ <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🧭</text></svg>">
9
+ <link rel="preconnect" href="https://fonts.googleapis.com">
10
+ <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&family=Instrument+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
11
+ <style>
12
+ :root {
13
+ --bg-deep: #0a0a0f;
14
+ --bg-surface: #111118;
15
+ --bg-card: #16161f;
16
+ --border: #222233;
17
+ --text-primary: #e8e8f0;
18
+ --text-secondary: #8888a0;
19
+ --text-dim: #555570;
20
+ --accent: #00cc66;
21
+ --accent-glow: rgba(0,204,102,0.15);
22
+ --blue: #4488ff;
23
+ --purple: #aa66ff;
24
+ --warning: #ffaa00;
25
+ --mono: 'JetBrains Mono', monospace;
26
+ --sans: 'Instrument Sans', system-ui, sans-serif;
27
+ }
28
+ * { margin:0; padding:0; box-sizing:border-box; }
29
+ body { background: var(--bg-deep); color: var(--text-primary); font-family: var(--sans); line-height: 1.6; overflow-x:hidden; }
30
+
31
+ /* Noise overlay */
32
+ body::before { content:''; position:fixed; top:0; left:0; width:100%; height:100%; pointer-events:none; z-index:9999;
33
+ background: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.03'/%3E%3C/svg%3E");
34
+ }
35
+
36
+ /* Nav */
37
+ nav { position:fixed; top:0; left:0; right:0; z-index:100; padding: 12px 32px; display:flex; align-items:center; justify-content:space-between;
38
+ background: rgba(10,10,15,0.8); backdrop-filter: blur(20px) saturate(1.8); border-bottom: 1px solid var(--border); }
39
+ .nav-brand { font-family: var(--mono); font-weight: 600; font-size: 15px; color: var(--accent); text-decoration: none; }
40
+ .nav-brand span { color: var(--text-dim); }
41
+ .nav-links { display:flex; gap: 24px; align-items:center; }
42
+ .nav-links a { color: var(--text-secondary); text-decoration:none; font-size: 14px; transition: color 0.2s; }
43
+ .nav-links a:hover { color: var(--text-primary); }
44
+ .nav-links .gh-btn { display:inline-flex; align-items:center; gap:6px; padding: 6px 14px; border: 1px solid var(--border); border-radius: 6px; font-size: 13px; }
45
+ .nav-links .gh-btn:hover { border-color: var(--text-dim); }
46
+
47
+ /* Article layout */
48
+ .article { max-width: 800px; margin: 0 auto; padding: 100px 32px 80px; }
49
+ .article h1 { font-size: 42px; font-weight: 700; line-height: 1.15; margin-bottom: 16px; letter-spacing: -0.02em; }
50
+ .article h1 .accent { color: var(--accent); }
51
+ .article .lead { font-size: 18px; color: var(--text-secondary); margin-bottom: 48px; }
52
+ .article h2 { font-size: 28px; font-weight: 600; margin: 48px 0 16px; padding-top: 16px; border-top: 1px solid var(--border); }
53
+ .article h2:first-of-type { border-top: none; }
54
+ .article h3 { font-size: 20px; font-weight: 600; margin: 32px 0 12px; }
55
+ .article p { color: var(--text-secondary); margin-bottom: 16px; font-size: 15px; }
56
+ .article ul, .article ol { color: var(--text-secondary); margin: 0 0 16px 24px; font-size: 15px; }
57
+ .article li { margin-bottom: 8px; }
58
+ .article li strong { color: var(--text-primary); }
59
+ .article a { color: var(--accent); text-decoration: none; }
60
+ .article a:hover { text-decoration: underline; }
61
+
62
+ /* Code blocks */
63
+ .code-block { background: var(--bg-surface); border: 1px solid var(--border); border-radius: 8px; padding: 16px 20px; font-family: var(--mono); font-size: 13px; line-height: 1.7; overflow-x: auto; margin-bottom: 16px; color: var(--text-primary); }
64
+ .code-block .comment { color: var(--text-dim); }
65
+ .code-block .key { color: var(--warning); }
66
+ .code-block .value { color: var(--blue); }
67
+ .code-block .cmd { color: var(--accent); }
68
+
69
+ /* Inline code */
70
+ .article code { background: var(--bg-surface); border: 1px solid var(--border); border-radius: 4px; padding: 2px 6px; font-family: var(--mono); font-size: 13px; color: var(--accent); }
71
+
72
+ /* Concept mapping table */
73
+ .concept-table { width: 100%; border-collapse: collapse; font-size: 14px; margin-bottom: 24px; }
74
+ .concept-table th { padding: 12px 16px; text-align: left; border-bottom: 2px solid var(--border); color: var(--text-secondary); font-weight: 500; }
75
+ .concept-table th.highlight-col { color: var(--accent); border-bottom-color: var(--accent); }
76
+ .concept-table td { padding: 10px 16px; border-bottom: 1px solid var(--border); color: var(--text-secondary); }
77
+ .concept-table td.highlight-col { background: var(--accent-glow); color: var(--text-primary); }
78
+
79
+ /* Callout cards */
80
+ .callout-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 24px; }
81
+ .callout-card { background: var(--bg-surface); border: 1px solid var(--border); border-radius: 10px; padding: 20px; }
82
+ .callout-card .icon { font-size: 24px; margin-bottom: 8px; }
83
+ .callout-card h4 { font-size: 15px; margin-bottom: 6px; color: var(--text-primary); }
84
+ .callout-card p { font-size: 13px; color: var(--text-secondary); margin-bottom: 0; }
85
+
86
+ /* Gaps section */
87
+ .gap-card { background: var(--bg-surface); border: 1px solid var(--border); border-left: 3px solid var(--warning); border-radius: 0 10px 10px 0; padding: 16px 20px; margin-bottom: 12px; }
88
+ .gap-card h4 { font-size: 14px; margin-bottom: 4px; color: var(--warning); }
89
+ .gap-card p { font-size: 13px; color: var(--text-secondary); margin-bottom: 0; }
90
+
91
+ /* Step numbers */
92
+ .step { display: flex; gap: 16px; margin-bottom: 24px; }
93
+ .step-num { flex-shrink: 0; width: 32px; height: 32px; border-radius: 50%; background: var(--accent); color: var(--bg-deep); font-weight: 700; font-size: 14px; display: flex; align-items: center; justify-content: center; margin-top: 2px; }
94
+ .step-content { flex: 1; }
95
+ .step-content h3 { margin-top: 0; }
96
+
97
+ /* Back link */
98
+ .back-link { display: inline-flex; align-items: center; gap: 8px; color: var(--accent); text-decoration: none; font-size: 14px; margin-top: 32px; }
99
+ .back-link:hover { text-decoration: underline; }
100
+
101
+ /* Footer */
102
+ footer { padding: 40px 32px; border-top: 1px solid var(--border); text-align:center; color: var(--text-dim); font-size: 13px; }
103
+ footer a { color: var(--text-secondary); text-decoration:none; }
104
+
105
+ /* Responsive: Tablet */
106
+ @media (max-width: 768px) {
107
+ .article h1 { font-size: 32px; }
108
+ .article { padding: 90px 16px 60px; }
109
+ .callout-grid { grid-template-columns: 1fr; }
110
+ .concept-table { font-size: 12px; }
111
+ .concept-table th, .concept-table td { padding: 8px 10px; }
112
+ nav { padding: 12px 16px; }
113
+ .nav-links { gap: 12px; }
114
+ }
115
+
116
+ /* Responsive: Mobile */
117
+ @media (max-width: 480px) {
118
+ .article h1 { font-size: 26px; }
119
+ .article .lead { font-size: 15px; }
120
+ .article h2 { font-size: 22px; }
121
+ .nav-links a:not(.gh-btn) { display: none; }
122
+ .code-block { font-size: 11px; padding: 12px 14px; }
123
+ .step { flex-direction: column; gap: 8px; }
124
+ }
125
+ </style>
126
+ </head>
127
+ <body>
128
+
129
+ <nav>
130
+ <a href="index.html" class="nav-brand"><span>$</span> pathfinder</a>
131
+ <div class="nav-links">
132
+ <a href="index.html">Home</a>
133
+ <a href="https://github.com/CopilotKit/pathfinder" class="gh-btn">GitHub</a>
134
+ </div>
135
+ </nav>
136
+
137
+ <article class="article">
138
+ <h1>Migrate from <span class="accent">Mintlify</span> to Pathfinder</h1>
139
+ <p class="lead">Your Markdown docs are already structured for it. This guide takes about 15 minutes and gives you full ownership of your docs retrieval infrastructure.</p>
140
+
141
+ <h2>Why Migrate</h2>
142
+ <ul>
143
+ <li><strong>Own your infrastructure.</strong> No vendor lock-in, no per-seat pricing, no surprise deprecations. Your docs live in your repo, your search runs on your Postgres.</li>
144
+ <li><strong>Both retrieval paradigms.</strong> Mintlify's ChromaFS replaced RAG with filesystem access. Pathfinder composes both — agents pick the right tool for each sub-task.</li>
145
+ <li><strong>Agentic features out of the box.</strong> Session state, vector grep, writable workspaces, cross-source <code>related</code> commands, and telemetry — all config-driven.</li>
146
+ <li><strong>Zero-infra option.</strong> Start with bash-only tools (no database, no API keys) and add RAG when you're ready. Mintlify's ChromaFS always requires Chroma + Redis.</li>
147
+ </ul>
148
+
149
+ <h2>Concept Mapping</h2>
150
+ <p>How Mintlify concepts translate to Pathfinder:</p>
151
+
152
+ <table class="concept-table">
153
+ <thead>
154
+ <tr>
155
+ <th>Mintlify</th>
156
+ <th class="highlight-col">Pathfinder</th>
157
+ <th>Notes</th>
158
+ </tr>
159
+ </thead>
160
+ <tbody>
161
+ <tr><td><code>mint.json</code></td><td class="highlight-col"><code>pathfinder.yaml</code></td><td>Config file — YAML instead of JSON</td></tr>
162
+ <tr><td>Hosted docs site</td><td class="highlight-col">MCP server (self-hosted)</td><td>Agents consume tools, not rendered pages</td></tr>
163
+ <tr><td>ChromaFS collection</td><td class="highlight-col">Source (type: markdown)</td><td>Multiple sources supported</td></tr>
164
+ <tr><td>ChromaFS search</td><td class="highlight-col">Search tool (type: search)</td><td>pgvector instead of Chroma</td></tr>
165
+ <tr><td>ChromaFS find/grep/cat</td><td class="highlight-col">Bash tool (type: bash)</td><td>Same commands, plus session state</td></tr>
166
+ <tr><td>Chroma embeddings</td><td class="highlight-col">OpenAI embeddings</td><td>Configurable model and dimensions</td></tr>
167
+ <tr><td>Chroma + Redis infra</td><td class="highlight-col">PostgreSQL + pgvector</td><td>Single database, no Redis needed</td></tr>
168
+ <tr><td>Manual reingestion</td><td class="highlight-col">Webhook auto-reindex</td><td>GitHub push triggers targeted reindex</td></tr>
169
+ </tbody>
170
+ </table>
171
+
172
+ <h2>Migration Walkthrough</h2>
173
+
174
+ <div class="step">
175
+ <div class="step-num">1</div>
176
+ <div class="step-content">
177
+ <h3>Clone Pathfinder</h3>
178
+ <div class="code-block"><span class="cmd">$</span> git clone https://github.com/CopilotKit/pathfinder.git
179
+ <span class="cmd">$</span> cd pathfinder
180
+ <span class="cmd">$</span> cp pathfinder.example.yaml pathfinder.yaml</div>
181
+ </div>
182
+ </div>
183
+
184
+ <div class="step">
185
+ <div class="step-num">2</div>
186
+ <div class="step-content">
187
+ <h3>Map your docs source</h3>
188
+ <p>Open <code>pathfinder.yaml</code> and add your docs repo as a source. If your Mintlify docs live at <code>docs/</code> in your repo:</p>
189
+ <div class="code-block"><span class="key">sources:</span>
190
+ - <span class="key">name:</span> <span class="value">docs</span>
191
+ <span class="key">type:</span> <span class="value">markdown</span>
192
+ <span class="key">repo:</span> <span class="value">https://github.com/your-org/your-repo.git</span>
193
+ <span class="key">path:</span> <span class="value">docs/</span>
194
+ <span class="key">file_patterns:</span> [<span class="value">"**/*.mdx"</span>, <span class="value">"**/*.md"</span>]
195
+ <span class="key">chunk:</span>
196
+ <span class="key">target_tokens:</span> <span class="value">600</span>
197
+ <span class="key">overlap_tokens:</span> <span class="value">50</span></div>
198
+ </div>
199
+ </div>
200
+
201
+ <div class="step">
202
+ <div class="step-num">3</div>
203
+ <div class="step-content">
204
+ <h3>Configure tools</h3>
205
+ <p>Define how agents access your docs. You can use search (RAG), bash (filesystem), or both:</p>
206
+ <div class="code-block"><span class="key">tools:</span>
207
+ <span class="comment"># Semantic search — like ChromaFS search but with pgvector</span>
208
+ - <span class="key">name:</span> <span class="value">search-docs</span>
209
+ <span class="key">type:</span> <span class="value">search</span>
210
+ <span class="key">source:</span> <span class="value">docs</span>
211
+ <span class="key">default_limit:</span> <span class="value">5</span>
212
+
213
+ <span class="comment"># Filesystem exploration — like ChromaFS find/grep/cat</span>
214
+ - <span class="key">name:</span> <span class="value">explore-docs</span>
215
+ <span class="key">type:</span> <span class="value">bash</span>
216
+ <span class="key">sources:</span> [<span class="value">docs</span>]
217
+ <span class="key">bash:</span>
218
+ <span class="key">session_state:</span> <span class="value">true</span>
219
+ <span class="key">grep_strategy:</span> <span class="value">hybrid</span></div>
220
+ </div>
221
+ </div>
222
+
223
+ <div class="step">
224
+ <div class="step-num">4</div>
225
+ <div class="step-content">
226
+ <h3>Set environment variables</h3>
227
+ <p>Create a <code>.env</code> file with your credentials:</p>
228
+ <div class="code-block"><span class="comment"># Required for RAG search tools</span>
229
+ <span class="key">OPENAI_API_KEY</span>=<span class="value">sk-...</span>
230
+ <span class="key">DATABASE_URL</span>=<span class="value">postgresql://user:pass@localhost:5432/pathfinder</span>
231
+
232
+ <span class="comment"># Optional: for private repos</span>
233
+ <span class="key">GITHUB_TOKEN</span>=<span class="value">ghp_...</span>
234
+
235
+ <span class="comment"># Optional: for webhook auto-reindex</span>
236
+ <span class="key">GITHUB_WEBHOOK_SECRET</span>=<span class="value">your-secret</span></div>
237
+ <p>If you only use bash tools (no search), you can skip <code>OPENAI_API_KEY</code> and <code>DATABASE_URL</code> entirely.</p>
238
+ </div>
239
+ </div>
240
+
241
+ <div class="step">
242
+ <div class="step-num">5</div>
243
+ <div class="step-content">
244
+ <h3>Start the server</h3>
245
+ <div class="code-block"><span class="cmd">$</span> docker compose up</div>
246
+ <p>This starts Pathfinder and PostgreSQL. The first boot automatically indexes your sources.</p>
247
+ </div>
248
+ </div>
249
+
250
+ <div class="step">
251
+ <div class="step-num">6</div>
252
+ <div class="step-content">
253
+ <h3>Connect your AI agent</h3>
254
+ <p>Point your agent's MCP config at Pathfinder:</p>
255
+ <div class="code-block">{
256
+ <span class="key">"mcpServers"</span>: {
257
+ <span class="key">"docs"</span>: { <span class="key">"url"</span>: <span class="value">"http://localhost:3001/mcp"</span> }
258
+ }
259
+ }</div>
260
+ <p>Your agent now has access to both search and bash tools.</p>
261
+ </div>
262
+ </div>
263
+
264
+ <div class="step">
265
+ <div class="step-num">7</div>
266
+ <div class="step-content">
267
+ <h3>Set up auto-reindex (optional)</h3>
268
+ <p>Add webhook config so docs reindex automatically when you push:</p>
269
+ <div class="code-block"><span class="key">webhook:</span>
270
+ <span class="key">repo_sources:</span>
271
+ <span class="value">"your-org/your-repo"</span>: [<span class="value">docs</span>]
272
+ <span class="key">path_triggers:</span>
273
+ <span class="key">docs:</span> [<span class="value">"docs/"</span>]</div>
274
+ <p>Then add a GitHub webhook pointing to <code>https://your-server/webhooks/github</code> with the push event.</p>
275
+ </div>
276
+ </div>
277
+
278
+ <h2>What You Gain</h2>
279
+ <div class="callout-grid">
280
+ <div class="callout-card">
281
+ <div class="icon">🧭</div>
282
+ <h4>Session State</h4>
283
+ <p>Agents <code>cd</code> into directories and stay there across commands. No more repeating full paths every tool call.</p>
284
+ </div>
285
+ <div class="callout-card">
286
+ <div class="icon">⚡</div>
287
+ <h4>Vector Grep</h4>
288
+ <p>When <code>grep</code> misses, semantic search fills the gaps. Three-pass deduplication gives clean results.</p>
289
+ </div>
290
+ <div class="callout-card">
291
+ <div class="icon">📝</div>
292
+ <h4>Writable Workspace</h4>
293
+ <p>Agents save notes, grep results, and intermediate files to <code>/workspace/</code> during a session.</p>
294
+ </div>
295
+ <div class="callout-card">
296
+ <div class="icon">🔗</div>
297
+ <h4>Cross-Source Related</h4>
298
+ <p>Run <code>related /docs/auth.mdx</code> to discover semantically similar files across all sources.</p>
299
+ </div>
300
+ <div class="callout-card">
301
+ <div class="icon">📊</div>
302
+ <h4>Feedback Collection</h4>
303
+ <p>Define collect tools with YAML schemas. Agents report search quality, broken links, or anything you define.</p>
304
+ </div>
305
+ <div class="callout-card">
306
+ <div class="icon">🚀</div>
307
+ <h4>Zero-Infra Start</h4>
308
+ <p>Bash-only mode needs no database or API keys. Add RAG later with a config change — no code edits.</p>
309
+ </div>
310
+ </div>
311
+
312
+ <h2>What's Different</h2>
313
+ <p>Pathfinder is not a drop-in replacement for Mintlify's full platform. Here's what it doesn't do:</p>
314
+
315
+ <div class="gap-card">
316
+ <h4>No hosted docs site</h4>
317
+ <p>Pathfinder is an MCP server, not a documentation hosting platform. Your rendered docs site (if you need one) stays wherever it is — Mintlify, Docusaurus, GitBook, etc.</p>
318
+ </div>
319
+ <div class="gap-card">
320
+ <h4>No built-in UI</h4>
321
+ <p>There's no web dashboard for browsing search results or managing content. Pathfinder is designed for agent consumption via MCP, not human browsing.</p>
322
+ </div>
323
+ <div class="gap-card">
324
+ <h4>Self-hosted only</h4>
325
+ <p>You run the infrastructure. Docker Compose makes this straightforward, but there's no managed cloud offering (yet). You need PostgreSQL and optionally an OpenAI API key.</p>
326
+ </div>
327
+ <div class="gap-card">
328
+ <h4>No analytics dashboard</h4>
329
+ <p>Telemetry data (file access patterns, grep misses) goes to the database but there's no built-in visualization. Query it directly or build your own dashboard.</p>
330
+ </div>
331
+
332
+ <a href="index.html" class="back-link">&larr; Back to Pathfinder</a>
333
+ </article>
334
+
335
+ <footer>
336
+ <p>Pathfinder is MIT Licensed &middot; <a href="https://github.com/CopilotKit/pathfinder">GitHub</a> &middot; <a href="index.html">Home</a> &middot; Built by <a href="https://copilotkit.ai">CopilotKit</a></p>
337
+ </footer>
338
+
339
+ </body>
340
+ </html>
package/.superpowers/brainstorm/82141-1775511032/state/server-stopped ADDED
@@ -0,0 +1 @@
1
+ {"reason":"idle timeout","timestamp":1775513132891}
package/.superpowers/brainstorm/82141-1775511032/state/server.log ADDED
@@ -0,0 +1,4 @@
1
+ {"type":"server-started","port":58651,"host":"127.0.0.1","url_host":"localhost","url":"http://localhost:58651","screen_dir":"/proj/cpk/mcp-docs/.superpowers/brainstorm/82141-1775511032/content","state_dir":"/proj/cpk/mcp-docs/.superpowers/brainstorm/82141-1775511032/state"}
2
+ {"type":"screen-added","file":"/proj/cpk/mcp-docs/.superpowers/brainstorm/82141-1775511032/content/migration.html"}
3
+ {"type":"screen-added","file":"/proj/cpk/mcp-docs/.superpowers/brainstorm/82141-1775511032/content/migration-v2.html"}
4
+ {"type":"server-stopped","reason":"idle timeout"}
package/CHANGELOG.md ADDED
@@ -0,0 +1,26 @@
1
+ # Changelog
2
+
3
+ ## 1.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Rename project from mcp-docs to Pathfinder
8
+ - Add agentic retrieval: session state, vector grep, virtual files, related command, telemetry
9
+ - Add configurable bash tool options (grep_strategy, workspace, virtual_files)
10
+ - Add Pathfinder landing page and documentation site
11
+ - Add Mintlify migration tutorial
12
+ - Add GitHub Actions for Pages deployment, releases, and Docker publishing
13
+ - Add versioning infrastructure with CHANGELOG
14
+
15
+ ## 1.0.0
16
+
17
+ ### Initial Release
18
+
19
+ - Semantic search over documentation and code via pgvector + OpenAI embeddings
20
+ - Bash tool filesystem exploration via just-bash virtual filesystem
21
+ - Feedback collection tools with YAML-defined schemas
22
+ - Config-driven via pathfinder.yaml
23
+ - Webhook-triggered reindexing from GitHub push events
24
+ - Nightly auto-reindex on configurable schedule
25
+ - Docker deployment support
26
+ - MIT License
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CopilotKit, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.