@karmaniverous/jeeves-server 3.0.0-0

package/dist/src/util/formatters.test.js

@@ -0,0 +1,83 @@
+/**
+ * Tests for formatting utilities
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { formatRelativeTime, formatSize, nowIso } from './formatters.js';
+describe('formatters', () => {
+    describe('formatSize', () => {
+        it('should format 0 bytes', () => {
+            expect(formatSize(0)).toBe('0 B');
+        });
+        it('should format bytes', () => {
+            expect(formatSize(500)).toBe('500 B');
+            expect(formatSize(1023)).toBe('1023 B');
+        });
+        it('should format kilobytes', () => {
+            expect(formatSize(1024)).toBe('1.0 KB');
+            expect(formatSize(1536)).toBe('1.5 KB');
+            expect(formatSize(10240)).toBe('10.0 KB');
+        });
+        it('should format megabytes', () => {
+            expect(formatSize(1048576)).toBe('1.0 MB');
+            expect(formatSize(1572864)).toBe('1.5 MB');
+        });
+        it('should format gigabytes', () => {
+            expect(formatSize(1073741824)).toBe('1.0 GB');
+            expect(formatSize(2147483648)).toBe('2.0 GB');
+        });
+        it('should format terabytes', () => {
+            expect(formatSize(1099511627776)).toBe('1.0 TB');
+        });
+    });
+    describe('formatRelativeTime', () => {
+        beforeEach(() => {
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date('2026-02-15T12:00:00Z'));
+        });
+        it('should return null for null input', () => {
+            expect(formatRelativeTime(null)).toBeNull();
+        });
+        it('should return null for future timestamps', () => {
+            const future = new Date('2026-02-15T13:00:00Z').toISOString();
+            expect(formatRelativeTime(future)).toBeNull();
+        });
+        it('should return "just now" for very recent timestamps', () => {
+            const recent = new Date('2026-02-15T11:59:30Z').toISOString();
+            expect(formatRelativeTime(recent)).toBe('just now');
+        });
+        it('should return minutes ago', () => {
+            const mins5 = new Date('2026-02-15T11:55:00Z').toISOString();
+            expect(formatRelativeTime(mins5)).toBe('5m ago');
+            const mins45 = new Date('2026-02-15T11:15:00Z').toISOString();
+            expect(formatRelativeTime(mins45)).toBe('45m ago');
+        });
+        it('should return hours ago', () => {
+            const hours2 = new Date('2026-02-15T10:00:00Z').toISOString();
+            expect(formatRelativeTime(hours2)).toBe('2h ago');
+            const hours12 = new Date('2026-02-15T00:00:00Z').toISOString();
+            expect(formatRelativeTime(hours12)).toBe('12h ago');
+        });
+        it('should return days ago', () => {
+            const days1 = new Date('2026-02-14T12:00:00Z').toISOString();
+            expect(formatRelativeTime(days1)).toBe('1d ago');
+            const days7 = new Date('2026-02-08T12:00:00Z').toISOString();
+            expect(formatRelativeTime(days7)).toBe('7d ago');
+        });
+        it('should prioritize days over hours', () => {
+            const days1Hours5 = new Date('2026-02-14T07:00:00Z').toISOString();
+            expect(formatRelativeTime(days1Hours5)).toBe('1d ago');
+        });
+    });
+    describe('nowIso', () => {
+        beforeEach(() => {
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date('2026-02-15T12:34:56.789Z'));
+        });
+        it('should return current time in ISO format', () => {
+            expect(nowIso()).toBe('2026-02-15T12:34:56.789Z');
+        });
+        it('should match ISO 8601 format', () => {
+            expect(nowIso()).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+        });
+    });
+});

package/dist/src/util/packageVersion.js

@@ -0,0 +1,25 @@
+/**
+ * Resolve the service package version by walking up from the caller's directory.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function findPackageJson(startDir) {
+    let dir = startDir;
+    while (dir !== path.dirname(dir)) {
+        const candidate = path.join(dir, 'package.json');
+        if (fs.existsSync(candidate)) {
+            const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            // Find our package specifically, not the monorepo root
+            if (pkg.name === '@karmaniverous/jeeves-server')
+                return candidate;
+        }
+        dir = path.dirname(dir);
+    }
+    throw new Error('Could not find @karmaniverous/jeeves-server package.json');
+}
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgPath = findPackageJson(__dirname);
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+/** The package version of the jeeves-server service package. */
+export const packageVersion = pkg.version;

package/dist/src/util/platform.js

@@ -0,0 +1,148 @@
+/**
+ * Platform abstraction for filesystem operations.
+ *
+ * Handles the differences between Windows (drive letters, backslashes)
+ * and Linux (mount points, forward slashes) for URL path ↔ filesystem path conversion.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const IS_WINDOWS = process.platform === 'win32';
+/**
+ * Discover available filesystem roots.
+ * Windows: enumerate accessible drive letters.
+ * Linux: return configured roots or default to '/'.
+ */
+export function getRoots(configuredRoots) {
+    if (IS_WINDOWS) {
+        const roots = [];
+        for (let code = 65; code <= 90; code++) {
+            const letter = String.fromCharCode(code);
+            const drivePath = `${letter}:\\`;
+            try {
+                fs.accessSync(drivePath, fs.constants.R_OK);
+                roots.push({
+                    id: letter.toLowerCase(),
+                    label: `${letter}:`,
+                    fsPath: drivePath,
+                });
+            }
+            catch {
+                // Drive not accessible
+            }
+        }
+        return roots;
+    }
+    // Linux: use configured roots or default to filesystem root
+    if (configuredRoots && Object.keys(configuredRoots).length > 0) {
+        return Object.entries(configuredRoots).map(([id, fsPath]) => ({
+            id,
+            label: fsPath,
+            fsPath: fsPath.endsWith('/') ? fsPath : fsPath + '/',
+        }));
+    }
+    return [{ id: 'root', label: '/', fsPath: '/' }];
+}
+/**
+ * Convert a URL path to a filesystem path.
+ *
+ * URL paths use forward slashes and start with the root id:
+ *   Windows: /e/jeeves-server/README.md → E:\\jeeves-server\\README.md
+ *   Linux:   /home/user/docs/README.md → /home/user/docs/README.md
+ *            /root/docs/README.md       → /docs/README.md (if root id is "root" mapping to "/")
+ */
+export function urlPathToFs(urlPath, roots) {
+    const normalized = urlPath.replace(/^\/+/, '');
+    if (!normalized)
+        return null;
+    if (IS_WINDOWS) {
+        // First segment is the drive letter
+        const slashIdx = normalized.indexOf('/');
+        const driveLetter = slashIdx >= 0 ? normalized.substring(0, slashIdx) : normalized;
+        const rest = slashIdx >= 0 ? normalized.substring(slashIdx + 1) : '';
+        if (driveLetter.length !== 1)
+            return null;
+        const fsPath = `${driveLetter.toUpperCase()}:\\${rest.replace(/\//g, '\\')}`;
+        return fsPath;
+    }
+    // Linux: match against configured roots
+    for (const root of roots) {
+        if (normalized.startsWith(root.id + '/') || normalized === root.id) {
+            const rest = normalized.substring(root.id.length);
+            // rest starts with '/' or is empty
+            const fsPath = root.fsPath.replace(/\/+$/, '') + (rest || '/');
+            return fsPath;
+        }
+    }
+    return null;
+}
+/**
+ * Convert a filesystem path to a URL path.
+ *
+ * Windows: E:\\jeeves-server\\README.md → /e/jeeves-server/README.md
+ * Linux:   /home/user/docs/README.md → /home/user/docs/README.md (root="root" → "/")
+ */
+export function fsPathToUrl(fsPath, roots) {
+    if (IS_WINDOWS) {
+        return ('/' +
+            fsPath
+                .replace(/\\/g, '/')
+                .replace(/^([A-Za-z]):/, (_, d) => d.toLowerCase()));
+    }
+    // Linux: find the matching root and prepend the root id
+    for (const root of roots) {
+        const rootFs = root.fsPath.replace(/\/+$/, '');
+        if (fsPath === rootFs || fsPath.startsWith(rootFs + '/')) {
+            const rest = fsPath.substring(rootFs.length); // starts with '/' or is empty
+            if (root.id === 'root' && root.fsPath === '/') {
+                // Default root — URL path is just the fs path
+                return rest || '/';
+            }
+            return '/' + root.id + rest;
+        }
+    }
+    // Fallback: return as-is with forward slashes
+    return fsPath.replace(/\\/g, '/');
+}
+/**
+ * Split a filesystem path into breadcrumb parts.
+ * Returns [\{label, urlPath\}] from root to leaf.
+ */
+export function breadcrumbParts(fsPath, roots) {
+    const urlPath = fsPathToUrl(fsPath, roots);
+    const parts = urlPath
+        .replace(/^\/+/, '')
+        .split('/')
+        .filter((p) => p);
+    return parts.map((_part, i) => {
+        const accumulated = parts.slice(0, i + 1).join('/');
+        return { label: parts[i], path: accumulated };
+    });
+}
+/**
+ * Recursively calculate total size of a directory in bytes.
+ */
+export function getDirSize(dirPath) {
+    let totalSize = 0;
+    try {
+        const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = path.join(dirPath, entry.name);
+            try {
+                if (entry.isDirectory()) {
+                    totalSize += getDirSize(entryPath);
+                }
+                else {
+                    const s = fs.statSync(entryPath);
+                    totalSize += s.size;
+                }
+            }
+            catch {
+                /* skip inaccessible */
+            }
+        }
+    }
+    catch {
+        /* skip inaccessible */
+    }
+    return totalSize;
+}

package/dist/src/util/state.js

@@ -0,0 +1,46 @@
+/**
+ * Server state management (key rotation tracking, etc.)
+ */
+import fs from 'node:fs';
+import { getConfig } from '../config/index.js';
+/**
+ * Load state from file
+ */
+export function loadState() {
+    const { stateFile } = getConfig();
+    try {
+        if (fs.existsSync(stateFile)) {
+            const content = fs.readFileSync(stateFile, 'utf8');
+            return JSON.parse(content);
+        }
+    }
+    catch {
+        // Ignore errors, return empty state
+    }
+    return {};
+}
+/**
+ * Save state to file
+ */
+export function saveState(state) {
+    const { stateFile } = getConfig();
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+}
+/**
+ * Set key rotation timestamp
+ */
+export function setKeyRotationTimestamp(timestamp) {
+    const state = loadState();
+    state.keyRotatedAt = timestamp;
+    saveState(state);
+}
+/**
+ * Set an insider's auto-generated key in state
+ */
+export function setInsiderKey(email, seed, createdAt) {
+    const state = loadState();
+    if (!state.insiderKeys)
+        state.insiderKeys = {};
+    state.insiderKeys[email.toLowerCase()] = { seed, createdAt };
+    saveState(state);
+}

package/dist/vitest.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'happy-dom',
+        exclude: ['dist/**', '**/node_modules/**'],
+        coverage: {
+            provider: 'v8',
+            reporter: ['text', 'lcov'],
+        },
+    },
+});

package/favicon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <text y="0.9em" font-size="90">🎩</text>
+</svg>

package/guides/access-decision-flow.mmd

@@ -0,0 +1,24 @@
+flowchart TD
+    A["Request arrives"] --> B{"Has session cookie?\n(Google OAuth)"}
+    B -- Yes --> C{"Email in\ninsiders map?"}
+    C -- Yes --> D["✅ INSIDER access\n(within scopes)"]
+    C -- No --> E["❌ DENIED"]
+
+    B -- No --> F{"Has ?key=\nparameter?"}
+    F -- Yes --> G{"Matches machine\ninsider key?"}
+    G -- Yes --> H["✅ INSIDER access\n(within scopes)"]
+    G -- No --> I{"Matches outsider key?\n(machine or insider seed)"}
+    I -- Yes --> J{"Path matches key\npath or ancestor?"}
+    J -- Yes --> K["✅ OUTSIDER access"]
+    J -- No --> L["❌ DENIED"]
+    I -- No --> M["❌ DENIED"]
+
+    F -- No --> N["❌ DENIED\n(or redirect to Google login)"]
+
+    style D fill:#22c55e,color:#fff,stroke:#16a34a
+    style H fill:#22c55e,color:#fff,stroke:#16a34a
+    style K fill:#22c55e,color:#fff,stroke:#16a34a
+    style E fill:#ef4444,color:#fff,stroke:#dc2626
+    style L fill:#ef4444,color:#fff,stroke:#dc2626
+    style M fill:#ef4444,color:#fff,stroke:#dc2626
+    style N fill:#f59e0b,color:#fff,stroke:#d97706

package/guides/access-decision-flow.svg

@@ -0,0 +1 @@
+<svg id="my-svg" width="100%" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" class="flowchart" style="max-width: 1102.22px; background-color: white;" viewBox="0 0 1102.21875 1878.078125" role="graphics-document document" aria-roledescription="flowchart-v2"><style>#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#my-svg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#my-svg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#333333;stroke:#333333;}#my-svg .marker.cross{stroke:#333333;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#my-svg .cluster-label text{fill:#333;}#my-svg .cluster-label span{color:#333;}#my-svg .cluster-label span p{background-color:transparent;}#my-svg .label text,#my-svg span{fill:#333;color:#333;}#my-svg .node rect,#my-svg .node circle,#my-svg .node ellipse,#my-svg .node polygon,#my-svg .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#my-svg .rough-node .label text,#my-svg .node .label text,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-anchor:middle;}#my-svg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#my-svg .rough-node .label,#my-svg .node .label,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-align:center;}#my-svg .node.clickable{cursor:pointer;}#my-svg .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#my-svg .arrowheadPath{fill:#333333;}#my-svg .edgePath .path{stroke:#333333;stroke-width:2.0px;}#my-svg .flowchart-link{stroke:#333333;fill:none;}#my-svg .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#my-svg .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#my-svg .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#my-svg .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#my-svg .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#my-svg .cluster text{fill:#333;}#my-svg .cluster span{color:#333;}#my-svg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#my-svg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#my-svg rect.text{fill:none;stroke-width:0;}#my-svg .icon-shape,#my-svg .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#my-svg .icon-shape p,#my-svg .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#my-svg .icon-shape rect,#my-svg .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#my-svg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#my-svg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}</style><g><marker id="my-svg_flowchart-v2-pointEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-pointStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="4.5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 5 L 10 10 L 10 0 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-circleEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="11" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-circleStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-1" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-crossEnd" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="12" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-crossStart" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="-1" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"/></marker><g class="root"><g class="clusters"/><g class="edgePaths"><path d="M551.109,62L551.109,66.167C551.109,70.333,551.109,78.667,551.109,86.333C551.109,94,551.109,101,551.109,104.5L551.109,108" id="L_A_B_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_A_B_0" data-points="W3sieCI6NTUxLjEwOTM3NSwieSI6NjJ9LHsieCI6NTUxLjEwOTM3NSwieSI6ODd9LHsieCI6NTUxLjEwOTM3NSwieSI6MTEyfV0=" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M464.771,303.661L431.068,324.218C397.365,344.774,329.96,385.887,296.257,411.944C262.555,438,262.555,449,262.555,454.5L262.555,460" id="L_B_C_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_B_C_0" data-points="W3sieCI6NDY0Ljc3MDU1OTI2NTg0NiwieSI6MzAzLjY2MTE4NDI2NTg0Nn0seyJ4IjoyNjIuNTU0Njg3NSwieSI6NDI3fSx7IngiOjI2Mi41NTQ2ODc1LCJ5Ijo0NjR9XQ==" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M211.818,635.342L199.515,649.964C187.212,664.587,162.606,693.833,150.303,730.622C138,767.411,138,811.745,138,833.911L138,856.078" id="L_C_D_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_C_D_0" data-points="W3sieCI6MjExLjgxODI1MDEwOTI2NTczLCJ5Ijo2MzUuMzQxNjg3NjA5MjY1N30seyJ4IjoxMzgsInkiOjcyMy4wNzgxMjV9LHsieCI6MTM4LCJ5Ijo4NjAuMDc4MTI1fV0=" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M313.291,635.342L325.594,649.964C337.897,664.587,362.503,693.833,374.806,732.622C387.109,771.411,387.109,819.745,387.109,843.911L387.109,868.078" id="L_C_E_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_C_E_0" data-points="W3sieCI6MzEzLjI5MTEyNDg5MDczNDI0LCJ5Ijo2MzUuMzQxNjg3NjA5MjY1N30seyJ4IjozODcuMTA5Mzc1LCJ5Ijo3MjMuMDc4MTI1fSx7IngiOjM4Ny4xMDkzNzUsInkiOjg3Mi4wNzgxMjV9XQ==" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M633.165,307.945L661.757,327.787C690.349,347.63,747.534,387.315,776.126,412.941C804.719,438.568,804.719,450.135,804.719,455.919L804.719,461.703" id="L_B_F_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_B_F_0" data-points="W3sieCI6NjMzLjE2NDYyMTQwODQzNzksInkiOjMwNy45NDQ3NTM1OTE1NjIxfSx7IngiOjgwNC43MTg3NSwieSI6NDI3fSx7IngiOjgwNC43MTg3NSwieSI6NDY1LjcwMzEyNX1d" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M748.013,627.67L730.881,643.571C713.749,659.473,679.484,691.275,662.351,712.677C645.219,734.078,645.219,745.078,645.219,750.578L645.219,756.078" id="L_F_G_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_F_G_0" data-points="W3sieCI6NzQ4LjAxMzQ5MTUyMTY1NjMsInkiOjYyNy42Njk3NDE1MjE2NTYzfSx7IngiOjY0NS4yMTg3NSwieSI6NzIzLjA3ODEyNX0seyJ4Ijo2NDUuMjE4NzUsInkiOjc2MC4wNzgxMjV9XQ==" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M579.137,971.996L563.567,989.176C547.997,1006.357,516.858,1040.717,501.288,1080.064C485.719,1119.411,485.719,1163.745,485.719,1185.911L485.719,1208.078" id="L_G_H_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_G_H_0" data-points="W3sieCI6NTc5LjEzNjc4Mjc4Njg4NTIsInkiOjk3MS45OTYxNTc3ODY4ODUyfSx7IngiOjQ4NS43MTg3NSwieSI6MTA3NS4wNzgxMjV9LHsieCI6NDg1LjcxODc1LCJ5IjoxMjEyLjA3ODEyNX1d" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M711.301,971.996L726.87,989.176C742.44,1006.357,773.579,1040.717,789.149,1063.398C804.719,1086.078,804.719,1097.078,804.719,1102.578L804.719,1108.078" id="L_G_I_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_G_I_0" data-points="W3sieCI6NzExLjMwMDcxNzIxMzExNDgsInkiOjk3MS45OTYxNTc3ODY4ODUyfSx7IngiOjgwNC43MTg3NSwieSI6MTA3NS4wNzgxMjV9LHsieCI6ODA0LjcxODc1LCJ5IjoxMTEyLjA3ODEyNX1d" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M745.914,1331.274L734.206,1347.241C722.497,1363.208,699.081,1395.143,687.372,1416.611C675.664,1438.078,675.664,1449.078,675.664,1454.578L675.664,1460.078" id="L_I_J_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_I_J_0" data-points="W3sieCI6NzQ1LjkxNDIwNjc1NzI0MTIsInkiOjEzMzEuMjczNTgxNzU3MjQxM30seyJ4Ijo2NzUuNjY0MDYyNSwieSI6MTQyNy4wNzgxMjV9LHsieCI6Njc1LjY2NDA2MjUsInkiOjE0NjQuMDc4MTI1fV0=" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M621.753,1688.167L612.153,1703.319C602.553,1718.471,583.352,1748.774,573.752,1769.426C564.152,1790.078,564.152,1801.078,564.152,1806.578L564.152,1812.078" id="L_J_K_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_J_K_0" data-points="W3sieCI6NjIxLjc1Mjc2ODEyMzQxMjEsInkiOjE2ODguMTY2ODMwNjIzNDEyMX0seyJ4Ijo1NjQuMTUyMzQzNzUsInkiOjE3NzkuMDc4MTI1fSx7IngiOjU2NC4xNTIzNDM3NSwieSI6MTgxNi4wNzgxMjV9XQ==" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M729.575,1688.167L739.175,1703.319C748.775,1718.471,767.976,1748.774,777.576,1769.426C787.176,1790.078,787.176,1801.078,787.176,1806.578L787.176,1812.078" id="L_J_L_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_J_L_0" data-points="W3sieCI6NzI5LjU3NTM1Njg3NjU4NzksInkiOjE2ODguMTY2ODMwNjIzNDEyMX0seyJ4Ijo3ODcuMTc1NzgxMjUsInkiOjE3NzkuMDc4MTI1fSx7IngiOjc4Ny4xNzU3ODEyNSwieSI6MTgxNi4wNzgxMjV9XQ==" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M863.523,1331.274L875.232,1347.241C886.94,1363.208,910.357,1395.143,922.065,1435.277C933.773,1475.411,933.773,1523.745,933.773,1547.911L933.773,1572.078" id="L_I_M_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_I_M_0" data-points="W3sieCI6ODYzLjUyMzI5MzI0Mjc1ODgsInkiOjEzMzEuMjczNTgxNzU3MjQxM30seyJ4Ijo5MzMuNzczNDM3NSwieSI6MTQyNy4wNzgxMjV9LHsieCI6OTMzLjc3MzQzNzUsInkiOjE1NzYuMDc4MTI1fV0=" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M861.424,627.67L878.556,643.571C895.689,659.473,929.954,691.275,947.086,729.343C964.219,767.411,964.219,811.745,964.219,833.911L964.219,856.078" id="L_F_N_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_F_N_0" data-points="W3sieCI6ODYxLjQyNDAwODQ3ODM0MzcsInkiOjYyNy42Njk3NDE1MjE2NTYzfSx7IngiOjk2NC4yMTg3NSwieSI6NzIzLjA3ODEyNX0seyJ4Ijo5NjQuMjE4NzUsInkiOjg2MC4wNzgxMjV9XQ==" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/></g><g class="edgeLabels"><g class="edgeLabel"><g class="label" data-id="L_A_B_0" transform="translate(0, 0)"><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(262.5546875, 427)"><g class="label" data-id="L_B_C_0" transform="translate(-11.328125, -12)"><foreignObject width="22.65625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>Yes</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(138, 723.078125)"><g class="label" data-id="L_C_D_0" transform="translate(-11.328125, -12)"><foreignObject width="22.65625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>Yes</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(387.109375, 723.078125)"><g class="label" data-id="L_C_E_0" transform="translate(-9.3984375, -12)"><foreignObject width="18.796875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>No</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(804.71875, 427)"><g class="label" data-id="L_B_F_0" transform="translate(-9.3984375, -12)"><foreignObject width="18.796875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>No</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(645.21875, 723.078125)"><g class="label" data-id="L_F_G_0" transform="translate(-11.328125, -12)"><foreignObject width="22.65625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>Yes</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(485.71875, 1075.078125)"><g class="label" data-id="L_G_H_0" transform="translate(-11.328125, -12)"><foreignObject width="22.65625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>Yes</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(804.71875, 1075.078125)"><g class="label" data-id="L_G_I_0" transform="translate(-9.3984375, -12)"><foreignObject width="18.796875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>No</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(675.6640625, 1427.078125)"><g class="label" data-id="L_I_J_0" transform="translate(-11.328125, -12)"><foreignObject width="22.65625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>Yes</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(564.15234375, 1779.078125)"><g class="label" data-id="L_J_K_0" transform="translate(-11.328125, -12)"><foreignObject width="22.65625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>Yes</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(787.17578125, 1779.078125)"><g class="label" data-id="L_J_L_0" transform="translate(-9.3984375, -12)"><foreignObject width="18.796875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>No</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(933.7734375, 1427.078125)"><g class="label" data-id="L_I_M_0" transform="translate(-9.3984375, -12)"><foreignObject width="18.796875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>No</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(964.21875, 723.078125)"><g class="label" data-id="L_F_N_0" transform="translate(-9.3984375, -12)"><foreignObject width="18.796875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>No</p></span></div></foreignObject></g></g></g><g class="nodes"><g class="node default" id="flowchart-A-0" transform="translate(551.109375, 35)"><rect class="basic label-container" style="" x="-84.9296875" y="-27" width="169.859375" height="54"/><g class="label" style="" transform="translate(-54.9296875, -12)"><rect/><foreignObject width="109.859375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="nodeLabel"><p>Request arrives</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-B-1" transform="translate(551.109375, 251)"><polygon points="139,0 278,-139 139,-278 0,-139" class="label-container" transform="translate(-138.5, 139)"/><g class="label" style="" transform="translate(-100, -24)"><rect/><foreignObject width="200" height="48"><div xmlns="http://www.w3.org/1999/xhtml" style="display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;"><span class="nodeLabel"><p>Has session cookie?\n(Google OAuth)</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-C-3" transform="translate(262.5546875, 575.0390625)"><polygon points="111.0390625,0 222.078125,-111.0390625 111.0390625,-222.078125 0,-111.0390625" class="label-container" transform="translate(-110.5390625, 111.0390625)"/><g class="label" style="" transform="translate(-84.0390625, -12)"><rect/><foreignObject width="168.078125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="nodeLabel"><p>Email in\ninsiders map?</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-D-5" transform="translate(138, 899.078125)"><rect class="basic label-container" style="fill:#22c55e !important;stroke:#16a34a !important" x="-130" y="-39" width="260" height="78"/><g class="label" style="color:#fff !important" transform="translate(-100, -24)"><rect/><foreignObject width="200" height="48"><div style="color: rgb(255, 255, 255) !important; display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#fff !important" class="nodeLabel"><p>✅ INSIDER access\n(within scopes)</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-E-7" transform="translate(387.109375, 899.078125)"><rect class="basic label-container" style="fill:#ef4444 !important;stroke:#dc2626 !important" x="-69.109375" y="-27" width="138.21875" height="54"/><g class="label" style="color:#fff !important" transform="translate(-39.109375, -12)"><rect/><foreignObject width="78.21875" height="24"><div style="color: rgb(255, 255, 255) !important; display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#fff !important" class="nodeLabel"><p>❌ DENIED</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-F-9" transform="translate(804.71875, 575.0390625)"><polygon points="109.3359375,0 218.671875,-109.3359375 109.3359375,-218.671875 0,-109.3359375" class="label-container" transform="translate(-108.8359375, 109.3359375)"/><g class="label" style="" transform="translate(-82.3359375, -12)"><rect/><foreignObject width="164.671875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="nodeLabel"><p>Has ?key=\nparameter?</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-G-11" transform="translate(645.21875, 899.078125)"><polygon points="139,0 278,-139 139,-278 0,-139" class="label-container" transform="translate(-138.5, 139)"/><g class="label" style="" transform="translate(-100, -24)"><rect/><foreignObject width="200" height="48"><div xmlns="http://www.w3.org/1999/xhtml" style="display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;"><span class="nodeLabel"><p>Matches machine\ninsider key?</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-H-13" transform="translate(485.71875, 1251.078125)"><rect class="basic label-container" style="fill:#22c55e !important;stroke:#16a34a !important" x="-130" y="-39" width="260" height="78"/><g class="label" style="color:#fff !important" transform="translate(-100, -24)"><rect/><foreignObject width="200" height="48"><div style="color: rgb(255, 255, 255) !important; display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#fff !important" class="nodeLabel"><p>✅ INSIDER access\n(within scopes)</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-I-15" transform="translate(804.71875, 1251.078125)"><polygon points="139,0 278,-139 139,-278 0,-139" class="label-container" transform="translate(-138.5, 139)"/><g class="label" style="" transform="translate(-100, -24)"><rect/><foreignObject width="200" height="48"><div xmlns="http://www.w3.org/1999/xhtml" style="display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;"><span class="nodeLabel"><p>Matches outsider key?\n(machine or insider seed)</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-J-17" transform="translate(675.6640625, 1603.078125)"><polygon points="139,0 278,-139 139,-278 0,-139" class="label-container" transform="translate(-138.5, 139)"/><g class="label" style="" transform="translate(-100, -24)"><rect/><foreignObject width="200" height="48"><div xmlns="http://www.w3.org/1999/xhtml" style="display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;"><span class="nodeLabel"><p>Path matches key\npath or ancestor?</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-K-19" transform="translate(564.15234375, 1843.078125)"><rect class="basic label-container" style="fill:#22c55e !important;stroke:#16a34a !important" x="-103.9140625" y="-27" width="207.828125" height="54"/><g class="label" style="color:#fff !important" transform="translate(-73.9140625, -12)"><rect/><foreignObject width="147.828125" height="24"><div style="color: rgb(255, 255, 255) !important; display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#fff !important" class="nodeLabel"><p>✅ OUTSIDER access</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-L-21" transform="translate(787.17578125, 1843.078125)"><rect class="basic label-container" style="fill:#ef4444 !important;stroke:#dc2626 !important" x="-69.109375" y="-27" width="138.21875" height="54"/><g class="label" style="color:#fff !important" transform="translate(-39.109375, -12)"><rect/><foreignObject width="78.21875" height="24"><div style="color: rgb(255, 255, 255) !important; display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#fff !important" class="nodeLabel"><p>❌ DENIED</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-M-23" transform="translate(933.7734375, 1603.078125)"><rect class="basic label-container" style="fill:#ef4444 !important;stroke:#dc2626 !important" x="-69.109375" y="-27" width="138.21875" height="54"/><g class="label" style="color:#fff !important" transform="translate(-39.109375, -12)"><rect/><foreignObject width="78.21875" height="24"><div style="color: rgb(255, 255, 255) !important; display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#fff !important" class="nodeLabel"><p>❌ DENIED</p></span></div></foreignObject></g></g><g class="node default" id="flowchart-N-25" transform="translate(964.21875, 899.078125)"><rect class="basic label-container" style="fill:#f59e0b !important;stroke:#d97706 !important" x="-130" y="-39" width="260" height="78"/><g class="label" style="color:#fff !important" transform="translate(-100, -24)"><rect/><foreignObject width="200" height="48"><div style="color: rgb(255, 255, 255) !important; display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#fff !important" class="nodeLabel"><p>❌ DENIED\n(or redirect to Google login)</p></span></div></foreignObject></g></g></g></g></g></svg>

package/guides/api-integration.md

@@ -0,0 +1,236 @@
+# API & Integration Guide
+
+How to interact with Jeeves Server programmatically — for scripts, bots, AI assistants, and CI/CD pipelines.
+
+## Authentication for API Access
+
+All API requests authenticate via `?key=<insider-key>` URL parameter or session cookie. For programmatic access, use a key:
+
+```typescript
+// In jeeves.config.ts
+keys: {
+  'ci-bot': 'random-seed-string',
+  // Scoped key for webhooks only:
+  'webhook': { key: 'another-seed', scopes: ['/event'] },
+},
+```
+
+### Getting the derived key
+
+The config contains **seeds**. The actual URL key is derived via HMAC:
+
+```bash
+# Get the insider key from a seed
+curl -s "http://localhost:1934/insider-key" -H "X-API-Key: <seed>"
+# Returns: { "key": "a1b2c3d4..." }
+```
+
+Or compute it yourself:
+
+```javascript
+const crypto = require('crypto');
+function insiderKey(seed) {
+  return crypto.createHmac('sha256', seed).update('insider').digest('hex').substring(0, 32);
+}
+```
+
+## API Endpoints
+
+### File Access
+
+```bash
+# Get file content (rendered)
+GET /api/file/d/docs/design.md?key=<key>
+# Returns: { type: "markdown", html: "...", headings: [...], content: "...", fileName: "..." }
+
+# Get file content (raw text)
+GET /api/file/d/docs/design.md?key=<key>&mode=raw
+# Returns: { type: "text", content: "...", fileName: "..." }
+
+# Get raw file bytes
+GET /path/d/docs/design.md?key=<key>&raw=1
+# Returns: file content with appropriate Content-Type
+
+# Export as PDF
+GET /path/d/docs/design.md?key=<key>&export=pdf
+# Returns: application/pdf
+
+# Export as DOCX
+GET /path/d/docs/design.md?key=<key>&export=docx
+# Returns: application/vnd.openxmlformats-officedocument.wordprocessingml.document
+```
+
+### Directory Listing
+
+```bash
+# List drives
+GET /api/drives?key=<key>
+# Returns: { drives: [{ letter: "C", label: "System", ... }] }
+
+# List directory
+GET /api/directory/d/docs?key=<key>
+# Returns: { path: "d/docs", entries: [{ name: "...", type: "file"|"directory", ... }] }
+```
+
+### Authentication
+
+```bash
+# Check auth status
+GET /api/auth/status?key=<key>
+# Returns: { authenticated: true, email: "...", isInsider: true, mode: "key" }
+```
+
+### Sharing
+
+```bash
+# Get insider key (requires X-API-Key header with seed)
+GET /insider-key
+# Headers: X-API-Key: <seed>
+# Returns: { key: "a1b2c3d4..." }
+
+# Compute outsider key for a path
+GET /key?path=/d/docs/design.md
+# Headers: X-API-Key: <seed>
+# Returns: { key: "e5f6a7b8..." }
+
+# Rotate a key
+POST /rotate-key
+# Body: { key: "<current-insider-key>" }
+```
+
+### Event Gateway
+
+```bash
+# Send a webhook
+POST /event?key=<webhook-key>
+Content-Type: application/json
+Body: { "type": "page.content_updated", "data": { "page_id": "abc123" } }
+# Returns: { matched: "notion-page-update" } or { matched: null }
+```
+
+### Health
+
+```bash
+GET /health
+# Returns: 200 OK (no auth required)
+```
+
+## Converting Windows Paths to URLs
+
+Jeeves Server maps Windows filesystem paths to URL paths:
+
+```
+D:\docs\design.md  →  /d/docs/design.md
+E:\projects\foo    →  /e/projects/foo
+```
+
+**Conversion formula:**
+1. Replace backslashes with forward slashes
+2. Replace the drive letter + colon with lowercase letter
+3. Prepend the route prefix (`/path/` for legacy, `/browse/` for SPA, `/api/file/` for API)
+
+```javascript
+function winPathToUrl(winPath, prefix = '/path/') {
+  const urlPath = winPath
+    .replace(/\\/g, '/')
+    .replace(/^([A-Z]):/, (_, d) => d.toLowerCase());
+  return `${prefix}${urlPath}`;
+}
+
+// D:\docs\design.md → /path/d/docs/design.md
+// D:\docs\design.md → /browse/d/docs/design.md
+// D:\docs\design.md → /api/file/d/docs/design.md
+```
+
+```powershell
+# PowerShell equivalent
+function Convert-ToJeevesUrl {
+  param([string]$Path, [string]$Prefix = '/path/')
+  $urlPath = $Path -replace '\\','/' -replace '^([A-Z]):',{ $_.Groups[1].Value.ToLower() }
+  return "${Prefix}${urlPath}"
+}
+```
+
+## Generating Share Links
+
+### Insider links
+
+```javascript
+const insiderKey = computeInsiderKey(seed);
+const url = `https://jeeves.example.com/browse/d/docs/design.md?key=${insiderKey}`;
+```
+
+### Outsider links (path-scoped)
+
+```javascript
+const crypto = require('crypto');
+
+function outsiderKey(seed, path) {
+  const normalized = path.toLowerCase().replace(/^\/+|\/+$/g, '');
+  return crypto.createHmac('sha256', seed).update(normalized).digest('hex').substring(0, 32);
+}
+
+function outsiderKeyWithExpiry(seed, path, expiryMs) {
+  const normalized = path.toLowerCase().replace(/^\/+|\/+$/g, '');
+  const data = `${normalized}|${expiryMs}`;
+  return crypto.createHmac('sha256', seed).update(data).digest('hex').substring(0, 32);
+}
+
+// Non-expiring outsider link
+const key = outsiderKey(seed, 'd/docs/design.md');
+const url = `https://jeeves.example.com/browse/d/docs/design.md?key=${key}`;
+
+// Expiring outsider link (1 week)
+const expiry = Date.now() + 7 * 24 * 60 * 60 * 1000;
+const key = outsiderKeyWithExpiry(seed, 'd/docs/design.md', expiry);
+const url = `https://jeeves.example.com/browse/d/docs/design.md?key=${key}&exp=${expiry}`;
+```
+
+### Directory links
+
+Outsider keys for directories grant access to all descendants:
+
+```javascript
+// Share an entire directory
+const key = outsiderKey(seed, 'd/projects/client-x');
+const url = `https://jeeves.example.com/browse/d/projects/client-x?key=${key}`;
+// Grants access to all files under D:\projects\client-x\
+```
+
+## For AI Assistants
+
+If you're an AI assistant working with Jeeves Server, here's what you need to know:
+
+### Generating links to share with humans
+
+When your human asks you to share a document:
+
+1. **Convert the Windows path** to a URL path (see above)
+2. **Use the insider key** for team members, or generate an outsider key for external recipients
+3. **Choose the right route**: `/browse/` for browser viewing, `/path/` with `?export=pdf` for direct PDF download
+
+### Authoring documents
+
+Write Markdown files to the server's filesystem. Jeeves Server will render them beautifully. You can:
+- Embed Mermaid diagrams (rendered inline)
+- Embed SVG files (rendered with pan/zoom)
+- Use code blocks with language hints (syntax highlighted)
+- Reference other local files with relative paths
+
+### Checking server status
+
+```bash
+curl -s http://localhost:1934/health
+```
+
+### Triggering webhooks
+
+If you need to trigger an action via the event gateway:
+
+```bash
+curl -X POST "http://localhost:1934/event?key=<webhook-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"action": "rebuild", "target": "docs"}'
+```
+
+Match this against a configured event schema to dispatch your handler.