nova-audio-agent 0.1.2 → 0.2.0

package/README.md

@@ -28,7 +28,7 @@ In the desktop settings, configure your [DashScope](https://platform.qianwenai.c
 API key for the default Qwen realtime voice service and your
 [Tavily](https://docs.tavily.com) API key for web search. For coding tasks, set up
 a logged-in Codex executable; see the
-[setup guide](https://github.com/deepnovacore/NovaAudioAgent/blob/main/docs/getting-started.md).
+[setup guide](https://github.com/deepnovacore/NovaAudioAgent/blob/main/docs/en/getting-started.md).
 Allow microphone access when prompted, then launch Nova:
 
 ```bash
@@ -66,14 +66,14 @@ for your installed version.
 
 ## Installation details
 
-The CLI downloads the matching `v0.1.1` desktop release from
-[GitHub Releases](https://github.com/deepnovacore/NovaAudioAgent/releases/tag/v0.1.1)
+The CLI downloads the matching `v0.2.0` desktop release from
+[GitHub Releases](https://github.com/deepnovacore/NovaAudioAgent/releases/tag/v0.2.0)
 into `~/.nova-audio-agent/cli/releases/` and verifies its published SHA-256 digest
 before launching it. It reuses the desktop client's encrypted settings store;
 the CLI does not read or print secret values.
 
 Documentation-only npm updates may have a newer package version while retaining
-the same desktop release. `novaaudio --version` continues to report `0.1.1`.
+the same desktop release. `novaaudio --version` continues to report `0.2.0`.
 
 This release supports macOS arm64 and Windows x64. Linux and Intel Mac desktop
 downloads are not included. The desktop application is currently unsigned, so
@@ -81,9 +81,9 @@ macOS Gatekeeper or Windows SmartScreen may display a security warning.
 
 ## Learn more
 
-- [Getting started and integrations](https://github.com/deepnovacore/NovaAudioAgent/blob/main/docs/getting-started.md)
-- [Runtime architecture](https://github.com/deepnovacore/NovaAudioAgent/blob/main/docs/architecture.md)
-- [Design: when should a proactive voice agent speak?](https://github.com/deepnovacore/NovaAudioAgent/blob/main/docs/blog/2026-08-proactive-voice-agent-design-space.md)
+- [Getting started and integrations](https://github.com/deepnovacore/NovaAudioAgent/blob/main/docs/en/getting-started.md)
+- [Runtime architecture](https://github.com/deepnovacore/NovaAudioAgent/blob/main/docs/en/architecture.md)
+- [Design: when should a proactive voice agent speak?](https://github.com/deepnovacore/NovaAudioAgent/blob/main/docs/en/blog/2026-08-proactive-voice-agent-design-space.md)
 - [Report an issue](https://github.com/deepnovacore/NovaAudioAgent/issues)
 - [Build from source and contribute](https://github.com/deepnovacore/NovaAudioAgent/blob/main/CONTRIBUTING.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nova-audio-agent",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Install and launch the Nova Audio Agent desktop client from the command line.",
   "type": "module",
   "bin": {

package/release-assets.json

@@ -3,13 +3,13 @@
   "repository": "deepnovacore/NovaAudioAgent",
   "targets": {
     "darwin-arm64": {
-      "artifact": "nova-audio-agent-0.1.1-macos-arm64-app.zip",
-      "executable": "Nova Audio Agent Ambient Orb.app/Contents/MacOS/Nova Audio Agent Ambient Orb",
+      "artifact": "nova-audio-agent-0.2.0-macos-arm64-app.zip",
+      "executable": "Nova Audio Agent Desktop.app/Contents/MacOS/Nova Audio Agent Desktop",
       "archive": "zip"
     },
     "win32-x64": {
-      "artifact": "nova-audio-agent-0.1.1-windows-x64-portable.zip",
-      "executable": "Nova Audio Agent Ambient Orb.exe",
+      "artifact": "nova-audio-agent-0.2.0-windows-x64-portable.zip",
+      "executable": "Nova Audio Agent Desktop.exe",
       "archive": "zip"
     }
   }

package/src/capability-registry.mjs

@@ -0,0 +1,266 @@
+// Generated from runtime/src/config/capability-registry.ts; run node runtime/scripts/check-capabilities.mjs --write.
+/** One dependency-free registry parser, also emitted into the standalone CLI by check-capabilities.mjs. */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const DEFAULT_CAPABILITIES_PATH = '~/.nova-audio-agent/capabilities.json';
+export const BAILIAN_SEARCH_MCP_URL = 'https://dashscope.aliyuncs.com/api/v1/mcps/EnhancedSearch/mcp';
+export const BAILIAN_SEARCH_MCP_TOOL = 'search_pro';
+export const DEFAULT_FRONTBRAIN_TOOL_BUDGET = 24;
+export const MCP_NON_AUTH_HEADERS = ['accept', 'content-type', 'user-agent'];
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u;
+const SERVER_NAME = /^[a-z][a-z0-9_]{0,31}$/u;
+const MAX_CONFIG_BYTES = 256 * 1024;
+export class CapabilityConfigurationError extends Error {
+    reason;
+    code = 'invalid_capabilities_configuration';
+    constructor(reason) {
+        super(`invalid capabilities configuration: ${reason}`);
+        this.reason = reason;
+        this.name = 'CapabilityConfigurationError';
+    }
+}
+function environmentOverride(environment, name) {
+    const value = environment[name]?.trim();
+    return value === '' ? undefined : value;
+}
+function omittedDefault(value, fallback) { return value === undefined ? fallback : value; }
+function invalid(field) { throw new CapabilityConfigurationError(field); }
+function object(value, field, keys) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        invalid(field);
+    const record = value;
+    if (keys !== undefined && Object.keys(record).some(key => !keys.includes(key)))
+        invalid(field);
+    return record;
+}
+function bool(value, fallback, field) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        invalid(field);
+    return value;
+}
+function string(value, field, max = 8192) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > max || /[\u0000\r\n]/u.test(value))
+        invalid(field);
+    return value;
+}
+function integer(value, fallback, max, field) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > max)
+        invalid(field);
+    return value;
+}
+function stringMap(value, field) {
+    const entries = Object.entries(object(omittedDefault(value, {}), field));
+    if (entries.length > 64)
+        invalid(field);
+    return Object.fromEntries(entries.map(([key, val]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_-]{0,127}$/u.test(key))
+            invalid(field);
+        if (typeof val !== 'string' || val.length > 8192 || /[\u0000\r\n]/u.test(val))
+            invalid(field);
+        return [key, val];
+    }));
+}
+export function interpolateCapabilityValue(value, environment) {
+    const resolved = value.replace(/\$\{([^}]+)\}/gu, (_match, name) => {
+        if (!ENV_NAME.test(name))
+            invalid('invalid_environment_reference');
+        const replacement = environment[name];
+        if (replacement === undefined || replacement.trim() === '')
+            invalid(`missing_environment:${name}`);
+        if (/[\u0000\r\n]/u.test(replacement))
+            invalid(`invalid_environment:${name}`);
+        return replacement;
+    });
+    if (resolved.length > 8192)
+        invalid('interpolated_value_too_large');
+    return resolved;
+}
+function interpolateMap(value, environment) {
+    return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, interpolateCapabilityValue(val, environment)]));
+}
+export function validateMcpEndpoint(value, headers = {}) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        invalid('invalid_mcp_endpoint');
+    }
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    // Unknown custom headers may themselves be credentials. Only known non-auth metadata is safe on HTTP.
+    const hasAuth = Object.keys(headers).some(key => !MCP_NON_AUTH_HEADERS.some(name => name === key.toLowerCase()));
+    if (url.username || url.password || url.hash
+        || (url.protocol !== 'https:' && (url.protocol !== 'http:' || !loopback || hasAuth)))
+        invalid('insecure_mcp_endpoint');
+}
+function moduleConfig(value, field, keys) {
+    return object(omittedDefault(value, {}), field, ['enabled', ...keys]);
+}
+export function parseCapabilityRegistry(input, environment = {}) {
+    const document = object(input, 'document', ['version', 'modules', 'mcpServers', 'frontbrainToolBudget']);
+    if (document.version !== 1)
+        invalid('version');
+    const modules = object(omittedDefault(document.modules, {}), 'modules', ['search', 'camera', 'coding', 'knowledge']);
+    const search = moduleConfig(modules.search, 'modules.search', ['provider', 'mcp', 'tavily']);
+    const camera = moduleConfig(modules.camera, 'modules.camera', []);
+    const coding = moduleConfig(modules.coding, 'modules.coding', []);
+    const knowledge = moduleConfig(modules.knowledge, 'modules.knowledge', ['exposeToCodex']);
+    const enabled = bool(search.enabled, true, 'modules.search.enabled');
+    const configuredProvider = omittedDefault(search.provider, 'tavily');
+    if (configuredProvider !== 'tavily' && configuredProvider !== 'mcp')
+        invalid('modules.search.provider');
+    const provider = environmentOverride(environment, 'NOVA_AUDIO_AGENT_SEARCH_PROVIDER') ?? configuredProvider;
+    if (provider !== 'tavily' && provider !== 'mcp')
+        invalid('NOVA_AUDIO_AGENT_SEARCH_PROVIDER');
+    const overrides = [];
+    if (environment.NOVA_AUDIO_AGENT_SEARCH_PROVIDER?.trim())
+        overrides.push('NOVA_AUDIO_AGENT_SEARCH_PROVIDER');
+    let cameraEnabled = bool(camera.enabled, true, 'modules.camera.enabled');
+    const cameraOverride = environment.NOVA_AUDIO_AGENT_CAMERA_MODULE_ENABLED?.trim().toLowerCase();
+    if (cameraOverride) {
+        if (!['true', 'false', '1', '0', 'yes', 'no', 'on', 'off'].includes(cameraOverride))
+            invalid('NOVA_AUDIO_AGENT_CAMERA_MODULE_ENABLED');
+        cameraEnabled = ['true', '1', 'yes', 'on'].includes(cameraOverride);
+        overrides.push('NOVA_AUDIO_AGENT_CAMERA_MODULE_ENABLED');
+    }
+    const tavily = object(omittedDefault(search.tavily, {}), 'modules.search.tavily', ['apiKeyEnv']);
+    const apiKeyEnv = string(omittedDefault(tavily.apiKeyEnv, 'TAVILY_API_KEY'), 'modules.search.tavily.apiKeyEnv', 128);
+    if (!ENV_NAME.test(apiKeyEnv))
+        invalid('modules.search.tavily.apiKeyEnv');
+    let mcp;
+    if (search.mcp !== undefined || (enabled && provider === 'mcp')) {
+        const config = object(omittedDefault(search.mcp, {}), 'modules.search.mcp', ['url', 'tool', 'headers', 'timeoutMs', 'maxResultBytes']);
+        const urlOverride = environmentOverride(environment, 'NOVA_AUDIO_AGENT_SEARCH_MCP_URL');
+        const toolOverride = environmentOverride(environment, 'NOVA_AUDIO_AGENT_SEARCH_MCP_TOOL');
+        const preset = !urlOverride && config.url === undefined;
+        const configuredUrl = string(omittedDefault(config.url, BAILIAN_SEARCH_MCP_URL), 'modules.search.mcp.url');
+        const rawUrl = string(urlOverride ?? configuredUrl, 'modules.search.mcp.url');
+        const configuredTool = string(omittedDefault(config.tool, preset ? BAILIAN_SEARCH_MCP_TOOL : 'web_search'), 'modules.search.mcp.tool', 256);
+        const tool = string(toolOverride ?? configuredTool, 'modules.search.mcp.tool', 256);
+        const rawHeaders = stringMap(omittedDefault(config.headers, preset ? { authorization: 'Bearer ${DASHSCOPE_API_KEY}' } : {}), 'modules.search.mcp.headers');
+        const headers = enabled && provider === 'mcp' ? interpolateMap(rawHeaders, environment) : rawHeaders;
+        const url = enabled && provider === 'mcp' ? interpolateCapabilityValue(rawUrl, environment) : rawUrl;
+        if (enabled && provider === 'mcp')
+            validateMcpEndpoint(url, headers);
+        mcp = { url, tool, headers,
+            timeoutMs: integer(config.timeoutMs, 8000, 60000, 'modules.search.mcp.timeoutMs'),
+            maxResultBytes: integer(config.maxResultBytes, 262144, 1048576, 'modules.search.mcp.maxResultBytes') };
+        if (urlOverride)
+            overrides.push('NOVA_AUDIO_AGENT_SEARCH_MCP_URL');
+        if (toolOverride)
+            overrides.push('NOVA_AUDIO_AGENT_SEARCH_MCP_TOOL');
+    }
+    const servers = object(omittedDefault(document.mcpServers, {}), 'mcpServers');
+    if (Object.keys(servers).length > 8)
+        invalid('mcpServers:max_8');
+    const mcpServers = Object.create(null);
+    const serverStatuses = [];
+    for (const [index, [name, value]] of Object.entries(servers).entries()) {
+        const safeName = SERVER_NAME.test(name) ? name : `invalid_server_${index + 1}`;
+        try {
+            if (!SERVER_NAME.test(name))
+                invalid('invalid_server_name');
+            if (name === 'nova_camera' || name === 'nova_knowledge')
+                invalid('reserved_server_name');
+            const server = parseServer(value, environment);
+            mcpServers[name] = server;
+            serverStatuses.push({ name, status: server.enabled ? 'configured' : 'disabled' });
+        }
+        catch (error) {
+            serverStatuses.push({ name: safeName, status: 'failed', reason: error instanceof CapabilityConfigurationError ? error.reason : 'invalid_server' });
+        }
+    }
+    return { version: 1, modules: {
+            search: { enabled, provider, tavily: { apiKeyEnv, ...(environment[apiKeyEnv] === undefined ? {} : { apiKey: environment[apiKeyEnv] }) }, ...(mcp === undefined ? {} : { mcp }) },
+            camera: { enabled: cameraEnabled }, coding: { enabled: bool(coding.enabled, true, 'modules.coding.enabled') },
+            knowledge: { enabled: bool(knowledge.enabled, false, 'modules.knowledge.enabled'), exposeToCodex: bool(knowledge.exposeToCodex, false, 'modules.knowledge.exposeToCodex') },
+        }, mcpServers, serverStatuses, overrides,
+        frontbrainToolBudget: integer(document.frontbrainToolBudget, DEFAULT_FRONTBRAIN_TOOL_BUDGET, 256, 'frontbrainToolBudget') };
+}
+function parseServer(value, environment) {
+    const config = object(value, 'server', ['enabled', 'transport', 'url', 'headers', 'command', 'args', 'env', 'tools', 'exposeTo']);
+    const enabled = bool(config.enabled, true, 'server.enabled');
+    const transport = config.transport;
+    if (transport !== 'streamable-http' && transport !== 'stdio')
+        invalid('server.transport');
+    const exposure = object(omittedDefault(config.exposeTo, {}), 'server.exposeTo', ['frontbrain', 'codex']);
+    const exposeTo = { frontbrain: bool(exposure.frontbrain, false, 'server.exposeTo.frontbrain'), codex: bool(exposure.codex, true, 'server.exposeTo.codex') };
+    const rawTools = object(omittedDefault(config.tools, {}), 'server.tools');
+    if (Object.keys(rawTools).length > 32)
+        invalid('server.tools:max_32');
+    const tools = Object.fromEntries(Object.entries(rawTools).map(([name, value]) => {
+        string(name, 'server.tool_name', 256);
+        const tool = object(value, 'server.tool', ['enabled', 'timeoutMs', 'maxResultBytes', 'maxCallsPerTurn']);
+        return [name, { enabled: bool(tool.enabled, false, 'server.tool.enabled'),
+                timeoutMs: integer(tool.timeoutMs, 8000, 60000, 'server.tool.timeoutMs'),
+                maxResultBytes: integer(tool.maxResultBytes, 32768, 1048576, 'server.tool.maxResultBytes'),
+                maxCallsPerTurn: integer(tool.maxCallsPerTurn, 2, 32, 'server.tool.maxCallsPerTurn') }];
+    }));
+    if (transport === 'streamable-http') {
+        if (config.command !== undefined || config.args !== undefined || config.env !== undefined)
+            invalid('server.transport_fields');
+        const rawHeaders = stringMap(config.headers, 'server.headers');
+        const rawUrl = string(config.url, 'server.url');
+        const headers = enabled ? interpolateMap(rawHeaders, environment) : rawHeaders;
+        const url = enabled ? interpolateCapabilityValue(rawUrl, environment) : rawUrl;
+        if (enabled)
+            validateMcpEndpoint(url, headers);
+        return { enabled, transport, url, urlInterpolated: /\$\{[A-Za-z_][A-Za-z0-9_]*\}/u.test(rawUrl), headers, tools, exposeTo };
+    }
+    if (config.url !== undefined || config.headers !== undefined)
+        invalid('server.transport_fields');
+    const command = string(config.command, 'server.command');
+    const args = omittedDefault(config.args, []);
+    if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 8192 || arg.includes('\0')))
+        invalid('server.args');
+    const env = stringMap(config.env, 'server.env');
+    if (Object.keys(env).some(key => !ENV_NAME.test(key)))
+        invalid('server.env');
+    return { enabled, transport, command, args: args, env: enabled ? interpolateMap(env, environment) : env, tools, exposeTo };
+}
+export function loadCapabilityRegistry(options = {}) {
+    const environment = options.environment ?? process.env;
+    const explicitPath = (options.path === '' ? undefined : options.path) ?? environmentOverride(environment, 'NOVA_AUDIO_AGENT_CAPABILITIES_CONFIG');
+    const path = explicitPath ?? DEFAULT_CAPABILITIES_PATH;
+    const explicit = explicitPath !== undefined;
+    const resolved = path.startsWith('~/') ? join(options.home ?? homedir(), path.slice(2)) : path;
+    let input;
+    try {
+        const bytes = readFileSync(resolved);
+        if (bytes.byteLength > MAX_CONFIG_BYTES)
+            invalid('file_too_large');
+        input = JSON.parse(bytes.toString('utf8'));
+    }
+    catch (error) {
+        if (!explicit && error.code === 'ENOENT')
+            input = { version: 1 };
+        else
+            throw error instanceof CapabilityConfigurationError ? error : new CapabilityConfigurationError('file_unreadable_or_invalid_json');
+    }
+    return parseCapabilityRegistry(input, environment);
+}
+export function capabilityStatus(registry, toolCount = null) {
+    return { modules: {
+            search: { enabled: registry.modules.search.enabled, provider: registry.modules.search.provider },
+            camera: registry.modules.camera, coding: registry.modules.coding, knowledge: registry.modules.knowledge,
+        }, servers: registry.serverStatuses, overrides: registry.overrides, toolCount, toolBudget: registry.frontbrainToolBudget };
+}
+export function inspectCapabilities(options = {}) {
+    try {
+        const registry = loadCapabilityRegistry(options);
+        const environment = options.environment ?? process.env;
+        const missingTavily = registry.modules.search.enabled && registry.modules.search.provider === 'tavily'
+            && !environment[registry.modules.search.tavily.apiKeyEnv]?.trim();
+        return { ok: !missingTavily && registry.serverStatuses.every(server => server.status !== 'failed'),
+            ...capabilityStatus(registry),
+            ...(missingTavily ? { reason: `missing_environment:${registry.modules.search.tavily.apiKeyEnv}` } : {}) };
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof CapabilityConfigurationError ? error.reason : 'invalid_configuration' };
+    }
+}

package/src/command.mjs

@@ -37,7 +37,17 @@ export async function main(argv, {
       stdout.write(`Configured keys: ${report.configuredSecretKeys.length === 0 ? 'none' : report.configuredSecretKeys.join(', ')}\n`)
       stdout.write(`Codex: ${report.codexPresent ? 'found' : 'missing'}\n`)
     }
-    return report.supported ? 0 : 1
+    if (report.capabilities !== undefined) {
+      const status = report.capabilities
+      stdout.write(`Capabilities: ${status.ok ? 'valid' : 'needs attention'}${status.reason ? ` (${status.reason})` : ''}\n`)
+      if (status.modules) {
+        for (const [name, module] of Object.entries(status.modules)) stdout.write(`  ${name}: ${module.enabled ? 'enabled' : 'disabled'}${module.provider ? ` (${module.provider})` : ''}\n`)
+        stdout.write(`  FrontBrain budget: ${status.toolBudget}; exact count requires runtime composition\n`)
+        for (const server of status.servers) stdout.write(`  MCP ${server.name}: ${server.status}${server.reason ? ` (${server.reason})` : ''}\n`)
+        for (const name of status.overrides) stdout.write(`  Override: ${name}\n`)
+      }
+    }
+    return report.supported && report.capabilities?.ok !== false ? 0 : 1
   }
   if (command !== 'start' && command !== 'config') {
     stdout.write(`${HELP_TEXT}\n`)

package/src/runtime.mjs

@@ -1,3 +1,4 @@
+import {inspectCapabilities} from './capability-registry.mjs'
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto'
 import { spawn, spawnSync } from 'node:child_process'
 import {
@@ -430,8 +431,16 @@ export async function inspectDoctor({
   const executable = resolve(root, target.executable)
   const settings = desktopSettingsPath({platform, home, environment})
   let secretKeys = []
+  let capabilitiesConfigPath
   try {
     const document = JSON.parse(await readFile(settings, 'utf8'))
+    // Match settings-store v4 migration/string validation, then backendLaunchSpec's nonempty saved-path override.
+    const acceptsV4Fields = document?.version === undefined || (typeof document.version === 'number' && document.version >= 4)
+    const candidate = document?.capabilitiesConfigPath
+    if (acceptsV4Fields && typeof candidate === 'string' && !/[\u0000-\u001f\u007f]/u.test(candidate)) {
+      const normalized = candidate.trim()
+      if (normalized && [...normalized].length <= 32768) capabilitiesConfigPath = normalized
+    }
     if (document?.secrets && typeof document.secrets === 'object' && !Array.isArray(document.secrets)) {
       secretKeys = Object.keys(document.secrets).sort()
     }
@@ -443,5 +452,11 @@ export async function inspectDoctor({
     settingsPresent: await access(settings).then(() => true, () => false),
     configuredSecretKeys: Object.freeze(secretKeys),
     codexPresent: findCodex(platform),
+    capabilities: inspectCapabilities({
+      environment: capabilitiesConfigPath === undefined ? environment : {
+        ...environment, NOVA_AUDIO_AGENT_CAPABILITIES_CONFIG: capabilitiesConfigPath,
+      },
+      ...(home === undefined ? {} : {home}),
+    }),
   })
 }

package/src/target.mjs

@@ -1,18 +1,18 @@
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
-export const PRODUCT_VERSION = '0.1.1'
+export const PRODUCT_VERSION = '0.2.0'
 export const RELEASE_REPOSITORY = 'deepnovacore/NovaAudioAgent'
 
 const DEFINITIONS = Object.freeze({
   'darwin-arm64': Object.freeze({
     artifact: `nova-audio-agent-${PRODUCT_VERSION}-macos-arm64-app.zip`,
-    executable: 'Nova Audio Agent Ambient Orb.app/Contents/MacOS/Nova Audio Agent Ambient Orb',
+    executable: 'Nova Audio Agent Desktop.app/Contents/MacOS/Nova Audio Agent Desktop',
     archive: 'zip',
   }),
   'win32-x64': Object.freeze({
     artifact: `nova-audio-agent-${PRODUCT_VERSION}-windows-x64-portable.zip`,
-    executable: 'Nova Audio Agent Ambient Orb.exe',
+    executable: 'Nova Audio Agent Desktop.exe',
     archive: 'zip',
   }),
 })
@@ -43,6 +43,7 @@ export function desktopSettingsPath({
   home = homedir(),
   environment = process.env,
 } = {}) {
+  // Stable storage identity shared with the renamed desktop (including encrypted settings).
   const product = 'Nova Audio Agent Ambient Orb'
   if (platform === 'darwin') {
     return join(home, 'Library', 'Application Support', product, 'ambient-orb-settings.json')