@andespindola/brainlink 1.0.2 → 1.0.3

package/README.md

@@ -633,7 +633,7 @@ blink server --vault ./vault --no-index
 
 ## HTTP API
 
-The HTTP API is read-only and exists only to power the graph UI and local inspection workflows.
+The HTTP API is mostly read-oriented and exists to power the graph UI, local inspection workflows and the local document-import modal.
 
 The server always refuses non-loopback hosts. Brainlink HTTP only runs on localhost.
 
@@ -654,6 +654,7 @@ Routes:
 - `GET /api/broken-links`
 - `GET /api/orphans`
 - `GET /api/validate`
+- `POST /api/import-file` with multipart field `file`
 
 Read routes accept `agent=<agent-id>`:
 
@@ -768,6 +769,18 @@ Imports durable memory from a legacy SQLite database into Markdown notes (`agent
 When `--db` is omitted, Brainlink auto-detects common legacy paths such as `<vault>/.brainlink/brainlink.db`.
 Use `--agent <id>` to force all imported rows into one namespace, `--limit` for incremental imports, `--dry-run` to preview without writing files, and `--no-index` to defer reindexing.
 
+### `import-file`
+
+```bash
+blink import-file ./report.pdf --vault ./team-vault
+blink import-file ./report.pdf --vault ./team-vault --agent coding-agent
+blink import-file ./report.pdf --vault ./team-vault --title "Quarterly Report"
+blink import-file ./report.pdf --vault ./team-vault --no-auto-index
+```
+
+Converts a document with Docling and imports the converted Markdown as a durable note. The `docling` executable must be installed and available in `PATH`.
+The graph UI exposes the same flow through the upload button in the toolbar.
+
 ### `init`
 
 ```bash
@@ -1000,7 +1013,7 @@ blink server --vault ./vault --no-open
 blink server --vault ./vault --no-watch
 ```
 
-Starts the local read-only graph UI and HTTP API.
+Starts the local graph UI and HTTP API.
 Watch mode is enabled by default for Markdown changes in local filesystem vaults. Use `--no-watch` to run without the watcher.
 By default, it tries to open a native desktop GUI window for the graph URL.
 On Linux, native GUI is disabled by default; enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.

package/dist/application/frontend/client-css.js

@@ -379,6 +379,133 @@ li small {
   display: none;
 }
 
+.upload-dialog {
+  position: absolute;
+  z-index: 7;
+  top: 88px;
+  right: 14px;
+  width: min(420px, calc(100vw - 28px));
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--panel);
+  color: var(--text);
+  box-shadow: 0 24px 80px rgba(1, 6, 13, 0.48);
+  overflow: hidden;
+}
+
+.upload-dialog[hidden] {
+  display: none;
+}
+
+.upload-dialog form {
+  display: grid;
+  gap: 14px;
+}
+
+.upload-dialog header,
+.upload-dialog footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 14px;
+  padding: 16px;
+}
+
+.upload-dialog header {
+  border-bottom: 1px solid var(--line);
+}
+
+.upload-dialog h2,
+.upload-dialog p {
+  margin: 0;
+}
+
+.upload-dialog h2 {
+  margin-top: 4px;
+  font-size: 18px;
+  line-height: 1.2;
+}
+
+#uploadClose,
+#uploadSubmit {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--panel-strong);
+  color: var(--text);
+  cursor: pointer;
+}
+
+#uploadClose {
+  flex: 0 0 auto;
+  width: 38px;
+  height: 38px;
+  padding: 0;
+  font-size: 22px;
+  line-height: 1;
+}
+
+#uploadSubmit {
+  min-width: 98px;
+  height: 38px;
+  padding: 0 14px;
+}
+
+#uploadSubmit:disabled {
+  cursor: progress;
+  opacity: 0.62;
+}
+
+#uploadClose:hover,
+#uploadClose:focus,
+#uploadSubmit:hover,
+#uploadSubmit:focus {
+  border-color: var(--accent);
+  color: var(--accent);
+}
+
+.upload-field {
+  display: grid;
+  gap: 7px;
+  padding: 0 16px;
+}
+
+.upload-field span,
+.upload-check span {
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.upload-field input[type="text"],
+.upload-field input[type="file"] {
+  width: 100%;
+  min-height: 40px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: rgba(12, 24, 36, 0.94);
+  color: var(--text);
+  padding: 8px 10px;
+}
+
+.upload-check {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  padding: 0 16px;
+}
+
+.upload-check input {
+  width: 16px;
+  height: 16px;
+}
+
+#uploadStatus {
+  min-height: 16px;
+  color: var(--muted);
+  font-size: 12px;
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+}
+
 .content-dialog article {
   display: grid;
   grid-template-rows: auto auto minmax(0, 1fr);
@@ -559,6 +686,13 @@ li small {
     max-height: none;
   }
 
+  .upload-dialog {
+    top: 8px;
+    right: 8px;
+    left: 8px;
+    width: auto;
+  }
+
   .content-dialog header {
     align-items: flex-start;
     gap: 12px;

package/dist/application/frontend/client-html.js

@@ -35,6 +35,7 @@ export const createClientHtml = () => `<!doctype html>
               <select id="context"></select>
             </label>
             <div class="toolbar" aria-label="Graph controls">
+              <button id="uploadOpen" type="button" title="Import document">⇧</button>
               <button id="zoomIn" type="button" title="Zoom in">+</button>
               <button id="zoomOut" type="button" title="Zoom out">-</button>
               <button id="fit" type="button" title="Focus central hub">◎</button>
@@ -48,6 +49,33 @@ export const createClientHtml = () => `<!doctype html>
           <div id="graphLabels" class="graph-labels" aria-hidden="true"></div>
           <div id="graphTooltip" class="graph-tooltip" role="tooltip" hidden></div>
           <canvas id="miniMap" class="mini-map" aria-label="Graph overview"></canvas>
+          <aside id="uploadDialog" class="upload-dialog" role="dialog" aria-labelledby="uploadTitle" hidden>
+            <form id="uploadForm">
+              <header>
+                <div>
+                  <span class="eyebrow">Context import</span>
+                  <h2 id="uploadTitle">Upload document</h2>
+                </div>
+                <button id="uploadClose" type="button" aria-label="Close upload dialog" title="Close upload dialog">&times;</button>
+              </header>
+              <label class="upload-field">
+                <span>File</span>
+                <input id="uploadFile" name="file" type="file" required />
+              </label>
+              <label class="upload-field">
+                <span>Title</span>
+                <input id="uploadTitleInput" name="title" type="text" placeholder="Use filename" autocomplete="off" />
+              </label>
+              <label class="upload-check">
+                <input id="uploadAllowSensitive" name="allowSensitive" type="checkbox" />
+                <span>Allow sensitive-looking content</span>
+              </label>
+              <footer>
+                <p id="uploadStatus" role="status"></p>
+                <button id="uploadSubmit" type="submit">Import</button>
+              </footer>
+            </form>
+          </aside>
           <aside id="contentDialog" class="content-dialog" role="dialog" aria-labelledby="contentTitle" hidden>
             <article>
               <header>

package/dist/application/frontend/client-js.js

@@ -12,6 +12,15 @@ const elements = {
   fit: byId('fit'),
   releaseNode: byId('releaseNode'),
   reset: byId('reset'),
+  uploadOpen: byId('uploadOpen'),
+  uploadDialog: byId('uploadDialog'),
+  uploadForm: byId('uploadForm'),
+  uploadFile: byId('uploadFile'),
+  uploadTitleInput: byId('uploadTitleInput'),
+  uploadAllowSensitive: byId('uploadAllowSensitive'),
+  uploadClose: byId('uploadClose'),
+  uploadSubmit: byId('uploadSubmit'),
+  uploadStatus: byId('uploadStatus'),
   labels: byId('graphLabels'),
   tooltip: byId('graphTooltip'),
   miniMap: byId('miniMap'),
@@ -1368,6 +1377,10 @@ const setupInput = () => {
   })
 
   window.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape' && !elements.uploadDialog.hidden) {
+      closeUploadDialog()
+      return
+    }
     if (event.key === 'Escape' && !elements.contentDialog.hidden) {
       closeContentDialog()
       return
@@ -1386,6 +1399,95 @@ const setupInput = () => {
   })
 }
 
+const openUploadDialog = () => {
+  elements.uploadDialog.hidden = false
+  elements.uploadStatus.textContent = ''
+  elements.uploadTitleInput.value = ''
+  elements.uploadFile.value = ''
+  elements.uploadAllowSensitive.checked = false
+  window.setTimeout(() => elements.uploadFile.focus(), 0)
+}
+
+const closeUploadDialog = () => {
+  elements.uploadDialog.hidden = true
+}
+
+const setUploadBusy = (busy) => {
+  elements.uploadSubmit.disabled = busy
+  elements.uploadFile.disabled = busy
+  elements.uploadTitleInput.disabled = busy
+  elements.uploadAllowSensitive.disabled = busy
+}
+
+const uploadImportUrl = () => {
+  const params = new URLSearchParams()
+  if (state.agentId) {
+    params.set('agent', state.agentId)
+  }
+  const query = params.toString()
+
+  return '/api/import-file' + (query ? '?' + query : '')
+}
+
+const submitUpload = async (event) => {
+  event.preventDefault()
+  const file = elements.uploadFile.files?.[0]
+  if (!file) {
+    elements.uploadStatus.textContent = 'Choose a file to import.'
+    return
+  }
+
+  const form = new FormData()
+  form.append('file', file)
+  const title = elements.uploadTitleInput.value.trim()
+  if (title) {
+    form.append('title', title)
+  }
+  if (elements.uploadAllowSensitive.checked) {
+    form.append('allowSensitive', 'true')
+  }
+
+  setUploadBusy(true)
+  elements.uploadStatus.textContent = 'Importing...'
+
+  try {
+    const response = await fetch(uploadImportUrl(), {
+      method: 'POST',
+      body: form
+    })
+    const payload = await response.json().catch(() => ({}))
+    if (!response.ok) {
+      throw new Error(payload?.error || 'Import failed')
+    }
+
+    elements.uploadStatus.textContent = 'Imported "' + String(payload?.title || file.name) + '".'
+    await loadAgents()
+    await loadContexts()
+    scheduleChunkFetch({ fit: true })
+    window.setTimeout(closeUploadDialog, 700)
+  } catch (error) {
+    elements.uploadStatus.textContent = error instanceof Error ? error.message : String(error)
+  } finally {
+    setUploadBusy(false)
+  }
+}
+
+const setupUploadDialog = () => {
+  elements.uploadOpen.addEventListener('click', openUploadDialog)
+  elements.uploadClose.addEventListener('click', closeUploadDialog)
+  elements.uploadForm.addEventListener('submit', (event) => {
+    submitUpload(event).catch((error) => {
+      elements.uploadStatus.textContent = error instanceof Error ? error.message : String(error)
+      setUploadBusy(false)
+    })
+  })
+  elements.uploadDialog.addEventListener('click', (event) => {
+    if (event.target === elements.uploadDialog) {
+      closeUploadDialog()
+    }
+  })
+}
+
 const setupControls = () => {
   elements.zoomIn.addEventListener('click', () => {
     zoomAtPoint(state.viewport.width / 2, state.viewport.height / 2, 1.06)
@@ -1629,6 +1731,7 @@ const bootstrap = async () => {
   setupRenderWorker()
   setupInput()
   setupControls()
+  setupUploadDialog()
   setupContextControl()
   wireNodeLinkClicks()
 

package/dist/application/import-file.js

@@ -0,0 +1,45 @@
+import { basename, extname } from 'node:path';
+import { sharedAgentId } from '../domain/agents.js';
+import { convertDocumentWithDocling } from '../infrastructure/docling.js';
+import { addNoteWithMetadata } from './add-note.js';
+import { indexVault } from './index-vault.js';
+const titleFromSourceName = (sourceName) => {
+    const name = basename(sourceName, extname(sourceName))
+        .replace(/[_-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return name.length > 0 ? name : 'Imported Document';
+};
+const buildImportedContent = (sourceName, markdown) => [
+    `Imported from \`${sourceName}\` with Docling. #import #document`,
+    '',
+    '## Extracted Content',
+    '',
+    markdown.trim()
+].join('\n');
+const toResult = (title, sourceName, added, index) => ({
+    title,
+    sourceName,
+    path: added.path,
+    writeConnectivity: {
+        autoLinked: added.autoLinked,
+        linkTarget: added.linkTarget,
+        context: added.context,
+        hubCreated: added.hubCreated,
+        guaranteedEdge: added.autoLinked
+    },
+    ...(index ? { index } : {})
+});
+export const importFile = async (input) => {
+    const sourceName = input.originalName?.trim() || basename(input.filePath);
+    const title = input.title?.trim() || titleFromSourceName(sourceName);
+    const converter = input.converter ?? convertDocumentWithDocling;
+    const converted = await converter({ path: input.filePath });
+    const content = buildImportedContent(sourceName, converted.markdown);
+    const added = await addNoteWithMetadata(input.vaultPath, title, content, input.agentId ?? sharedAgentId, {
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: input.autoContextLinks
+    });
+    const index = input.autoIndex === false ? undefined : await indexVault(input.vaultPath);
+    return toResult(title, sourceName, added, index);
+};

package/dist/application/server/multipart.js

@@ -0,0 +1,80 @@
+const readRequestBuffer = async (request, limitBytes) => {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.byteLength;
+        if (size > limitBytes) {
+            throw Object.assign(new Error('Request body too large'), { statusCode: 413 });
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+};
+const parseDisposition = (value) => value
+    .split(';')
+    .slice(1)
+    .reduce((params, entry) => {
+    const [rawKey, ...rawValue] = entry.trim().split('=');
+    const key = rawKey?.trim();
+    if (!key) {
+        return params;
+    }
+    params[key] = rawValue.join('=').trim().replace(/^"|"$/g, '');
+    return params;
+}, {});
+const parseHeaders = (value) => value.split('\r\n').reduce((headers, line) => {
+    const separator = line.indexOf(':');
+    if (separator < 0) {
+        return headers;
+    }
+    const key = line.slice(0, separator).trim().toLowerCase();
+    const headerValue = line.slice(separator + 1).trim();
+    if (key) {
+        headers[key] = headerValue;
+    }
+    return headers;
+}, {});
+const stripPartTerminator = (value) => value.endsWith('\r\n') ? value.slice(0, -2) : value;
+export const parseMultipartForm = async (request, limitBytes = 50 * 1024 * 1024) => {
+    const contentType = Array.isArray(request.headers['content-type'])
+        ? request.headers['content-type'][0]
+        : request.headers['content-type'];
+    const boundary = contentType?.match(/boundary=(?:"([^"]+)"|([^;]+))/)?.[1] ?? contentType?.match(/boundary=(?:"([^"]+)"|([^;]+))/)?.[2];
+    if (!boundary) {
+        throw Object.assign(new Error('Missing multipart boundary'), { statusCode: 400 });
+    }
+    const body = await readRequestBuffer(request, limitBytes);
+    const bodyText = body.toString('binary');
+    const parts = bodyText.split(`--${boundary}`);
+    const fields = {};
+    const files = [];
+    for (const rawPart of parts) {
+        if (!rawPart || rawPart === '--\r\n' || rawPart === '--') {
+            continue;
+        }
+        const part = rawPart.startsWith('\r\n') ? rawPart.slice(2) : rawPart;
+        const separator = part.indexOf('\r\n\r\n');
+        if (separator < 0) {
+            continue;
+        }
+        const headers = parseHeaders(part.slice(0, separator));
+        const content = stripPartTerminator(part.slice(separator + 4));
+        const disposition = parseDisposition(headers['content-disposition'] ?? '');
+        const fieldName = disposition.name ?? '';
+        if (!fieldName) {
+            continue;
+        }
+        if (disposition.filename != null && disposition.filename.length > 0) {
+            files.push({
+                fieldName,
+                filename: disposition.filename,
+                contentType: headers['content-type'] ?? 'application/octet-stream',
+                data: Buffer.from(content, 'binary')
+            });
+            continue;
+        }
+        fields[fieldName] = Buffer.from(content, 'binary').toString('utf8');
+    }
+    return { fields, files };
+};

package/dist/application/server/routes.js

@@ -1,3 +1,6 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../analyze-vault.js';
 import { buildContextPackage } from '../build-context.js';
 import { getGraph } from '../get-graph.js';
@@ -7,6 +10,7 @@ import { getGraphLayout } from '../get-graph-layout.js';
 import { getGraphView } from '../get-graph-view.js';
 import { getGraphStreamChunk } from '../get-graph-stream-chunk.js';
 import { deleteGraphViewState, getGraphViewState, saveGraphViewState } from '../graph-view-state.js';
+import { importFile } from '../import-file.js';
 import { listAgents } from '../list-agents.js';
 import { listBacklinks, listLinks } from '../list-links.js';
 import { searchGraphNodeIds } from '../search-graph-node-ids.js';
@@ -18,6 +22,7 @@ import { createClientJs } from '../frontend/client-js.js';
 import { createClientWorkerJs } from '../frontend/client-worker-js.js';
 import { createClientRenderWorkerJs } from '../frontend/client-render-worker-js.js';
 import { contentTypes, createJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
+import { parseMultipartForm } from './multipart.js';
 const readSearchMode = async (url) => {
     const config = await loadBrainlinkConfig();
     const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
@@ -95,6 +100,27 @@ const readGraphViewStateInput = (url) => ({
     agentId: readAgentQuery(url),
     context: readContextQuery(url)
 });
+const booleanField = (value) => value === '1' || value === 'true' || value === 'on';
+const writeUploadTempFile = async (filename, data) => {
+    const directory = await mkdtemp(join(tmpdir(), 'brainlink-upload-'));
+    const safeName = filename.replace(/[\\/]/g, '-').trim() || 'upload.bin';
+    const path = join(directory, safeName);
+    await writeFile(path, data);
+    return { directory, path };
+};
+const isSameOriginWrite = (request, url) => {
+    const originHeader = Array.isArray(request.headers.origin) ? request.headers.origin[0] : request.headers.origin;
+    if (!originHeader) {
+        return true;
+    }
+    try {
+        const origin = new URL(originHeader);
+        return origin.protocol === url.protocol && origin.host === url.host;
+    }
+    catch {
+        return false;
+    }
+};
 const compactGraphLayoutThreshold = 12_000;
 const compactGraphLayoutEdgeLimit = 60_000;
 const graphLayoutBodyCacheLimit = 8;
@@ -345,6 +371,34 @@ export const route = async (request, url, vaultPath) => {
         }
         return createResponse(createJsonResponse(await deleteGraphViewState(vaultPath, input)), 200, contentTypes['.json']);
     }
+    if (request.method === 'POST' && url.pathname === '/api/import-file') {
+        if (!isSameOriginWrite(request, url)) {
+            return createResponse(createJsonResponse({ error: 'Cross-origin imports are not allowed' }), 403, contentTypes['.json']);
+        }
+        const config = await loadBrainlinkConfig();
+        const form = await parseMultipartForm(request);
+        const file = form.files.find((candidate) => candidate.fieldName === 'file') ?? form.files[0];
+        if (!file || file.data.byteLength === 0) {
+            return createResponse(createJsonResponse({ error: 'Missing uploaded file' }), 400, contentTypes['.json']);
+        }
+        const temp = await writeUploadTempFile(file.filename, file.data);
+        try {
+            const result = await importFile({
+                vaultPath,
+                filePath: temp.path,
+                originalName: file.filename,
+                title: form.fields.title,
+                agentId: readAgentQuery(url) ?? form.fields.agent,
+                allowSensitive: booleanField(form.fields.allowSensitive),
+                autoContextLinks: config.autoCanonicalContextLinks,
+                autoIndex: config.autoIndexOnWrite
+            });
+            return createResponse(createJsonResponse(result), 200, contentTypes['.json']);
+        }
+        finally {
+            await rm(temp.directory, { recursive: true, force: true });
+        }
+    }
     if (isReadMethod(request) && url.pathname === '/api/graph-node') {
         const id = url.searchParams.get('id')?.trim() ?? '';
         if (!id) {

package/dist/cli/commands/write-commands.js

@@ -8,6 +8,7 @@ import { buildContextPackage } from '../../application/build-context.js';
 import { deleteNote } from '../../application/delete-note.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/dedupe-notes.js';
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
+import { importFile } from '../../application/import-file.js';
 import { indexVault, indexVaultWithOptions } from '../../application/index-vault.js';
 import { migrateContextLinks } from '../../application/migrate-context-links.js';
 import { canonicalizeContextLinks } from '../../application/canonical-context-links.js';
@@ -874,6 +875,38 @@ export const registerWriteCommands = (program) => {
             return `Created note at ${added.path}.${linkMessage}${duplicateMessage}`;
         });
     });
+    program
+        .command('import-file')
+        .argument('<file>', 'file to convert and import into the vault')
+        .option('-t, --title <title>', 'note title; defaults to the source filename')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--allow-sensitive', 'allow writing converted content that looks like a secret')
+        .option('--no-auto-context-links', 'skip canonical Context Links for this imported note')
+        .option('--no-auto-index', 'skip reindexing after import')
+        .option('--json', 'print machine-readable JSON')
+        .description('convert a document with Docling and import it as a Markdown note')
+        .action(async (file, options) => {
+        const resolved = await resolveOptions(options);
+        const result = await importFile({
+            vaultPath: resolved.vault,
+            filePath: resolve(file),
+            title: options.title,
+            agentId: resolved.agent,
+            allowSensitive: Boolean(options.allowSensitive),
+            autoContextLinks: options.autoContextLinks !== false && resolved.config.autoCanonicalContextLinks,
+            autoIndex: options.autoIndex !== false && resolved.config.autoIndexOnWrite
+        });
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result
+        }, () => {
+            const linkMessage = result.writeConnectivity.autoLinked ? ` Linked to [[${result.writeConnectivity.linkTarget}]].` : '';
+            const indexMessage = result.index ? ` Indexed ${result.index.documentCount} documents.` : '';
+            return `Imported ${result.sourceName} as "${result.title}" at ${result.path}.${linkMessage}${indexMessage}`;
+        });
+    });
     program
         .command('delete-note')
         .option('-v, --vault <vault>', 'vault directory')

package/dist/infrastructure/docling.js

@@ -0,0 +1,40 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, extname, join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const readConvertedMarkdown = async (outputDirectory, sourcePath) => {
+    const sourceName = basename(sourcePath, extname(sourcePath));
+    const files = await readdir(outputDirectory);
+    const exact = files.find((file) => file === `${sourceName}.md`);
+    const fallback = files.find((file) => extname(file).toLowerCase() === '.md');
+    const markdownFile = exact ?? fallback;
+    if (!markdownFile) {
+        throw new Error('Docling did not produce a Markdown output file.');
+    }
+    return readFile(join(outputDirectory, markdownFile), 'utf8');
+};
+const toDoclingError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const notFound = 'code' in Object(error) && Object(error).code === 'ENOENT';
+    return new Error(notFound
+        ? 'Docling executable not found. Install the Python package and make the `docling` command available in PATH.'
+        : `Docling conversion failed: ${message}`);
+};
+export const convertDocumentWithDocling = async (input) => {
+    const outputDirectory = await mkdtemp(join(tmpdir(), 'brainlink-docling-'));
+    try {
+        await execFileAsync('docling', ['--to', 'md', '--output', outputDirectory, input.path], {
+            maxBuffer: 1024 * 1024 * 50
+        });
+        const markdown = await readConvertedMarkdown(outputDirectory, input.path);
+        return { markdown };
+    }
+    catch (error) {
+        throw toDoclingError(error);
+    }
+    finally {
+        await rm(outputDirectory, { recursive: true, force: true });
+    }
+};

package/docs/AGENT_USAGE.md

@@ -430,6 +430,17 @@ blink db-import --vault ./team-vault --db ./legacy/brainlink.db --table legacy_n
 Without `--db`, Brainlink auto-detects common legacy database paths.
 Use `--agent` to force namespace, `--limit` for staged migration, `--dry-run` to preview writes, and `--no-index` to postpone indexing.
 
+### Import A Document File
+
+```bash
+blink import-file ./report.pdf --vault ./team-vault
+blink import-file ./report.pdf --vault ./team-vault --agent coding-agent
+blink import-file ./report.pdf --vault ./team-vault --title "Quarterly Report"
+```
+
+`import-file` converts a source document with Docling, writes the converted Markdown as a durable note, and indexes the result by default.
+The `docling` executable must be installed and available in `PATH`. The graph UI exposes the same import path through its upload modal.
+
 ### Install Agent Integration
 
 ```bash
@@ -636,7 +647,7 @@ blink server --vault ./vault --host 127.0.0.1 --port 4321
 blink server --vault ./vault --host 127.0.0.1 --port 4321 --no-open
 ```
 
-This starts a local frontend for inspecting the knowledge graph.
+This starts a local frontend for inspecting the knowledge graph and importing document files into the selected vault.
 By default it tries to open the graph in a native desktop GUI window:
 - macOS: Swift + WebKit
 - Windows: PowerShell WinForms WebBrowser
@@ -764,9 +775,10 @@ GET  /api/stats
 GET  /api/broken-links
 GET  /api/orphans
 GET  /api/validate
+POST /api/import-file
 ```
 
-The HTTP API is read-only. Use the CLI for writes and indexing.
+The HTTP API is read-oriented, with `POST /api/import-file` reserved for the local upload modal. Use the CLI for other writes and indexing.
 
 Indexing writes private encrypted search packs at `.brainlink/search-packs/*.blpk` for resilient retrieval and portability.
 Pack search now uses compressed-space prefiltering (token bloom index per pack) before decrypting/reading pack payloads.

package/docs/ARCHITECTURE.md

@@ -165,9 +165,10 @@ server command
   -> /api/graph-layout derives a cauliflower hub layout from indexed graph data
   -> optional context query narrows the layout to a segment-scoped cauliflower subgraph
   -> browser renders graph canvas
+  -> /api/import-file converts uploaded documents and writes Markdown notes
 ```
 
-The graph UI is intentionally read-only. Markdown remains the write interface and index artifacts remain derived data.
+The graph UI is primarily an inspection surface. Its upload modal is the narrow write path: uploaded files are converted to Markdown notes through the same application import use case used by the CLI. Markdown remains the source of truth and index artifacts remain derived data.
 The cauliflower layout is a visual projection over the indexed graph. Indexed weighted wiki-link edges remain unchanged for backlinks, ranking, graph reads and context traversal. The browser layout renders a simplified hierarchy instead: primary hub -> segment hubs -> local context nodes. This avoids unstable cross-context visual edges while preserving the real relationship model outside the render layer. Zoomed-out graph streams summarize those lobes as segment clusters before revealing individual nodes on zoom-in.
 
 ## HTTP API Flow
@@ -181,7 +182,7 @@ HTTP request
 ```
 
 The HTTP API is local-first and unauthenticated. It is meant for local agents, browser UI, and development workflows.
-The route adapter caches generated frontend assets (`/`, `/styles.css`, `/app.js`, `/app-worker.js`) and graph-layout JSON payloads by layout signature to reduce repeated CPU and allocation pressure during navigation.
+The route adapter caches generated frontend assets (`/`, `/styles.css`, `/app.js`, `/app-worker.js`) and graph-layout JSON payloads by layout signature to reduce repeated CPU and allocation pressure during navigation. File upload conversion is intentionally routed through the import-file use case instead of writing vault files directly in the HTTP adapter.
 
 ## MCP Flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",