notex-companion 0.3.2 → 0.3.3

package/README.md

@@ -45,10 +45,13 @@ notex-companion mcp                 # start the stdio MCP server — graph_statu
                                      # graph_query, graph_path, graph_node, plus notex_list_questions,
                                      # notex_get_question, notex_get_answer, notex_save_answer
                                      # (require .notex/notex.json — see docs/specs/notex-mcp-server.md)
+notex-companion link [options]      # write .notex/notex.json, pairing this checkout to a Notex Repository
 ```
 
 Setup, how it picks which checkout to serve, and a manual verification walkthrough:
 [`docs/testing/mcp-server-setup.md`](https://github.com/bhirmbani/notex/blob/main/docs/testing/mcp-server-setup.md).
+For `link` specifically — happy path, rotation, and every refusal path — see
+[`docs/testing/notex-companion-link-manual-test.md`](https://github.com/bhirmbani/notex/blob/main/docs/testing/notex-companion-link-manual-test.md).
 
 ### `serve` options
 
@@ -58,6 +61,19 @@ Setup, how it picks which checkout to serve, and a manual verification walkthrou
 | `--origin <url>` | — | An additional allowed CORS origin, beyond the production Notex origin (and `http://localhost:3000` outside `NODE_ENV=production`). Repeatable. |
 | `--rotate-token` | off | Generate a new pairing token, invalidating the previous one. |
 
+### `link` options (all required)
+
+| Flag | Meaning |
+|---|---|
+| `--organization-id <id>` | Notex organization id. |
+| `--project-id <id>` | Notex project id — cross-checked against the Repository's actual project before writing. |
+| `--repository-id <id>` | Notex repository id to bind this checkout to. |
+| `--api-key <key>` | Generated once, plaintext, from Notex Settings → API keys. |
+
+`link` validates all four against the Notex API before writing `.notex/notex.json` (mode `0600`) —
+a bad key, an inaccessible repository, or a repository/project mismatch fails with an actionable
+message and writes nothing.
+
 ## Pairing
 
 On first run the companion generates a 32-byte token, persists it to `.notex/companion.json`

package/dist/atomicWrite.d.ts

@@ -0,0 +1 @@
+export declare function atomicWriteFile(path: string, content: string, mode: number): void;

package/dist/cli.d.ts

@@ -1,6 +1,5 @@
-/** Thrown by argument parsing on bad input — `main()` turns it into a stderr message + exit 1. */
-export declare class CliUsageError extends Error {
-}
+import { CliUsageError } from "./cliErrors.js";
+export { CliUsageError };
 export type ServeArgs = {
     port: number | undefined;
     origins: Array<string>;

package/dist/cli.js

@@ -6520,10 +6520,203 @@ var require_dist = __commonJS((exports, module) => {
 import { existsSync } from "node:fs";
 import { resolve as resolve2 } from "node:path";
 
+// src/cliErrors.ts
+class CliUsageError extends Error {
+}
+
+// src/atomicWrite.ts
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+function atomicWriteFile(path, content, mode) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmpPath = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmpPath, content, { mode, flag: "wx" });
+  renameSync(tmpPath, path);
+}
+
+// src/notexConfig.ts
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+function configFilePath(checkoutPath) {
+  return join(checkoutPath, ".notex", "notex.json");
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function loadNotexConfig(checkoutPath, env = process.env) {
+  let raw;
+  try {
+    raw = readFileSync(configFilePath(checkoutPath), "utf8");
+  } catch {
+    return { kind: "unlinked", reason: "no .notex/notex.json found" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: "unlinked", reason: ".notex/notex.json is not valid JSON" };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { kind: "unlinked", reason: ".notex/notex.json must be a JSON object" };
+  }
+  const { organizationId, projectId, repositoryId, apiKey } = parsed;
+  if (!nonEmptyString(organizationId) || !nonEmptyString(projectId) || !nonEmptyString(repositoryId)) {
+    return { kind: "unlinked", reason: ".notex/notex.json is missing organizationId, projectId, or repositoryId" };
+  }
+  const resolvedKey = nonEmptyString(env.NOTEX_API_KEY) ? env.NOTEX_API_KEY : apiKey;
+  if (!nonEmptyString(resolvedKey)) {
+    return { kind: "unlinked", reason: ".notex/notex.json is missing apiKey, and NOTEX_API_KEY is not set" };
+  }
+  return { kind: "linked", config: { organizationId, projectId, repositoryId, apiKey: resolvedKey } };
+}
+
+// src/types.ts
+var ERROR_CODES = {
+  unauthorized: "unauthorized",
+  notFound: "not_found",
+  graphUnreadable: "graph_unreadable",
+  invalidRequest: "invalid_request",
+  graphLoading: "graph_loading",
+  forbidden: "forbidden",
+  notexApiError: "notex_api_error"
+};
+
+class OpError extends Error {
+  code;
+  detail;
+  constructor(code, message, detail) {
+    super(message);
+    this.name = "OpError";
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+// src/notexClient.ts
+var DEFAULT_API_URL = "http://localhost:3000";
+function resolveApiUrl(env = process.env) {
+  return env.NOTEX_API_URL?.trim() || DEFAULT_API_URL;
+}
+async function request(config, fetchImpl, method, path, body) {
+  let res;
+  try {
+    res = await fetchImpl(`${config.baseUrl}${path}`, {
+      method,
+      headers: {
+        "x-api-key": config.apiKey,
+        ...body !== undefined ? { "content-type": "application/json" } : {}
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined
+    });
+  } catch (err) {
+    throw new OpError(ERROR_CODES.notexApiError, `Could not reach the Notex API at ${config.baseUrl}`, err);
+  }
+  if (res.status === 401)
+    throw new OpError(ERROR_CODES.unauthorized, "Notex rejected the API key");
+  if (res.status === 403)
+    throw new OpError(ERROR_CODES.forbidden, "Not authorized for this Project");
+  if (res.status === 404)
+    throw new OpError(ERROR_CODES.notFound, "Not found in Notex");
+  if (!res.ok) {
+    const body2 = await res.json().catch(() => ({}));
+    throw new OpError(ERROR_CODES.notexApiError, body2.error?.message ?? `Notex API error (HTTP ${res.status})`);
+  }
+  return await res.json();
+}
+var enc = (id) => encodeURIComponent(id);
+function createNotexClient(config, fetchImpl = fetch) {
+  return {
+    getRepository: (organizationId, id) => request(config, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/repositories/${enc(id)}`),
+    listContexts: (organizationId, repositoryId) => request(config, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/repositories/${enc(repositoryId)}/contexts`),
+    getContext: (organizationId, id) => request(config, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(id)}`),
+    createContext: (organizationId, repositoryId, question) => request(config, fetchImpl, "POST", `/api/v1/organizations/${enc(organizationId)}/repositories/${enc(repositoryId)}/contexts`, { question }),
+    listFiles: (organizationId, contextId) => request(config, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(contextId)}/files`),
+    getFile: (organizationId, id) => request(config, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/files/${enc(id)}`),
+    createFile: (organizationId, contextId, file) => request(config, fetchImpl, "POST", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(contextId)}/files`, file),
+    deleteContext: (organizationId, id) => request(config, fetchImpl, "DELETE", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(id)}`)
+  };
+}
+
+// src/link.ts
+var REQUIRED_FLAGS = ["--organization-id", "--project-id", "--repository-id", "--api-key"];
+function parseLinkArgs(args) {
+  let organizationId;
+  let projectId;
+  let repositoryId;
+  let apiKey;
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--organization-id":
+        organizationId = args[++i];
+        if (!organizationId)
+          throw new CliUsageError("--organization-id needs a value");
+        break;
+      case "--project-id":
+        projectId = args[++i];
+        if (!projectId)
+          throw new CliUsageError("--project-id needs a value");
+        break;
+      case "--repository-id":
+        repositoryId = args[++i];
+        if (!repositoryId)
+          throw new CliUsageError("--repository-id needs a value");
+        break;
+      case "--api-key":
+        apiKey = args[++i];
+        if (!apiKey)
+          throw new CliUsageError("--api-key needs a value");
+        break;
+      default:
+        throw new CliUsageError(`unrecognised option "${arg}"`);
+    }
+  }
+  if (!organizationId || !projectId || !repositoryId || !apiKey) {
+    throw new CliUsageError(`link needs ${REQUIRED_FLAGS.join(", ")}, all required`);
+  }
+  return { organizationId, projectId, repositoryId, apiKey };
+}
+function writeNotexConfig(checkoutPath, config) {
+  atomicWriteFile(configFilePath(checkoutPath), JSON.stringify(config, null, 2), 384);
+}
+function describeValidationFailure(err, args) {
+  if (err instanceof OpError) {
+    switch (err.code) {
+      case ERROR_CODES.unauthorized:
+        return "Notex rejected the API key — generate a new one from Notex Settings → API keys and try again.";
+      case ERROR_CODES.forbidden:
+        return `Not authorized for repository ${args.repositoryId} in organization ${args.organizationId} — check the ids, or that your API key's owner holds a Grant on this Project.`;
+      case ERROR_CODES.notFound:
+        return `Repository ${args.repositoryId} was not found in organization ${args.organizationId} — check the ids from Notex Settings.`;
+      default:
+        return `Could not verify with the Notex API: ${err.message}`;
+    }
+  }
+  return `Could not verify with the Notex API: ${err instanceof Error ? err.message : String(err)}`;
+}
+async function link(args, opts = { checkoutPath: process.cwd() }) {
+  const client = createNotexClient({ baseUrl: resolveApiUrl(), apiKey: args.apiKey }, opts.fetchImpl);
+  let repository;
+  try {
+    repository = await client.getRepository(args.organizationId, args.repositoryId);
+  } catch (err) {
+    throw new CliUsageError(describeValidationFailure(err, args));
+  }
+  if (repository.projectId !== args.projectId) {
+    throw new CliUsageError(`Repository ${args.repositoryId} belongs to project ${repository.projectId}, not ${args.projectId} — check the ids from Notex Settings.`);
+  }
+  writeNotexConfig(opts.checkoutPath, {
+    organizationId: args.organizationId,
+    projectId: args.projectId,
+    repositoryId: args.repositoryId,
+    apiKey: args.apiKey
+  });
+}
+
 // src/graph.ts
 import { createHash } from "node:crypto";
 import { execSync } from "node:child_process";
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync as readFileSync2, statSync } from "node:fs";
 import { resolve } from "node:path";
 
 // src/scoring.ts
@@ -6574,28 +6767,6 @@ function scoreNodes(index, queryTerms) {
   return scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
 }
 
-// src/types.ts
-var ERROR_CODES = {
-  unauthorized: "unauthorized",
-  notFound: "not_found",
-  graphUnreadable: "graph_unreadable",
-  invalidRequest: "invalid_request",
-  graphLoading: "graph_loading",
-  forbidden: "forbidden",
-  notexApiError: "notex_api_error"
-};
-
-class OpError extends Error {
-  code;
-  detail;
-  constructor(code, message, detail) {
-    super(message);
-    this.name = "OpError";
-    this.code = code;
-    this.detail = detail;
-  }
-}
-
 // src/graph.ts
 function rootPrefixFor(checkoutPath, graphRoot) {
   if (graphRoot === checkoutPath)
@@ -6607,7 +6778,7 @@ function rootPrefixFor(checkoutPath, graphRoot) {
 }
 function readGraphRoot(checkoutPath) {
   try {
-    return readFileSync(resolve(checkoutPath, "graphify-out/.graphify_root"), "utf8").trim();
+    return readFileSync2(resolve(checkoutPath, "graphify-out/.graphify_root"), "utf8").trim();
   } catch {
     return checkoutPath;
   }
@@ -6623,7 +6794,7 @@ function loadGraph(checkoutPath) {
   const graphPath = resolve(checkoutPath, "graphify-out/graph.json");
   let raw;
   try {
-    raw = readFileSync(graphPath, "utf8");
+    raw = readFileSync2(graphPath, "utf8");
   } catch (err) {
     throw new OpError("graph_unreadable", `graph.json not found at ${graphPath}`, err);
   }
@@ -7194,8 +7365,8 @@ function startNodeServer(opts) {
 }
 async function handleRequest(req, res, fetch2) {
   try {
-    const request = await toWebRequest(req);
-    const response = await fetch2(request);
+    const request2 = await toWebRequest(req);
+    const response = await fetch2(request2);
     res.statusCode = response.status;
     response.headers.forEach((value, key) => res.setHeader(key, value));
     res.end(Buffer.from(await response.arrayBuffer()));
@@ -7231,18 +7402,18 @@ async function toWebRequest(req) {
 }
 
 // src/pairing.ts
-import { mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { dirname, join } from "node:path";
+import { dirname as dirname2, join as join2 } from "node:path";
 function pairingFilePath(checkoutPath) {
-  return join(checkoutPath, ".notex", "companion.json");
+  return join2(checkoutPath, ".notex", "companion.json");
 }
 function generateToken() {
   return randomBytes(32).toString("base64url");
 }
 function readExistingToken(path2) {
   try {
-    const parsed = JSON.parse(readFileSync2(path2, "utf8"));
+    const parsed = JSON.parse(readFileSync3(path2, "utf8"));
     return typeof parsed.token === "string" ? parsed.token : undefined;
   } catch {
     return;
@@ -7252,14 +7423,11 @@ function tokenContents(token) {
   return JSON.stringify({ token }, null, 2);
 }
 function createTokenFileExclusive(path2, token) {
-  mkdirSync(dirname(path2), { recursive: true });
-  writeFileSync(path2, tokenContents(token), { mode: 384, flag: "wx" });
+  mkdirSync2(dirname2(path2), { recursive: true });
+  writeFileSync2(path2, tokenContents(token), { mode: 384, flag: "wx" });
 }
 function rewriteTokenFile(path2, token) {
-  mkdirSync(dirname(path2), { recursive: true });
-  const tmpPath = `${path2}.${process.pid}.tmp`;
-  writeFileSync(tmpPath, tokenContents(token), { mode: 384, flag: "wx" });
-  renameSync(tmpPath, path2);
+  atomicWriteFile(path2, tokenContents(token), 384);
 }
 function loadOrCreateToken(checkoutPath, opts = {}) {
   const path2 = pairingFilePath(checkoutPath);
@@ -16474,14 +16642,14 @@ var CompleteRequestSchema = RequestSchema.extend({
   method: literal("completion/complete"),
   params: CompleteRequestParamsSchema
 });
-function assertCompleteRequestPrompt(request) {
-  if (request.params.ref.type !== "ref/prompt") {
-    throw new TypeError(`Expected CompleteRequestPrompt, but got ${request.params.ref.type}`);
+function assertCompleteRequestPrompt(request2) {
+  if (request2.params.ref.type !== "ref/prompt") {
+    throw new TypeError(`Expected CompleteRequestPrompt, but got ${request2.params.ref.type}`);
   }
 }
-function assertCompleteRequestResourceTemplate(request) {
-  if (request.params.ref.type !== "ref/resource") {
-    throw new TypeError(`Expected CompleteRequestResourceTemplate, but got ${request.params.ref.type}`);
+function assertCompleteRequestResourceTemplate(request2) {
+  if (request2.params.ref.type !== "ref/resource") {
+    throw new TypeError(`Expected CompleteRequestResourceTemplate, but got ${request2.params.ref.type}`);
   }
 }
 var CompleteResultSchema = ResultSchema.extend({
@@ -17918,8 +18086,8 @@ class Protocol {
     this._taskStore = _options?.taskStore;
     this._taskMessageQueue = _options?.taskMessageQueue;
     if (this._taskStore) {
-      this.setRequestHandler(GetTaskRequestSchema, async (request, extra) => {
-        const task = await this._taskStore.getTask(request.params.taskId, extra.sessionId);
+      this.setRequestHandler(GetTaskRequestSchema, async (request2, extra) => {
+        const task = await this._taskStore.getTask(request2.params.taskId, extra.sessionId);
         if (!task) {
           throw new McpError(ErrorCode.InvalidParams, "Failed to retrieve task: Task not found");
         }
@@ -17927,9 +18095,9 @@ class Protocol {
           ...task
         };
       });
-      this.setRequestHandler(GetTaskPayloadRequestSchema, async (request, extra) => {
+      this.setRequestHandler(GetTaskPayloadRequestSchema, async (request2, extra) => {
         const handleTaskResult = async () => {
-          const taskId = request.params.taskId;
+          const taskId = request2.params.taskId;
           if (this._taskMessageQueue) {
             let queuedMessage;
             while (queuedMessage = await this._taskMessageQueue.dequeue(taskId, extra.sessionId)) {
@@ -17980,9 +18148,9 @@ class Protocol {
         };
         return await handleTaskResult();
       });
-      this.setRequestHandler(ListTasksRequestSchema, async (request, extra) => {
+      this.setRequestHandler(ListTasksRequestSchema, async (request2, extra) => {
         try {
-          const { tasks, nextCursor } = await this._taskStore.listTasks(request.params?.cursor, extra.sessionId);
+          const { tasks, nextCursor } = await this._taskStore.listTasks(request2.params?.cursor, extra.sessionId);
           return {
             tasks,
             nextCursor,
@@ -17992,20 +18160,20 @@ class Protocol {
           throw new McpError(ErrorCode.InvalidParams, `Failed to list tasks: ${error2 instanceof Error ? error2.message : String(error2)}`);
         }
       });
-      this.setRequestHandler(CancelTaskRequestSchema, async (request, extra) => {
+      this.setRequestHandler(CancelTaskRequestSchema, async (request2, extra) => {
         try {
-          const task = await this._taskStore.getTask(request.params.taskId, extra.sessionId);
+          const task = await this._taskStore.getTask(request2.params.taskId, extra.sessionId);
           if (!task) {
-            throw new McpError(ErrorCode.InvalidParams, `Task not found: ${request.params.taskId}`);
+            throw new McpError(ErrorCode.InvalidParams, `Task not found: ${request2.params.taskId}`);
           }
           if (isTerminal(task.status)) {
             throw new McpError(ErrorCode.InvalidParams, `Cannot cancel task in terminal status: ${task.status}`);
           }
-          await this._taskStore.updateTaskStatus(request.params.taskId, "cancelled", "Client cancelled task execution.", extra.sessionId);
-          this._clearTaskQueue(request.params.taskId);
-          const cancelledTask = await this._taskStore.getTask(request.params.taskId, extra.sessionId);
+          await this._taskStore.updateTaskStatus(request2.params.taskId, "cancelled", "Client cancelled task execution.", extra.sessionId);
+          this._clearTaskQueue(request2.params.taskId);
+          const cancelledTask = await this._taskStore.getTask(request2.params.taskId, extra.sessionId);
           if (!cancelledTask) {
-            throw new McpError(ErrorCode.InvalidParams, `Task not found after cancellation: ${request.params.taskId}`);
+            throw new McpError(ErrorCode.InvalidParams, `Task not found after cancellation: ${request2.params.taskId}`);
           }
           return {
             _meta: {},
@@ -18121,14 +18289,14 @@ class Protocol {
     }
     Promise.resolve().then(() => handler(notification)).catch((error2) => this._onerror(new Error(`Uncaught error in notification handler: ${error2}`)));
   }
-  _onrequest(request, extra) {
-    const handler = this._requestHandlers.get(request.method) ?? this.fallbackRequestHandler;
+  _onrequest(request2, extra) {
+    const handler = this._requestHandlers.get(request2.method) ?? this.fallbackRequestHandler;
     const capturedTransport = this._transport;
-    const relatedTaskId = request.params?._meta?.[RELATED_TASK_META_KEY]?.taskId;
+    const relatedTaskId = request2.params?._meta?.[RELATED_TASK_META_KEY]?.taskId;
     if (handler === undefined) {
       const errorResponse = {
         jsonrpc: "2.0",
-        id: request.id,
+        id: request2.id,
         error: {
           code: ErrorCode.MethodNotFound,
           message: "Method not found"
@@ -18146,17 +18314,17 @@ class Protocol {
       return;
     }
     const abortController = new AbortController;
-    this._requestHandlerAbortControllers.set(request.id, abortController);
-    const taskCreationParams = isTaskAugmentedRequestParams(request.params) ? request.params.task : undefined;
-    const taskStore = this._taskStore ? this.requestTaskStore(request, capturedTransport?.sessionId) : undefined;
+    this._requestHandlerAbortControllers.set(request2.id, abortController);
+    const taskCreationParams = isTaskAugmentedRequestParams(request2.params) ? request2.params.task : undefined;
+    const taskStore = this._taskStore ? this.requestTaskStore(request2, capturedTransport?.sessionId) : undefined;
     const fullExtra = {
       signal: abortController.signal,
       sessionId: capturedTransport?.sessionId,
-      _meta: request.params?._meta,
+      _meta: request2.params?._meta,
       sendNotification: async (notification) => {
         if (abortController.signal.aborted)
           return;
-        const notificationOptions = { relatedRequestId: request.id };
+        const notificationOptions = { relatedRequestId: request2.id };
         if (relatedTaskId) {
           notificationOptions.relatedTask = { taskId: relatedTaskId };
         }
@@ -18166,7 +18334,7 @@ class Protocol {
         if (abortController.signal.aborted) {
           throw new McpError(ErrorCode.ConnectionClosed, "Request was cancelled");
         }
-        const requestOptions = { ...options, relatedRequestId: request.id };
+        const requestOptions = { ...options, relatedRequestId: request2.id };
         if (relatedTaskId && !requestOptions.relatedTask) {
           requestOptions.relatedTask = { taskId: relatedTaskId };
         }
@@ -18177,7 +18345,7 @@ class Protocol {
         return await this.request(r, resultSchema, requestOptions);
       },
       authInfo: extra?.authInfo,
-      requestId: request.id,
+      requestId: request2.id,
       requestInfo: extra?.requestInfo,
       taskId: relatedTaskId,
       taskStore,
@@ -18187,16 +18355,16 @@ class Protocol {
     };
     Promise.resolve().then(() => {
       if (taskCreationParams) {
-        this.assertTaskHandlerCapability(request.method);
+        this.assertTaskHandlerCapability(request2.method);
       }
-    }).then(() => handler(request, fullExtra)).then(async (result) => {
+    }).then(() => handler(request2, fullExtra)).then(async (result) => {
       if (abortController.signal.aborted) {
         return;
       }
       const response = {
         result,
         jsonrpc: "2.0",
-        id: request.id
+        id: request2.id
       };
       if (relatedTaskId && this._taskMessageQueue) {
         await this._enqueueTaskMessage(relatedTaskId, {
@@ -18213,7 +18381,7 @@ class Protocol {
       }
       const errorResponse = {
         jsonrpc: "2.0",
-        id: request.id,
+        id: request2.id,
         error: {
           code: Number.isSafeInteger(error2["code"]) ? error2["code"] : ErrorCode.InternalError,
           message: error2.message ?? "Internal error",
@@ -18230,8 +18398,8 @@ class Protocol {
         await capturedTransport?.send(errorResponse);
       }
     }).catch((error2) => this._onerror(new Error(`Failed to send response: ${error2}`))).finally(() => {
-      if (this._requestHandlerAbortControllers.get(request.id) === abortController) {
-        this._requestHandlerAbortControllers.delete(request.id);
+      if (this._requestHandlerAbortControllers.get(request2.id) === abortController) {
+        this._requestHandlerAbortControllers.delete(request2.id);
       }
     });
   }
@@ -18305,11 +18473,11 @@ class Protocol {
   async close() {
     await this._transport?.close();
   }
-  async* requestStream(request, resultSchema, options) {
+  async* requestStream(request2, resultSchema, options) {
     const { task } = options ?? {};
     if (!task) {
       try {
-        const result = await this.request(request, resultSchema, options);
+        const result = await this.request(request2, resultSchema, options);
         yield { type: "result", result };
       } catch (error2) {
         yield {
@@ -18321,7 +18489,7 @@ class Protocol {
     }
     let taskId;
     try {
-      const createResult = await this.request(request, CreateTaskResultSchema, options);
+      const createResult = await this.request(request2, CreateTaskResultSchema, options);
       if (createResult.task) {
         taskId = createResult.task.taskId;
         yield { type: "taskCreated", task: createResult.task };
@@ -18364,7 +18532,7 @@ class Protocol {
       };
     }
   }
-  request(request, resultSchema, options) {
+  request(request2, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
     return new Promise((resolve2, reject) => {
       const earlyReject = (error2) => {
@@ -18376,9 +18544,9 @@ class Protocol {
       }
       if (this._options?.enforceStrictCapabilities === true) {
         try {
-          this.assertCapabilityForMethod(request.method);
+          this.assertCapabilityForMethod(request2.method);
           if (task) {
-            this.assertTaskCapability(request.method);
+            this.assertTaskCapability(request2.method);
           }
         } catch (e) {
           earlyReject(e);
@@ -18388,16 +18556,16 @@ class Protocol {
       options?.signal?.throwIfAborted();
       const messageId = this._requestMessageId++;
       const jsonrpcRequest = {
-        ...request,
+        ...request2,
         jsonrpc: "2.0",
         id: messageId
       };
       if (options?.onprogress) {
         this._progressHandlers.set(messageId, options.onprogress);
         jsonrpcRequest.params = {
-          ...request.params,
+          ...request2.params,
           _meta: {
-            ...request.params?._meta || {},
+            ...request2.params?._meta || {},
             progressToken: messageId
           }
         };
@@ -18573,8 +18741,8 @@ class Protocol {
   setRequestHandler(requestSchema, handler) {
     const method = getMethodLiteral(requestSchema);
     this.assertRequestHandlerCapability(method);
-    this._requestHandlers.set(method, (request, extra) => {
-      const parsed = parseWithCompat(requestSchema, request);
+    this._requestHandlers.set(method, (request2, extra) => {
+      const parsed = parseWithCompat(requestSchema, request2);
       return Promise.resolve(handler(parsed, extra));
     });
   }
@@ -18647,19 +18815,19 @@ class Protocol {
       }, { once: true });
     });
   }
-  requestTaskStore(request, sessionId) {
+  requestTaskStore(request2, sessionId) {
     const taskStore = this._taskStore;
     if (!taskStore) {
       throw new Error("No task store configured");
     }
     return {
       createTask: async (taskParams) => {
-        if (!request) {
+        if (!request2) {
           throw new Error("No request provided");
         }
-        return await taskStore.createTask(taskParams, request.id, {
-          method: request.method,
-          params: request.params
+        return await taskStore.createTask(taskParams, request2.id, {
+          method: request2.method,
+          params: request2.params
         }, sessionId);
       },
       getTask: async (taskId) => {
@@ -18778,8 +18946,8 @@ class ExperimentalServerTasks {
   constructor(_server) {
     this._server = _server;
   }
-  requestStream(request, resultSchema, options) {
-    return this._server.requestStream(request, resultSchema, options);
+  requestStream(request2, resultSchema, options) {
+    return this._server.requestStream(request2, resultSchema, options);
   }
   createMessageStream(params, options) {
     const clientCapabilities = this._server.getClientCapabilities();
@@ -18900,12 +19068,12 @@ class Server extends Protocol {
     this._capabilities = options?.capabilities ?? {};
     this._instructions = options?.instructions;
     this._jsonSchemaValidator = options?.jsonSchemaValidator ?? new AjvJsonSchemaValidator;
-    this.setRequestHandler(InitializeRequestSchema, (request) => this._oninitialize(request));
+    this.setRequestHandler(InitializeRequestSchema, (request2) => this._oninitialize(request2));
     this.setNotificationHandler(InitializedNotificationSchema, () => this.oninitialized?.());
     if (this._capabilities.logging) {
-      this.setRequestHandler(SetLevelRequestSchema, async (request, extra) => {
+      this.setRequestHandler(SetLevelRequestSchema, async (request2, extra) => {
         const transportSessionId = extra.sessionId || extra.requestInfo?.headers["mcp-session-id"] || undefined;
-        const { level } = request.params;
+        const { level } = request2.params;
         const parseResult = LoggingLevelSchema.safeParse(level);
         if (parseResult.success) {
           this._loggingLevels.set(transportSessionId, parseResult.data);
@@ -18949,14 +19117,14 @@ class Server extends Protocol {
     }
     const method = methodValue;
     if (method === "tools/call") {
-      const wrappedHandler = async (request, extra) => {
-        const validatedRequest = safeParse2(CallToolRequestSchema, request);
+      const wrappedHandler = async (request2, extra) => {
+        const validatedRequest = safeParse2(CallToolRequestSchema, request2);
         if (!validatedRequest.success) {
           const errorMessage = validatedRequest.error instanceof Error ? validatedRequest.error.message : String(validatedRequest.error);
           throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call request: ${errorMessage}`);
         }
         const { params } = validatedRequest.data;
-        const result = await Promise.resolve(handler(request, extra));
+        const result = await Promise.resolve(handler(request2, extra));
         if (params.task) {
           const taskValidationResult = safeParse2(CreateTaskResultSchema, result);
           if (!taskValidationResult.success) {
@@ -19087,10 +19255,10 @@ class Server extends Protocol {
     }
     assertToolsCallTaskCapability(this._capabilities.tasks?.requests, method, "Server");
   }
-  async _oninitialize(request) {
-    const requestedVersion = request.params.protocolVersion;
-    this._clientCapabilities = request.params.capabilities;
-    this._clientVersion = request.params.clientInfo;
+  async _oninitialize(request2) {
+    const requestedVersion = request2.params.protocolVersion;
+    this._clientCapabilities = request2.params.capabilities;
+    this._clientVersion = request2.params.clientInfo;
     const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(requestedVersion) ? requestedVersion : LATEST_PROTOCOL_VERSION;
     return {
       protocolVersion,
@@ -19373,33 +19541,33 @@ class McpServer {
         return toolDefinition;
       })
     }));
-    this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    this.server.setRequestHandler(CallToolRequestSchema, async (request2, extra) => {
       try {
-        const tool = this._registeredTools[request.params.name];
+        const tool = this._registeredTools[request2.params.name];
         if (!tool) {
-          throw new McpError(ErrorCode.InvalidParams, `Tool ${request.params.name} not found`);
+          throw new McpError(ErrorCode.InvalidParams, `Tool ${request2.params.name} not found`);
         }
         if (!tool.enabled) {
-          throw new McpError(ErrorCode.InvalidParams, `Tool ${request.params.name} disabled`);
+          throw new McpError(ErrorCode.InvalidParams, `Tool ${request2.params.name} disabled`);
         }
-        const isTaskRequest = !!request.params.task;
+        const isTaskRequest = !!request2.params.task;
         const taskSupport = tool.execution?.taskSupport;
         const isTaskHandler = "createTask" in tool.handler;
         if ((taskSupport === "required" || taskSupport === "optional") && !isTaskHandler) {
-          throw new McpError(ErrorCode.InternalError, `Tool ${request.params.name} has taskSupport '${taskSupport}' but was not registered with registerToolTask`);
+          throw new McpError(ErrorCode.InternalError, `Tool ${request2.params.name} has taskSupport '${taskSupport}' but was not registered with registerToolTask`);
         }
         if (taskSupport === "required" && !isTaskRequest) {
-          throw new McpError(ErrorCode.MethodNotFound, `Tool ${request.params.name} requires task augmentation (taskSupport: 'required')`);
+          throw new McpError(ErrorCode.MethodNotFound, `Tool ${request2.params.name} requires task augmentation (taskSupport: 'required')`);
         }
         if (taskSupport === "optional" && !isTaskRequest && isTaskHandler) {
-          return await this.handleAutomaticTaskPolling(tool, request, extra);
+          return await this.handleAutomaticTaskPolling(tool, request2, extra);
         }
-        const args = await this.validateToolInput(tool, request.params.arguments, request.params.name);
+        const args = await this.validateToolInput(tool, request2.params.arguments, request2.params.name);
         const result = await this.executeToolHandler(tool, args, extra);
         if (isTaskRequest) {
           return result;
         }
-        await this.validateToolOutput(tool, result, request.params.name);
+        await this.validateToolOutput(tool, result, request2.params.name);
         return result;
       } catch (error2) {
         if (error2 instanceof McpError) {
@@ -19482,11 +19650,11 @@ class McpServer {
       return await Promise.resolve(typedHandler(extra));
     }
   }
-  async handleAutomaticTaskPolling(tool, request, extra) {
+  async handleAutomaticTaskPolling(tool, request2, extra) {
     if (!extra.taskStore) {
       throw new Error("No task store provided for task-capable tool.");
     }
-    const args = await this.validateToolInput(tool, request.params.arguments, request.params.name);
+    const args = await this.validateToolInput(tool, request2.params.arguments, request2.params.name);
     const handler = tool.handler;
     const taskExtra = { ...extra, taskStore: extra.taskStore };
     const createTaskResult = args ? await Promise.resolve(handler.createTask(args, taskExtra)) : await Promise.resolve(handler.createTask(taskExtra));
@@ -19511,21 +19679,21 @@ class McpServer {
     this.server.registerCapabilities({
       completions: {}
     });
-    this.server.setRequestHandler(CompleteRequestSchema, async (request) => {
-      switch (request.params.ref.type) {
+    this.server.setRequestHandler(CompleteRequestSchema, async (request2) => {
+      switch (request2.params.ref.type) {
         case "ref/prompt":
-          assertCompleteRequestPrompt(request);
-          return this.handlePromptCompletion(request, request.params.ref);
+          assertCompleteRequestPrompt(request2);
+          return this.handlePromptCompletion(request2, request2.params.ref);
         case "ref/resource":
-          assertCompleteRequestResourceTemplate(request);
-          return this.handleResourceCompletion(request, request.params.ref);
+          assertCompleteRequestResourceTemplate(request2);
+          return this.handleResourceCompletion(request2, request2.params.ref);
         default:
-          throw new McpError(ErrorCode.InvalidParams, `Invalid completion reference: ${request.params.ref}`);
+          throw new McpError(ErrorCode.InvalidParams, `Invalid completion reference: ${request2.params.ref}`);
       }
     });
     this._completionHandlerInitialized = true;
   }
-  async handlePromptCompletion(request, ref) {
+  async handlePromptCompletion(request2, ref) {
     const prompt = this._registeredPrompts[ref.name];
     if (!prompt) {
       throw new McpError(ErrorCode.InvalidParams, `Prompt ${ref.name} not found`);
@@ -19537,7 +19705,7 @@ class McpServer {
       return EMPTY_COMPLETION_RESULT;
     }
     const promptShape = getObjectShape(prompt.argsSchema);
-    const field = promptShape?.[request.params.argument.name];
+    const field = promptShape?.[request2.params.argument.name];
     if (!isCompletable(field)) {
       return EMPTY_COMPLETION_RESULT;
     }
@@ -19545,22 +19713,22 @@ class McpServer {
     if (!completer) {
       return EMPTY_COMPLETION_RESULT;
     }
-    const suggestions = await completer(request.params.argument.value, request.params.context);
+    const suggestions = await completer(request2.params.argument.value, request2.params.context);
     return createCompletionResult(suggestions);
   }
-  async handleResourceCompletion(request, ref) {
+  async handleResourceCompletion(request2, ref) {
     const template = Object.values(this._registeredResourceTemplates).find((t) => t.resourceTemplate.uriTemplate.toString() === ref.uri);
     if (!template) {
       if (this._registeredResources[ref.uri]) {
         return EMPTY_COMPLETION_RESULT;
       }
-      throw new McpError(ErrorCode.InvalidParams, `Resource template ${request.params.ref.uri} not found`);
+      throw new McpError(ErrorCode.InvalidParams, `Resource template ${request2.params.ref.uri} not found`);
     }
-    const completer = template.resourceTemplate.completeCallback(request.params.argument.name);
+    const completer = template.resourceTemplate.completeCallback(request2.params.argument.name);
     if (!completer) {
       return EMPTY_COMPLETION_RESULT;
     }
-    const suggestions = await completer(request.params.argument.value, request.params.context);
+    const suggestions = await completer(request2.params.argument.value, request2.params.context);
     return createCompletionResult(suggestions);
   }
   setResourceRequestHandlers() {
@@ -19575,7 +19743,7 @@ class McpServer {
         listChanged: true
       }
     });
-    this.server.setRequestHandler(ListResourcesRequestSchema, async (request, extra) => {
+    this.server.setRequestHandler(ListResourcesRequestSchema, async (request2, extra) => {
       const resources = Object.entries(this._registeredResources).filter(([_, resource]) => resource.enabled).map(([uri, resource]) => ({
         uri,
         name: resource.name,
@@ -19604,8 +19772,8 @@ class McpServer {
       }));
       return { resourceTemplates };
     });
-    this.server.setRequestHandler(ReadResourceRequestSchema, async (request, extra) => {
-      const uri = new URL(request.params.uri);
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request2, extra) => {
+      const uri = new URL(request2.params.uri);
       const resource = this._registeredResources[uri.toString()];
       if (resource) {
         if (!resource.enabled) {
@@ -19644,21 +19812,21 @@ class McpServer {
         };
       })
     }));
-    this.server.setRequestHandler(GetPromptRequestSchema, async (request, extra) => {
-      const prompt = this._registeredPrompts[request.params.name];
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request2, extra) => {
+      const prompt = this._registeredPrompts[request2.params.name];
       if (!prompt) {
-        throw new McpError(ErrorCode.InvalidParams, `Prompt ${request.params.name} not found`);
+        throw new McpError(ErrorCode.InvalidParams, `Prompt ${request2.params.name} not found`);
       }
       if (!prompt.enabled) {
-        throw new McpError(ErrorCode.InvalidParams, `Prompt ${request.params.name} disabled`);
+        throw new McpError(ErrorCode.InvalidParams, `Prompt ${request2.params.name} disabled`);
       }
       if (prompt.argsSchema) {
         const argsObj = normalizeObjectSchema(prompt.argsSchema);
-        const parseResult = await safeParseAsync2(argsObj, request.params.arguments);
+        const parseResult = await safeParseAsync2(argsObj, request2.params.arguments);
         if (!parseResult.success) {
           const error2 = "error" in parseResult ? parseResult.error : "Unknown error";
           const errorMessage = getParseErrorMessage(error2);
-          throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for prompt ${request.params.name}: ${errorMessage}`);
+          throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for prompt ${request2.params.name}: ${errorMessage}`);
         }
         const args = parseResult.data;
         const cb = prompt.callback;
@@ -32396,8 +32564,8 @@ function hex2(_params) {
   return _stringFormat2(ZodCustomStringFormat, "hex", exports_regexes2.hex, _params);
 }
 function hash(alg, params) {
-  const enc = params?.enc ?? "hex";
-  const format = `${alg}_${enc}`;
+  const enc2 = params?.enc ?? "hex";
+  const format = `${alg}_${enc2}`;
   const regex = exports_regexes2[format];
   if (!regex)
     throw new Error(`Unrecognized hash format: ${format}`);
@@ -33967,86 +34135,6 @@ ${answers.length} answer(s)`;
   };
 }
 
-// src/notexClient.ts
-var DEFAULT_API_URL = "http://localhost:3000";
-function resolveApiUrl(env = process.env) {
-  return env.NOTEX_API_URL?.trim() || DEFAULT_API_URL;
-}
-async function request(config3, fetchImpl, method, path2, body) {
-  let res;
-  try {
-    res = await fetchImpl(`${config3.baseUrl}${path2}`, {
-      method,
-      headers: {
-        "x-api-key": config3.apiKey,
-        ...body !== undefined ? { "content-type": "application/json" } : {}
-      },
-      body: body !== undefined ? JSON.stringify(body) : undefined
-    });
-  } catch (err) {
-    throw new OpError(ERROR_CODES.notexApiError, `Could not reach the Notex API at ${config3.baseUrl}`, err);
-  }
-  if (res.status === 401)
-    throw new OpError(ERROR_CODES.unauthorized, "Notex rejected the API key");
-  if (res.status === 403)
-    throw new OpError(ERROR_CODES.forbidden, "Not authorized for this Project");
-  if (res.status === 404)
-    throw new OpError(ERROR_CODES.notFound, "Not found in Notex");
-  if (!res.ok) {
-    const body2 = await res.json().catch(() => ({}));
-    throw new OpError(ERROR_CODES.notexApiError, body2.error?.message ?? `Notex API error (HTTP ${res.status})`);
-  }
-  return await res.json();
-}
-var enc = (id) => encodeURIComponent(id);
-function createNotexClient(config3, fetchImpl = fetch) {
-  return {
-    listContexts: (organizationId, repositoryId) => request(config3, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/repositories/${enc(repositoryId)}/contexts`),
-    getContext: (organizationId, id) => request(config3, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(id)}`),
-    createContext: (organizationId, repositoryId, question) => request(config3, fetchImpl, "POST", `/api/v1/organizations/${enc(organizationId)}/repositories/${enc(repositoryId)}/contexts`, { question }),
-    listFiles: (organizationId, contextId) => request(config3, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(contextId)}/files`),
-    getFile: (organizationId, id) => request(config3, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/files/${enc(id)}`),
-    createFile: (organizationId, contextId, file2) => request(config3, fetchImpl, "POST", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(contextId)}/files`, file2),
-    deleteContext: (organizationId, id) => request(config3, fetchImpl, "DELETE", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(id)}`)
-  };
-}
-
-// src/notexConfig.ts
-import { readFileSync as readFileSync3 } from "node:fs";
-import { join as join2 } from "node:path";
-function configFilePath(checkoutPath) {
-  return join2(checkoutPath, ".notex", "notex.json");
-}
-function nonEmptyString(value) {
-  return typeof value === "string" && value.length > 0;
-}
-function loadNotexConfig(checkoutPath, env = process.env) {
-  let raw;
-  try {
-    raw = readFileSync3(configFilePath(checkoutPath), "utf8");
-  } catch {
-    return { kind: "unlinked", reason: "no .notex/notex.json found" };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return { kind: "unlinked", reason: ".notex/notex.json is not valid JSON" };
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    return { kind: "unlinked", reason: ".notex/notex.json must be a JSON object" };
-  }
-  const { organizationId, projectId, repositoryId, apiKey } = parsed;
-  if (!nonEmptyString(organizationId) || !nonEmptyString(projectId) || !nonEmptyString(repositoryId)) {
-    return { kind: "unlinked", reason: ".notex/notex.json is missing organizationId, projectId, or repositoryId" };
-  }
-  const resolvedKey = nonEmptyString(env.NOTEX_API_KEY) ? env.NOTEX_API_KEY : apiKey;
-  if (!nonEmptyString(resolvedKey)) {
-    return { kind: "unlinked", reason: ".notex/notex.json is missing apiKey, and NOTEX_API_KEY is not set" };
-  }
-  return { kind: "linked", config: { organizationId, projectId, repositoryId, apiKey: resolvedKey } };
-}
-
 // src/retrievalLog.ts
 function createRetrievalLog() {
   const seen = new Set;
@@ -34095,16 +34183,20 @@ var HELP = `notex-companion — local retrieval companion over a checkout's grap
 Usage:
   notex-companion [serve] [options]   Start the loopback HTTP server (default command)
   notex-companion mcp                 Start the stdio MCP server
+  notex-companion link [options]      Write .notex/notex.json, pairing this checkout to a Notex Repository
 
 Options for serve:
   --port <n>       Port to bind (default 7717)
   --origin <url>   Additional allowed CORS origin, beyond the built-in defaults. Repeatable.
   --rotate-token   Generate a new pairing token, invalidating the old one
   -h, --help       Show this message
-`;
 
-class CliUsageError extends Error {
-}
+Options for link (all required):
+  --organization-id <id>
+  --project-id <id>
+  --repository-id <id>
+  --api-key <key>   Generated from Notex Settings → API keys
+`;
 function parseServeArgs(args) {
   const origins = [];
   let port;
@@ -34137,6 +34229,17 @@ function parseServeArgs(args) {
   }
   return { port, origins, rotateToken };
 }
+function runLink(args) {
+  const parsed = parseLinkArgs(args);
+  const checkoutPath = process.cwd();
+  link(parsed, { checkoutPath }).then(() => {
+    console.log(`notex-companion: linked ${checkoutPath} to repository ${parsed.repositoryId}`);
+    console.log("notex-companion: wrote .notex/notex.json (mode 0600)");
+  }, (err) => {
+    console.error(`notex-companion link: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  });
+}
 function runMcp() {
   startMcpServer(process.cwd()).catch((err) => {
     console.error(`notex-companion mcp: failed to start: ${err instanceof Error ? err.message : String(err)}`);
@@ -34178,6 +34281,8 @@ function main(argv = process.argv.slice(2)) {
   try {
     if (command === "mcp") {
       runMcp();
+    } else if (command === "link") {
+      runLink(rest);
     } else if (command === undefined || command === "serve" || command.startsWith("-")) {
       runServe(command === "serve" ? rest : argv);
     } else {

package/dist/cliErrors.d.ts

@@ -0,0 +1,3 @@
+/** Thrown by argument parsing on bad input — `main()` turns it into a stderr message + exit 1. */
+export declare class CliUsageError extends Error {
+}

package/dist/index.js

@@ -704,9 +704,21 @@ async function toWebRequest(req) {
 }
 
 // src/pairing.ts
-import { mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { dirname, join } from "node:path";
+import { dirname as dirname2, join } from "node:path";
+
+// src/atomicWrite.ts
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+function atomicWriteFile(path2, content, mode) {
+  mkdirSync(dirname(path2), { recursive: true });
+  const tmpPath = `${path2}.${process.pid}.tmp`;
+  writeFileSync(tmpPath, content, { mode, flag: "wx" });
+  renameSync(tmpPath, path2);
+}
+
+// src/pairing.ts
 function pairingFilePath(checkoutPath) {
   return join(checkoutPath, ".notex", "companion.json");
 }
@@ -725,14 +737,11 @@ function tokenContents(token) {
   return JSON.stringify({ token }, null, 2);
 }
 function createTokenFileExclusive(path2, token) {
-  mkdirSync(dirname(path2), { recursive: true });
-  writeFileSync(path2, tokenContents(token), { mode: 384, flag: "wx" });
+  mkdirSync2(dirname2(path2), { recursive: true });
+  writeFileSync2(path2, tokenContents(token), { mode: 384, flag: "wx" });
 }
 function rewriteTokenFile(path2, token) {
-  mkdirSync(dirname(path2), { recursive: true });
-  const tmpPath = `${path2}.${process.pid}.tmp`;
-  writeFileSync(tmpPath, tokenContents(token), { mode: 384, flag: "wx" });
-  renameSync(tmpPath, path2);
+  atomicWriteFile(path2, tokenContents(token), 384);
 }
 function loadOrCreateToken(checkoutPath, opts = {}) {
   const path2 = pairingFilePath(checkoutPath);

package/dist/link.d.ts

@@ -0,0 +1,15 @@
+export type LinkArgs = {
+    organizationId: string;
+    projectId: string;
+    repositoryId: string;
+    apiKey: string;
+};
+export declare function parseLinkArgs(args: Array<string>): LinkArgs;
+/**
+ * Validates `args` against the Notex API, then writes `.notex/notex.json`. Throws `CliUsageError`
+ * with an actionable message on bad input; writes nothing in that case.
+ */
+export declare function link(args: LinkArgs, opts?: {
+    checkoutPath: string;
+    fetchImpl?: typeof fetch;
+}): Promise<void>;

package/dist/notexClient.d.ts

@@ -12,6 +12,12 @@ export type NotexFile = {
     content: string;
     createdAt: string;
 };
+export type NotexRepository = {
+    id: string;
+    projectId: string;
+    name: string;
+    description: string | null;
+};
 export type NotexClientConfig = {
     baseUrl: string;
     apiKey: string;
@@ -23,6 +29,10 @@ export declare function resolveApiUrl(env?: {
     NOTEX_API_URL?: string;
 }): string;
 export declare function createNotexClient(config: NotexClientConfig, fetchImpl?: FetchImpl): {
+    /** Used by `link.ts` (TBR-85) to validate organizationId/repositoryId/apiKey together before
+     * writing `.notex/notex.json` — the returned `projectId` is checked against the one the user
+     * supplied, since no route accepts all three ids at once. */
+    getRepository: (organizationId: string, id: string) => Promise<NotexRepository>;
     listContexts: (organizationId: string, repositoryId: string) => Promise<NotexContext[]>;
     getContext: (organizationId: string, id: string) => Promise<NotexContext>;
     createContext: (organizationId: string, repositoryId: string, question: string) => Promise<NotexContext>;

package/dist/notexConfig.d.ts

@@ -11,6 +11,8 @@ export type NotexConfigState = {
     kind: "unlinked";
     reason: string;
 };
+/** Also used by `link.ts` (TBR-85), the sole writer of this path — this module is the sole reader. */
+export declare function configFilePath(checkoutPath: string): string;
 /** `NOTEX_API_KEY` overrides the file's `apiKey` (companion-api.md / notex-mcp-server.md §7). */
 export declare function loadNotexConfig(checkoutPath: string, env?: {
     NOTEX_API_KEY?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notex-companion",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Local retrieval companion for Notex — reads a checkout's graphify-out/graph.json and serves deterministic search/query/path/node lookups over loopback HTTP and MCP stdio. No LLM, no graph building, no network beyond 127.0.0.1.",
   "keywords": ["notex", "graphify", "mcp", "code-graph"],
   "license": "MIT",