@nram-ai/setup-agents 0.0.1-pre.0

package/dist/helpers/configure/cursor.js

@@ -0,0 +1,90 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure_cursor = exports.cursor_rule_file = exports.cursor_mcp_entry = void 0;
+const path_1 = require("path");
+const types_1 = require("../../types");
+const paths_1 = require("../paths");
+const upsert_1 = require("../upsert");
+/**
+ * Builds the `mcpServers.nram` entry for Cursor's mcp.json. In API-key mode
+ * the key is referenced through Cursor's `${env:...}` interpolation, never
+ * written to disk
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+const cursor_mcp_entry = (mcp_url, api_key) => {
+    const entry = { url: mcp_url };
+    if (api_key !== undefined) {
+        entry.headers = { Authorization: 'Bearer ${env:NRAM_API_KEY}' };
+    }
+    return entry;
+};
+exports.cursor_mcp_entry = cursor_mcp_entry;
+/**
+ * Builds the project rule file (`.cursor/rules/nram.mdc`) carrying the agent
+ * instructions; `alwaysApply: true` injects it into every Agent conversation
+ *
+ * @param instructions the agent instructions text
+ */
+const cursor_rule_file = (instructions) => '---\n' +
+    'description: nram (Neural Ram) persistent memory protocol\n' +
+    'alwaysApply: true\n' +
+    '---\n\n' +
+    `${instructions.trimEnd()}\n`;
+exports.cursor_rule_file = cursor_rule_file;
+/**
+ * Configures Cursor: merges the nram MCP server into mcp.json and, at project
+ * scope, writes the agent instructions as `.cursor/rules/nram.mdc`
+ * (`.cursorrules` is deprecated; user-level rules live only in the Cursor
+ * settings GUI, so the instruction half is reported and skipped at user scope)
+ *
+ * @param options the collected setup options
+ */
+const configure_cursor = async (options) => {
+    const results = [];
+    if (options.mcp_url !== undefined) {
+        const config_path = (0, path_1.resolve)((0, paths_1.cursor_dir)(options.scope), 'mcp.json');
+        const mcp = (0, upsert_1.mcp_json_result)(config_path, ['mcpServers', 'nram'], (0, exports.cursor_mcp_entry)(options.mcp_url, options.api_key));
+        results.push(mcp);
+        if (mcp.kind !== 'manual' && options.api_key !== undefined) {
+            results.push((0, upsert_1.api_key_manual_result)());
+        }
+    }
+    if (!options.instructions) {
+        return results;
+    }
+    if (options.scope !== types_1.Scope.PROJECT) {
+        results.push({
+            action: 'Agent instructions',
+            kind: 'skipped',
+            detail: 'Cursor has no file-based user-level rules (only Cursor Settings, Rules); ' +
+                'rerun at project scope to write .cursor/rules/nram.mdc instead'
+        });
+        return results;
+    }
+    const rule_path = (0, path_1.resolve)((0, paths_1.cursor_dir)(options.scope), 'rules', 'nram.mdc');
+    results.push((0, upsert_1.upsert_own_file)(rule_path, (0, exports.cursor_rule_file)(options.instructions.condensed), 'Agent instructions'));
+    return results;
+};
+exports.configure_cursor = configure_cursor;
+//# sourceMappingURL=cursor.js.map

package/dist/helpers/configure/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../src/helpers/configure/cursor.ts"],"names":[],"mappings":";AAAA,iEAAiE;AACjE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;;;AAEZ,+BAA+B;AAC/B,uCAAgE;AAChE,oCAAsC;AACtC,sCAAoF;AAEpF;;;;;;;GAOG;AACI,MAAM,gBAAgB,GAAG,CAAC,OAAe,EAAE,OAAgB,EAAO,EAAE;IACvE,MAAM,KAAK,GAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;IAEpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,KAAK,CAAC,OAAO,GAAG,EAAE,aAAa,EAAE,4BAA4B,EAAE,CAAC;IACpE,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC,CAAC;AARW,QAAA,gBAAgB,oBAQ3B;AAEF;;;;;GAKG;AACI,MAAM,gBAAgB,GAAG,CAAC,YAAoB,EAAU,EAAE,CAC7D,OAAO;IACP,6DAA6D;IAC7D,qBAAqB;IACrB,SAAS;IACT,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC;AALrB,QAAA,gBAAgB,oBAKK;AAElC;;;;;;;GAOG;AACI,MAAM,gBAAgB,GAAG,KAAK,EAAE,OAAqB,EAA2B,EAAE;IACrF,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,IAAA,cAAO,EAAC,IAAA,kBAAU,EAAC,OAAO,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC;QAEnE,MAAM,GAAG,GAAG,IAAA,wBAAe,EAAC,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,EAC3D,IAAA,wBAAgB,EAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAExD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAElB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACzD,OAAO,CAAC,IAAI,CAAC,IAAA,8BAAqB,GAAE,CAAC,CAAC;QAC1C,CAAC;IACL,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,KAAK,aAAK,CAAC,OAAO,EAAE,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC;YACT,MAAM,EAAE,oBAAoB;YAC5B,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,2EAA2E;gBAC/E,gEAAgE;SACvE,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,MAAM,SAAS,GAAG,IAAA,cAAO,EAAC,IAAA,kBAAU,EAAC,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAE1E,OAAO,CAAC,IAAI,CAAC,IAAA,wBAAe,EAAC,SAAS,EAAE,IAAA,wBAAgB,EAAC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAEjH,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC;AApCW,QAAA,gBAAgB,oBAoC3B"}

package/dist/helpers/configure/droid.d.ts

@@ -0,0 +1,18 @@
+import { ActionResult, SetupOptions } from '../../types';
+/**
+ * Builds the array element for Factory's mcp.json. Droid expands `${VAR}`
+ * references at load time, so the key never reaches disk
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+export declare const droid_mcp_entry: (mcp_url: string, api_key?: string) => any;
+/**
+ * Configures Droid (Factory): merges the nram MCP server into mcp.json
+ * (array-shaped `servers` list) and upserts the agent instructions into the
+ * AGENTS.md droid reads: `~/.factory/AGENTS.md` (documented personal
+ * override) at user scope, the repository root AGENTS.md at project scope
+ *
+ * @param options the collected setup options
+ */
+export declare const configure_droid: (options: SetupOptions) => Promise<ActionResult[]>;

package/dist/helpers/configure/droid.js

@@ -0,0 +1,70 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure_droid = exports.droid_mcp_entry = void 0;
+const path_1 = require("path");
+const paths_1 = require("../paths");
+const upsert_1 = require("../upsert");
+/**
+ * Builds the array element for Factory's mcp.json. Droid expands `${VAR}`
+ * references at load time, so the key never reaches disk
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+const droid_mcp_entry = (mcp_url, api_key) => {
+    const entry = {
+        name: 'nram',
+        type: 'http',
+        url: mcp_url
+    };
+    if (api_key !== undefined) {
+        entry.headers = { Authorization: 'Bearer ${NRAM_API_KEY}' };
+    }
+    return entry;
+};
+exports.droid_mcp_entry = droid_mcp_entry;
+/**
+ * Configures Droid (Factory): merges the nram MCP server into mcp.json
+ * (array-shaped `servers` list) and upserts the agent instructions into the
+ * AGENTS.md droid reads: `~/.factory/AGENTS.md` (documented personal
+ * override) at user scope, the repository root AGENTS.md at project scope
+ *
+ * @param options the collected setup options
+ */
+const configure_droid = async (options) => {
+    const results = [];
+    if (options.mcp_url !== undefined) {
+        const config_path = (0, path_1.resolve)((0, paths_1.factory_dir)(options.scope), 'mcp.json');
+        const entry = (0, exports.droid_mcp_entry)(options.mcp_url, options.api_key);
+        const mcp = (0, upsert_1.mcp_json_result)(config_path, ['servers'], entry, { array: true });
+        results.push(mcp);
+        if (mcp.kind !== 'manual' && options.api_key !== undefined) {
+            results.push((0, upsert_1.api_key_manual_result)());
+        }
+    }
+    if (options.instructions) {
+        results.push((0, upsert_1.agents_md_result)((0, paths_1.agents_md_path)(options.scope, (0, path_1.resolve)((0, paths_1.factory_dir)(options.scope), 'AGENTS.md')), options.instructions.full));
+    }
+    return results;
+};
+exports.configure_droid = configure_droid;
+//# sourceMappingURL=droid.js.map

package/dist/helpers/configure/droid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"droid.js","sourceRoot":"","sources":["../../../src/helpers/configure/droid.ts"],"names":[],"mappings":";AAAA,iEAAiE;AACjE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;;;AAEZ,+BAA+B;AAE/B,oCAAuD;AACvD,sCAAqF;AAErF;;;;;;GAMG;AACI,MAAM,eAAe,GAAG,CAAC,OAAe,EAAE,OAAgB,EAAO,EAAE;IACtE,MAAM,KAAK,GAAQ;QACf,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,MAAM;QACZ,GAAG,EAAE,OAAO;KACf,CAAC;IAEF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,KAAK,CAAC,OAAO,GAAG,EAAE,aAAa,EAAE,wBAAwB,EAAE,CAAC;IAChE,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC,CAAC;AAZW,QAAA,eAAe,mBAY1B;AAEF;;;;;;;GAOG;AACI,MAAM,eAAe,GAAG,KAAK,EAAE,OAAqB,EAA2B,EAAE;IACpF,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,IAAA,cAAO,EAAC,IAAA,mBAAW,EAAC,OAAO,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC;QAEpE,MAAM,KAAK,GAAG,IAAA,uBAAe,EAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAEhE,MAAM,GAAG,GAAG,IAAA,wBAAe,EAAC,WAAW,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAE9E,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAElB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACzD,OAAO,CAAC,IAAI,CAAC,IAAA,8BAAqB,GAAE,CAAC,CAAC;QAC1C,CAAC;IACL,CAAC;IAED,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,IAAA,yBAAgB,EACzB,IAAA,sBAAc,EAAC,OAAO,CAAC,KAAK,EAAE,IAAA,cAAO,EAAC,IAAA,mBAAW,EAAC,OAAO,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC,EAC/E,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC;AAxBW,QAAA,eAAe,mBAwB1B"}

package/dist/helpers/configure/grok.d.ts

@@ -0,0 +1,25 @@
+import { ActionResult, SetupOptions } from '../../types';
+/**
+ * Builds the marker-fenced `[mcp_servers.nram]` TOML block. Grok Build
+ * expands `${VAR}` in string fields at load time, so in API-key mode the
+ * Authorization header references the NRAM_API_KEY environment variable and
+ * the key itself is never written to disk
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+export declare const grok_mcp_block: (mcp_url: string, api_key?: string) => string;
+/**
+ * Configures Grok Build (xAI): upserts a marker-fenced `[mcp_servers.nram]`
+ * block in config.toml (project-scoped config files support `[mcp_servers]`
+ * only, which is exactly what is written) and injects the agent-instructions
+ * SessionStart hook as its own merged hooks file (Grok Build merges every
+ * `hooks/*.json`, in the same nested shape Claude Code uses).
+ *
+ * Native config.toml servers take documented precedence over Grok Build's
+ * Claude Code compatibility sources on a name conflict, so registering nram
+ * here stays correct on machines where Claude Code is configured too
+ *
+ * @param options the collected setup options
+ */
+export declare const configure_grok: (options: SetupOptions) => Promise<ActionResult[]>;

package/dist/helpers/configure/grok.js

@@ -0,0 +1,93 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure_grok = exports.grok_mcp_block = void 0;
+const path_1 = require("path");
+const smol_toml_1 = require("smol-toml");
+const types_1 = require("../../types");
+const paths_1 = require("../paths");
+const upsert_1 = require("../upsert");
+/**
+ * Builds the marker-fenced `[mcp_servers.nram]` TOML block. Grok Build
+ * expands `${VAR}` in string fields at load time, so in API-key mode the
+ * Authorization header references the NRAM_API_KEY environment variable and
+ * the key itself is never written to disk
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+const grok_mcp_block = (mcp_url, api_key) => {
+    const lines = [
+        '[mcp_servers.nram]',
+        `url = "${mcp_url}"`
+    ];
+    if (api_key !== undefined) {
+        lines.push('headers = { "Authorization" = "Bearer ${NRAM_API_KEY}" }');
+    }
+    return lines.join('\n');
+};
+exports.grok_mcp_block = grok_mcp_block;
+/**
+ * Configures Grok Build (xAI): upserts a marker-fenced `[mcp_servers.nram]`
+ * block in config.toml (project-scoped config files support `[mcp_servers]`
+ * only, which is exactly what is written) and injects the agent-instructions
+ * SessionStart hook as its own merged hooks file (Grok Build merges every
+ * `hooks/*.json`, in the same nested shape Claude Code uses).
+ *
+ * Native config.toml servers take documented precedence over Grok Build's
+ * Claude Code compatibility sources on a name conflict, so registering nram
+ * here stays correct on machines where Claude Code is configured too
+ *
+ * @param options the collected setup options
+ */
+const configure_grok = async (options) => {
+    const results = [];
+    if (options.mcp_url !== undefined) {
+        const config_path = (0, path_1.resolve)((0, paths_1.grok_dir)(options.scope), 'config.toml');
+        const mcp = (0, upsert_1.upsert_block_with_validation)(config_path, (0, exports.grok_mcp_block)(options.mcp_url, options.api_key), smol_toml_1.parse, 'TOML', (parsed, text) => parsed?.mcp_servers?.nram !== undefined && !(0, upsert_1.has_marker_block)(text, 'hash')
+            ? {
+                action: 'MCP registration',
+                kind: 'skipped',
+                detail: `[mcp_servers.nram] already exists in ${config_path} (outside the nram setup markers)`
+            }
+            : undefined, parsed => parsed?.mcp_servers?.nram !== undefined);
+        results.push(mcp);
+        if ((mcp.kind === 'written' || mcp.kind === 'updated') && options.api_key !== undefined) {
+            results.push((0, upsert_1.api_key_manual_result)());
+        }
+    }
+    if (options.instructions) {
+        const hook = (0, upsert_1.upsert_hooks_json)((0, path_1.resolve)((0, paths_1.grok_dir)(options.scope), 'hooks', 'nram.json'), options.base_url);
+        results.push(hook);
+        // user-scope hooks are always trusted; project hooks are not run
+        // until the user trusts them inside Grok Build
+        if (options.scope === types_1.Scope.PROJECT && (hook.kind === 'written' || hook.kind === 'updated')) {
+            results.push({
+                action: 'Hook trust',
+                kind: 'manual',
+                detail: 'project-scope hooks only run after you approve them: run /hooks-trust inside Grok Build'
+            });
+        }
+    }
+    return results;
+};
+exports.configure_grok = configure_grok;
+//# sourceMappingURL=grok.js.map

package/dist/helpers/configure/grok.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grok.js","sourceRoot":"","sources":["../../../src/helpers/configure/grok.ts"],"names":[],"mappings":"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"}

package/dist/helpers/configure/hermes.d.ts

@@ -0,0 +1,22 @@
+import { ActionResult, SetupOptions } from '../../types';
+/**
+ * Builds the marker-fenced `mcp_servers` YAML block. Hermes resolves
+ * `${VAR}` placeholders from `~/.hermes/.env` at connection time, so the key
+ * never reaches disk
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+export declare const hermes_mcp_block: (mcp_url: string, api_key?: string) => string;
+/**
+ * Configures Hermes (Nous Research): upserts a marker-fenced `mcp_servers`
+ * block in `~/.hermes/config.yaml` (user scope only; Hermes has no project
+ * configuration; YAML cannot carry a duplicate top-level key, so an existing
+ * `mcp_servers` outside our markers means a manual step) and the agent
+ * instructions into the repository root AGENTS.md at project scope.
+ * Hermes's user-level SOUL.md is identity, not protocol, so user-scope
+ * instructions are reported and skipped
+ *
+ * @param options the collected setup options
+ */
+export declare const configure_hermes: (options: SetupOptions) => Promise<ActionResult[]>;

package/dist/helpers/configure/hermes.js

@@ -0,0 +1,107 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure_hermes = exports.hermes_mcp_block = void 0;
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+const types_1 = require("../../types");
+const paths_1 = require("../paths");
+const upsert_1 = require("../upsert");
+/**
+ * Builds the marker-fenced `mcp_servers` YAML block. Hermes resolves
+ * `${VAR}` placeholders from `~/.hermes/.env` at connection time, so the key
+ * never reaches disk
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+const hermes_mcp_block = (mcp_url, api_key) => {
+    const lines = [
+        'mcp_servers:',
+        '  nram:',
+        `    url: "${mcp_url}"`
+    ];
+    if (api_key !== undefined) {
+        lines.push('    headers:');
+        lines.push('      Authorization: "Bearer ${NRAM_API_KEY}"');
+    }
+    return lines.join('\n');
+};
+exports.hermes_mcp_block = hermes_mcp_block;
+/**
+ * Configures Hermes (Nous Research): upserts a marker-fenced `mcp_servers`
+ * block in `~/.hermes/config.yaml` (user scope only; Hermes has no project
+ * configuration; YAML cannot carry a duplicate top-level key, so an existing
+ * `mcp_servers` outside our markers means a manual step) and the agent
+ * instructions into the repository root AGENTS.md at project scope.
+ * Hermes's user-level SOUL.md is identity, not protocol, so user-scope
+ * instructions are reported and skipped
+ *
+ * @param options the collected setup options
+ */
+const configure_hermes = async (options) => {
+    const results = [];
+    if (options.mcp_url !== undefined) {
+        if (options.scope !== types_1.Scope.USER) {
+            results.push({
+                action: 'MCP registration',
+                kind: 'skipped',
+                detail: 'Hermes keeps MCP servers in the user-level ~/.hermes/config.yaml only; rerun at user scope'
+            });
+        }
+        else {
+            const config_path = (0, path_1.resolve)((0, paths_1.hermes_dir)(), 'config.yaml');
+            const mcp = (0, upsert_1.upsert_block_with_validation)(config_path, (0, exports.hermes_mcp_block)(options.mcp_url, options.api_key), yaml_1.parse, 'YAML', (parsed, text) => parsed?.mcp_servers !== undefined && !(0, upsert_1.has_marker_block)(text, 'hash')
+                ? {
+                    action: 'MCP registration',
+                    kind: 'manual',
+                    detail: `${config_path} already has an mcp_servers key (YAML cannot carry the key ` +
+                        'twice); add this under it yourself:\n  nram:\n    url: "<your nram MCP URL>"'
+                }
+                : undefined, parsed => parsed?.mcp_servers?.nram !== undefined);
+            results.push(mcp);
+            if ((mcp.kind === 'written' || mcp.kind === 'updated') && options.api_key !== undefined) {
+                results.push({
+                    action: 'API key',
+                    kind: 'manual',
+                    detail: 'add NRAM_API_KEY=<your nram API key> to ~/.hermes/.env (Hermes resolves ${VAR} ' +
+                        'placeholders from that file); the key is never written to config.yaml'
+                });
+            }
+        }
+    }
+    if (options.instructions) {
+        if (options.scope !== types_1.Scope.PROJECT) {
+            results.push({
+                action: 'Agent instructions',
+                kind: 'skipped',
+                detail: 'Hermes has no documented global AGENTS.md (SOUL.md is identity, not protocol); ' +
+                    'rerun at project scope to write the repository AGENTS.md'
+            });
+        }
+        else {
+            results.push((0, upsert_1.agents_md_result)((0, path_1.resolve)(process.cwd(), 'AGENTS.md'), options.instructions.full));
+        }
+    }
+    return results;
+};
+exports.configure_hermes = configure_hermes;
+//# sourceMappingURL=hermes.js.map

package/dist/helpers/configure/hermes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermes.js","sourceRoot":"","sources":["../../../src/helpers/configure/hermes.ts"],"names":[],"mappings":"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"}

package/dist/helpers/configure/junie.d.ts

@@ -0,0 +1,10 @@
+import { ActionResult, SetupOptions } from '../../types';
+/**
+ * Configures Junie (JetBrains): merges the nram MCP server into mcp/mcp.json
+ * at the requested scope and upserts the agent instructions into the
+ * AGENTS.md Junie reads: `~/.junie/AGENTS.md` at user scope, the repository
+ * root AGENTS.md at project scope
+ *
+ * @param options the collected setup options
+ */
+export declare const configure_junie: (options: SetupOptions) => Promise<ActionResult[]>;

package/dist/helpers/configure/junie.js

@@ -0,0 +1,52 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure_junie = void 0;
+const path_1 = require("path");
+const paths_1 = require("../paths");
+const upsert_1 = require("../upsert");
+/**
+ * Configures Junie (JetBrains): merges the nram MCP server into mcp/mcp.json
+ * at the requested scope and upserts the agent instructions into the
+ * AGENTS.md Junie reads: `~/.junie/AGENTS.md` at user scope, the repository
+ * root AGENTS.md at project scope
+ *
+ * @param options the collected setup options
+ */
+const configure_junie = async (options) => {
+    const results = [];
+    if (options.mcp_url !== undefined) {
+        const config_path = (0, path_1.resolve)((0, paths_1.junie_dir)(options.scope), 'mcp', 'mcp.json');
+        const mcp = (0, upsert_1.mcp_json_result)(config_path, ['mcpServers', 'nram'], { url: options.mcp_url }, {
+            note: 'CLI format; JetBrains tracks an IDE/CLI mcp.json incompatibility, JUNIE-1331'
+        });
+        results.push(mcp);
+        if (mcp.kind !== 'manual' && options.api_key !== undefined) {
+            results.push((0, upsert_1.api_key_header_manual_result)(config_path));
+        }
+    }
+    if (options.instructions) {
+        results.push((0, upsert_1.agents_md_result)((0, paths_1.agents_md_path)(options.scope, (0, path_1.resolve)((0, paths_1.junie_dir)(options.scope), 'AGENTS.md')), options.instructions.full));
+    }
+    return results;
+};
+exports.configure_junie = configure_junie;
+//# sourceMappingURL=junie.js.map

package/dist/helpers/configure/junie.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"junie.js","sourceRoot":"","sources":["../../../src/helpers/configure/junie.ts"],"names":[],"mappings":";AAAA,iEAAiE;AACjE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;;;AAEZ,+BAA+B;AAE/B,oCAAqD;AACrD,sCAA4F;AAE5F;;;;;;;GAOG;AACI,MAAM,eAAe,GAAG,KAAK,EAAE,OAAqB,EAA2B,EAAE;IACpF,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,IAAA,cAAO,EAAC,IAAA,iBAAS,EAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAEzE,MAAM,GAAG,GAAG,IAAA,wBAAe,EAAC,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE;YACvF,IAAI,EAAE,8EAA8E;SACvF,CAAC,CAAC;QAEH,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAElB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACzD,OAAO,CAAC,IAAI,CAAC,IAAA,qCAA4B,EAAC,WAAW,CAAC,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;IAED,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,IAAA,yBAAgB,EACzB,IAAA,sBAAc,EAAC,OAAO,CAAC,KAAK,EAAE,IAAA,cAAO,EAAC,IAAA,iBAAS,EAAC,OAAO,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC,EAC7E,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC;AAxBW,QAAA,eAAe,mBAwB1B"}

package/dist/helpers/configure/kilo.d.ts

@@ -0,0 +1,19 @@
+import { ActionResult, SetupOptions } from '../../types';
+/**
+ * Builds the `mcp.nram` entry for kilo.jsonc. Kilo substitutes
+ * `{env:VAR}` references, so the key never reaches disk
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+export declare const kilo_mcp_entry: (mcp_url: string, api_key?: string) => any;
+/**
+ * Configures Kilo Code: merges the nram MCP server into kilo.jsonc at the
+ * requested scope. Instructions: project scope uses the repository root
+ * AGENTS.md (Kilo reads it natively); user scope writes a rule file under
+ * the global config dir and references it from the `instructions` array in
+ * kilo.jsonc, which is how Kilo documents global rules
+ *
+ * @param options the collected setup options
+ */
+export declare const configure_kilo: (options: SetupOptions) => Promise<ActionResult[]>;