Atlas foundation: codebase-knowledge layer in Pathfinder (off-by-default)

package.json

@@ -29,13 +29,15 @@
   },
   "main": "dist/index.js",
   "bin": {
+    "atlas": "dist/atlas-cli.js",
     "pathfinder": "dist/cli.js"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc",
+    "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
     "dev": "tsx watch src/index.ts",
     "seed-index": "tsx scripts/seed-index.ts",

pathfinder.example.yaml

@@ -86,6 +86,19 @@ sources:
 #      target_tokens: 600
 #      overlap_tokens: 50
 
+# ── Atlas source (agent-facing codebase knowledge cache) ──
+# Seed knowledge is durable; generated Atlas pages are disposable Pathfinder cache.
+#  - name: atlas
+#    type: atlas
+#    seed_path: .pathfinder/atlas/seed
+#    cache_namespace: my-project
+#    repositories:
+#      - repo_url: https://github.com/your-org/your-repo.git
+#        refs: ["main"]
+#    chunk:
+#      target_tokens: 800
+#      overlap_tokens: 80
+
 # ── Slack source (requires SLACK_BOT_TOKEN + OPENAI_API_KEY) ──
 #  - name: community
 #    type: slack
@@ -121,6 +134,16 @@ tools:
   #    description: "Browse and search community Q&A"
   #    sources: [community]
 
+  # ── Atlas search tool ──
+  #  - name: atlas-search
+  #    type: search
+  #    description: "Search Atlas codebase knowledge."
+  #    source: atlas
+  #    default_limit: 5
+  #    max_limit: 20
+  #    result_format: raw
+  #    search_mode: hybrid
+
 # Required for search tools (omit for bash-only mode)
 embedding:
   provider: openai

src/__tests__/analytics-endpoints.test.ts

@@ -113,6 +113,25 @@ describe("analyticsAuth middleware", () => {
     expect(next).not.toHaveBeenCalled();
   });
 
+  it("returns 503 when root config read fails before auth options are built", () => {
+    mockGetConfigFn.mockImplementation(() => {
+      throw new Error("bad root config");
+    });
+    const res = mockRes();
+    const next = vi.fn();
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    analyticsAuth({ headers: {} } as never, res as never, next);
+
+    expect(res.status).toHaveBeenCalledWith(503);
+    expect(res.json).toHaveBeenCalledWith({
+      error: "misconfigured",
+      error_description: "Analytics config read failed",
+    });
+    expect(next).not.toHaveBeenCalled();
+    consoleSpy.mockRestore();
+  });
+
   it("auto-generates token, logs only a fingerprint, and requires auth", () => {
     mockGetAnalyticsConfigFn.mockReturnValue({
       enabled: true,