@goodea/olimpyx 0.1.0 → 0.3.0

package/src/cli.js

@@ -10,6 +10,7 @@ import { addAgentFromCatalog, readOwnerStatus } from './init-apply.js';
 import { runInit } from './init.js';
 import { searchCharacters } from './characters.js';
 import { ownerHome, readVault } from './vault.js';
+import { HOST_SKILL_DIRS, installStarterSkill } from './skill-install.js';
 
 const args = process.argv.slice(2);
 const command = args.shift();
@@ -38,18 +39,27 @@ async function configuredClient(tokenOverride, credential = 'session') {
 }
 async function activeClient(callerId) {
   if (!callerId) throw new Error('--caller-id is required for participant commands');
-  const local = await state.loadSession(); if (!local) throw new Error('No local session. Run session begin first.');
+  const local = await state.loadSession(callerId); if (!local) throw new Error('No local session. Run session begin first.');
   await state.renewSession(callerId);
   const client = await configuredClient(local.token);
   const heartbeat = await client.request('POST', `/v1/sessions/${encodeURIComponent(local.session_id)}/heartbeat`, { observed_at: new Date().toISOString() });
   return { client, local, heartbeat };
 }
-async function mutation(client, method, path, body, explicitKey) {
-  const pending = await state.beginMutation(method, path, body, explicitKey);
+async function mutation(client, method, path, body, explicitKey, callerId) {
+  const pending = await state.beginMutation(method, path, body, explicitKey, callerId);
   const result = await client.request(method, path, body, { headers: { 'idempotency-key': pending.key } });
-  await state.completeMutation(pending.fingerprint);
+  await state.completeMutation(pending.fingerprint, callerId);
   return result;
 }
+// Best-effort activity broadcast; never fail the caller's command on a
+// transient server error. Used to keep the city UI showing where this agent is.
+async function broadcastActivity(callerId, payload) {
+  if (!callerId) return;
+  try {
+    const { client } = await activeClient(callerId);
+    await client.request('POST', '/v1/sessions/me/activity', payload);
+  } catch { /* presence/activity are advisory; never block the primary action */ }
+}
 async function loadVaultOwnerToken() {
   try { return (await readVault()).owner?.access_token ?? null; } catch { return null; }
 }
@@ -63,6 +73,22 @@ async function ownerServerUrl() {
   if (local.serverUrl) return local.serverUrl;
   try { return JSON.parse(await readFile(join(ownerHome(), 'config.json'), 'utf8')).serverUrl; } catch { return null; }
 }
+
+// Every owner-scoped client goes through here. Resolving the server from `state` alone --
+// which is rooted at the WORKING DIRECTORY (`OLIMPYX_HOME` or ./.olimpyx), not at the owner
+// home -- made these commands depend on where they were run from. After a global `init`
+// the owner config lives in ~/.olimpyx, so from any other directory the URL came back
+// undefined and the client constructor died on `undefined.replace`; worse, standing in a
+// project configured against a DIFFERENT server sent the owner's real token there and the
+// server answered 401 "Invalid or expired credential" -- a message that points at the token
+// when the token was never the problem. ownerServerUrl() keeps the project-local config
+// first and falls back to the owner home, which is what `usage` already did and the rest
+// did not.
+async function ownerClientWith(token) {
+  const serverUrl = await ownerServerUrl();
+  if (!serverUrl) throw new Error('Not configured. Run: olimpyx init (or olimpyx configure --server URL)');
+  return new OlimpyxClient({ serverUrl, token });
+}
 // Resolves this agent's own owner id for the local budget's owner-scoping (budget.js
 // isOwnTaskRoom/evaluateHelpPolicy, PRD §3.4): `enroll`/`owner-login` normally already
 // cache it in config.json, so this is usually a plain local read with no network call.
@@ -75,7 +101,7 @@ async function resolveOwnerId(config) {
   const ownerToken = await tryLoadOwnerToken();
   if (!ownerToken) return null;
   try {
-    const client = new OlimpyxClient({ serverUrl: config.serverUrl, token: ownerToken });
+    const client = await ownerClientWith(ownerToken);
     const me = await client.request('GET', '/v1/owners/me');
     const ownerId = me?.data?.owner_id ?? null;
     if (ownerId) await state.saveConfig({ ...config, ownerId });
@@ -86,10 +112,8 @@ async function resolveOwnerId(config) {
 }
 async function requireOwnerClient() {
   const ownerToken = await tryLoadOwnerToken();
-  const serverUrl = await ownerServerUrl();
-  if (!serverUrl) throw new Error('Not configured. Run: olimpyx init');
   if (!ownerToken) throw new Error('No owner credential. Run olimpyx init or owner-login.');
-  return new OlimpyxClient({ serverUrl, token: ownerToken });
+  return ownerClientWith(ownerToken);
 }
 // Best-effort so the server can prune acknowledged inbox events (PRD §3.3); a failure
 // here must never interrupt the caller, which has already persisted the cursor locally.
@@ -129,6 +153,11 @@ async function parseJsonOrList(value) {
 }
 
 async function main() {
+  if (command === 'resident') {
+    const { runResidentCli } = await import('./resident/cli.mjs');
+    await runResidentCli(args);
+    return;
+  }
   if (command === 'init') {
     await runInit();
     return;
@@ -138,9 +167,38 @@ async function main() {
     return;
   }
   if (command === 'skill') {
+    const sub = args.shift();
+    if (sub === '--update' || sub === 'update') {
+      const host = option('host', 'codex');
+      if (!HOST_SKILL_DIRS[host]) throw new Error(`Unknown host "${host}". Use one of: ${Object.keys(HOST_SKILL_DIRS).join(', ')}`);
+      const projectPath = option('project') || process.cwd();
+      const target = await installStarterSkill(host, { scope: 'local', projectPath });
+      output({ updated: true, host, target });
+      return;
+    }
+    if (sub === '--host' || sub === '--path') {
+      process.stderr.write(`Usage: olimpyx skill --update [--host codex|claude|claude_code|cursor|opencode] [--project PATH]\n`);
+      process.exitCode = 2; return;
+    }
     process.stdout.write(await readFile(join(ownerHome(), 'skill.md'), 'utf8'));
     return;
   }
+  if (command === 'activity') {
+    // Explicit activity declaration (F-02). The interactive `init` wizard
+    // does its own enrollment and never needs this; this command is for
+    // the non-interactive / scripted path or for re-declaring a location
+    // mid-session.
+    const sub = args.shift();
+    const callerId = option('caller-id');
+    if (sub !== 'set') throw new Error('activity actions: set --kind <room|knowledge|lobby|inbox|offline> [--room-id ID] [--knowledge-card-id ID] [--note TEXT]');
+    const kind = option('kind'); const roomId = option('room-id'); const knowledgeCardId = option('knowledge-card-id'); const note = option('note') ?? '';
+    if (!kind) throw new Error('--kind is required');
+    const payload = { kind, note };
+    if (kind === 'room') { if (!roomId) throw new Error('--room-id is required when --kind=room'); payload.room_id = roomId; }
+    if (kind === 'knowledge') { if (!knowledgeCardId) throw new Error('--knowledge-card-id is required when --kind=knowledge'); payload.knowledge_card_id = knowledgeCardId; }
+    const { client } = await activeClient(callerId);
+    output(await client.request('POST', '/v1/sessions/me/activity', payload)); return;
+  }
   if (command === 'configure') {
     const serverUrl = option('server'); if (!serverUrl) throw new Error('--server URL is required');
     const current = await state.loadConfig(); output(await state.saveConfig({ ...current, serverUrl })); return;
@@ -150,7 +208,7 @@ async function main() {
     const password = process.env.OLIMPYX_OWNER_PASSWORD || (option('password-stdin') ? await stdin() : null);
     if (!email || !password) throw new Error('Use --email and either --password-stdin or OLIMPYX_OWNER_PASSWORD');
     const config = await state.loadConfig();
-    const client = new OlimpyxClient({ serverUrl: config.serverUrl, token: null });
+    const client = await ownerClientWith(null);
     const result = await client.request('POST', '/v1/owners/login', { email, password });
     await state.init(); await state.saveOwnerCredential(result.data.access_token);
     // Cache this agent's owner id locally (budget.js isOwnTaskRoom/evaluateHelpPolicy
@@ -172,7 +230,7 @@ async function main() {
     if (!profile) throw new Error('--profile JSON or --profile @file is required');
     const config = await state.loadConfig();
     const ownerToken = process.env.OLIMPYX_OWNER_TOKEN || await state.loadOwnerCredential();
-    const owner = new OlimpyxClient({ serverUrl: config.serverUrl, token: ownerToken });
+    const owner = await ownerClientWith(ownerToken);
     // Always resolve this agent's own owner id from the owner token, even when config.ownerId
     // is already cached: enroll is what actually binds this installation's agent to an owner,
     // so a stale or previously-mismatched cached value must not be trusted here -- the owner
@@ -211,12 +269,13 @@ async function main() {
     }
     if (action === 'heartbeat') { const callerId = option('caller-id'); const { heartbeat } = await activeClient(callerId); output(heartbeat); return; }
     if (action === 'end') {
-      const local = await state.loadSession(); if (!local) return;
+      const callerId = option('caller-id');
+      const local = await state.loadSession(callerId); if (!local) return;
       const reason = option('reason', 'agent_ended');
       if (!['agent_ended', 'host_ended', 'shutdown'].includes(reason)) throw new Error('Session end reason must be agent_ended, host_ended, or shutdown');
       const result = await (await configuredClient(local.token)).request('POST', `/v1/sessions/${encodeURIComponent(local.session_id)}/end`, { reason });
       await recordSessionEnd(state.root, local.session_id);
-      await state.clearSession(); output(result); return;
+      await state.clearSession(callerId); output(result); return;
     }
     throw new Error('session actions: begin | heartbeat | end');
   }
@@ -226,12 +285,28 @@ async function main() {
     if (/^\/v1\/(?:owners\/(?:register|login)|owners\/me\/enrollment-tokens|agents\/enroll|sessions)$/.test(path)) throw new Error('Credential-issuing endpoints are blocked in generic request; use the dedicated safe command');
     const body = await jsonInput(args.shift());
     const explicitKey = option('idempotency-key');
-    const { client } = await activeClient(option('caller-id'));
-    output(['GET', 'HEAD'].includes(method) ? await client.request(method, path, body) : await mutation(client, method, path, body, explicitKey)); return;
+    const callerId = option('caller-id');
+    const { client } = await activeClient(callerId);
+    output(['GET', 'HEAD'].includes(method) ? await client.request(method, path, body) : await mutation(client, method, path, body, explicitKey, callerId)); return;
   }
   if (command === 'bootstrap') { const { client } = await activeClient(option('caller-id')); output(await client.bootstrap()); return; }
   if (command === 'rooms') { const q = option('q'); const { client } = await activeClient(option('caller-id')); output(await client.rooms(q ? new URLSearchParams({ q }).toString() : '')); return; }
-  if (command === 'inbox') { const { client } = await activeClient(option('caller-id')); output(await client.inbox()); return; }
+  if (command === 'inbox') { const callerId = option('caller-id'); const { client } = await activeClient(callerId); const result = await client.inbox(); await broadcastActivity(callerId, { kind: 'inbox', note: '' }); output(result); return; }
+  if (command === 'activity') {
+    // Explicit activity declaration (F-02). Use this when the agent is doing
+    // something the server can't infer (e.g. reading a knowledge card without
+    // posting a card/review, or simply hanging out in a room).
+    const sub = args.shift();
+    const callerId = option('caller-id');
+    if (sub !== 'set') throw new Error('activity actions: set --kind <room|knowledge|lobby|inbox|offline> [--room-id ID] [--knowledge-card-id ID] [--note TEXT]');
+    const kind = option('kind'); const roomId = option('room-id'); const knowledgeCardId = option('knowledge-card-id'); const note = option('note') ?? '';
+    if (!kind) throw new Error('--kind is required');
+    const payload = { kind, note };
+    if (kind === 'room') { if (!roomId) throw new Error('--room-id is required when --kind=room'); payload.room_id = roomId; }
+    if (kind === 'knowledge') { if (!knowledgeCardId) throw new Error('--knowledge-card-id is required when --kind=knowledge'); payload.knowledge_card_id = knowledgeCardId; }
+    const { client } = await activeClient(callerId);
+    output(await client.request('POST', '/v1/sessions/me/activity', payload)); return;
+  }
   if (command === 'knowledge') {
     const sub = args[0] && !args[0].startsWith('--') ? args.shift() : null;
     if (sub === 'card') {
@@ -250,7 +325,7 @@ async function main() {
         topic, summary, body, sources, references,
         ...(challengeCard && challengeVersion ? { challenge_of: { card_id: challengeCard, version_id: challengeVersion } } : {})
       };
-      output(await mutation(client, 'POST', '/v1/knowledge/cards', payload, explicitKey));
+      output(await mutation(client, 'POST', '/v1/knowledge/cards', payload, explicitKey, callerId));
       return;
     }
     if (sub === 'review') {
@@ -265,7 +340,7 @@ async function main() {
       const { client } = await activeClient(callerId);
       const path = `/v1/knowledge/versions/${encodeURIComponent(versionId)}/reviews`;
       const payload = { verdict, explanation, evidence };
-      output(await mutation(client, 'POST', path, payload, explicitKey));
+      output(await mutation(client, 'POST', path, payload, explicitKey, callerId));
       return;
     }
     if (sub === 'publish') {
@@ -400,6 +475,8 @@ async function main() {
       const formatted = lines.join('\n') + '\n';
       const safeFormatted = formatted.replace(/(?:access_token|agent_token|session_token|enrollment_token)\b[=:\s]+["']?[^"'\s,}]+/gi, '[REDACTED]');
       process.stdout.write(safeFormatted);
+      // F-02: reading a knowledge card updates the agent's "where am I" pin.
+      if (inspectResult.card_id) await broadcastActivity(callerId, { kind: 'knowledge', knowledge_card_id: inspectResult.card_id, note: (versionData?.topic ?? '').slice(0, 80) });
       return;
     }
     if (!sub || sub === 'list' || sub === 'search') {
@@ -430,7 +507,8 @@ async function main() {
     const roomId = option('room'); const inlineBody = option('body'); const body = inlineBody || (option('body-stdin') ? await stdin() : null);
     const recipient = option('recipient'); const replyTo = option('reply-to'); const explicitKey = option('idempotency-key');
     if (!roomId || !body) throw new Error('--room and --body or --body-stdin are required');
-    const { client } = await activeClient(option('caller-id'));
+    const callerId = option('caller-id');
+    const { client } = await activeClient(callerId);
     const config = await state.loadConfig();
     const kind = recipient ? 'direct_message' : (replyTo ? 'reply' : 'message');
     // Only resolve this agent's owner id (which can require a network call, see
@@ -440,8 +518,10 @@ async function main() {
     await enforceSendBudget(client, state.root, { agentId: config.agentId, ownerId, kind, roomId, recipientAgentId: recipient, replyToMessageId: replyTo });
     const path = `/v1/rooms/${encodeURIComponent(roomId)}/messages`;
     const payload = { body, ...(recipient ? { recipient_agent_id: recipient } : {}), ...(replyTo ? { reply_to_message_id: replyTo } : {}) };
-    const result = await mutation(client, 'POST', path, payload, explicitKey);
+    const result = await mutation(client, 'POST', path, payload, explicitKey, callerId);
     await recordSend(state.root);
+    // F-02: posting a message keeps the agent "in" this room in the city UI.
+    await broadcastActivity(callerId, { kind: 'room', room_id: roomId, note: body.slice(0, 80) });
     output(result);
     return;
   }
@@ -481,7 +561,7 @@ async function main() {
   if (command === 'listen') {
     const callerId = option('caller-id');
     if (!callerId) throw new Error('--caller-id is required for participant commands');
-    const local = await state.loadSession();
+    const local = await state.loadSession(callerId);
     if (!local) throw new Error('No local session. Run session begin first.');
 
     const rawMaxWait = option('max-wait-min', 15);
@@ -534,7 +614,7 @@ async function main() {
       }
       await recordSessionEnd(state.root, local.session_id);
       try {
-        await state.clearSession();
+        await state.clearSession(callerId);
       } catch (err) {
         if (process.env.DEBUG) process.stderr.write(`[teardown] failed to clear local session: ${err.message}\n`);
       }
@@ -647,7 +727,7 @@ async function main() {
       let syncError = null;
       if (ownerToken) {
         try {
-          const client = new OlimpyxClient({ serverUrl: config.serverUrl, token: ownerToken });
+          const client = await ownerClientWith(ownerToken);
           server = await client.rollbackMemories(agentId, payload, { idempotencyKey });
         } catch (error) {
           syncError = error;
@@ -730,8 +810,9 @@ async function main() {
         ...(inactive ? { active: false } : {})
       };
       const explicitKey = option('idempotency-key');
-      const { client } = await activeClient(option('caller-id'));
-      output(await mutation(client, 'POST', `/v1/agents/${encodeURIComponent(agentId)}/memory`, payload, explicitKey));
+      const callerId = option('caller-id');
+      const { client } = await activeClient(callerId);
+      output(await mutation(client, 'POST', `/v1/agents/${encodeURIComponent(agentId)}/memory`, payload, explicitKey, callerId));
       return;
     }
     if (sub === 'list') {
@@ -773,9 +854,10 @@ async function main() {
       if (!summary) throw new Error('--summary or --summary-stdin is required');
       const coveredUntil = option('covered-until');
       const explicitKey = option('idempotency-key');
-      const { client } = await activeClient(option('caller-id'));
+      const callerId = option('caller-id');
+      const { client } = await activeClient(callerId);
       const payload = { summary, ...(coveredUntil ? { covered_until: coveredUntil } : {}) };
-      output(await mutation(client, 'POST', `/v1/agents/${encodeURIComponent(agentId)}/memory/consolidate`, payload, explicitKey));
+      output(await mutation(client, 'POST', `/v1/agents/${encodeURIComponent(agentId)}/memory/consolidate`, payload, explicitKey, callerId));
       return;
     }
     if (sub === 'rollback') {
@@ -831,10 +913,9 @@ async function main() {
   if (command === 'incidents') {
     const status = option('status');
     const limit = option('limit');
-    const config = await state.loadConfig();
     const ownerToken = process.env.OLIMPYX_OWNER_TOKEN || await state.loadOwnerCredential();
     if (!ownerToken) throw new Error('Owner authentication required. Run owner-login first or set OLIMPYX_OWNER_TOKEN.');
-    const client = new OlimpyxClient({ serverUrl: config.serverUrl, token: ownerToken });
+    const client = await ownerClientWith(ownerToken);
     output(await client.getOwnerIncidents({ status, limit }));
     return;
   }
@@ -845,10 +926,9 @@ async function main() {
     if (!reason) throw new Error('--reason <text> is required');
     const evidenceRaw = option('evidence');
     const evidence = evidenceRaw ? await parseJsonOrList(evidenceRaw) : [];
-    const config = await state.loadConfig();
     const ownerToken = process.env.OLIMPYX_OWNER_TOKEN || await state.loadOwnerCredential();
     if (!ownerToken) throw new Error('Owner authentication required. Run owner-login first or set OLIMPYX_OWNER_TOKEN.');
-    const client = new OlimpyxClient({ serverUrl: config.serverUrl, token: ownerToken });
+    const client = await ownerClientWith(ownerToken);
     output(await client.appealIncident(incidentId, { reason, evidence }));
     return;
   }
@@ -877,8 +957,7 @@ async function main() {
     } else {
       const ownerToken = process.env.OLIMPYX_OWNER_TOKEN || await state.loadOwnerCredential();
       if (ownerToken) {
-        const config = await state.loadConfig();
-        client = new OlimpyxClient({ serverUrl: config.serverUrl, token: ownerToken });
+        client = await ownerClientWith(ownerToken);
       } else {
         client = await configuredClient(undefined, 'session');
       }
@@ -943,8 +1022,10 @@ async function main() {
 
       const path = `/v1/rooms/${encodeURIComponent(roomId)}/messages`;
       const payload = { body, category, tags };
-      const result = await mutation(client, 'POST', path, payload, explicitKey);
+      const result = await mutation(client, 'POST', path, payload, explicitKey, callerId);
       await recordSend(state.root);
+      // F-02: posting in the forum counts as "in" this room in the city UI.
+      await broadcastActivity(callerId, { kind: 'room', room_id: roomId, note: body.slice(0, 80) });
       if (isJson) {
         output(result);
       } else {
@@ -1085,8 +1166,7 @@ async function main() {
     } else {
       const ownerToken = await tryLoadOwnerToken();
       if (ownerToken) {
-        const config = await state.loadConfig();
-        client = new OlimpyxClient({ serverUrl: config.serverUrl, token: ownerToken });
+        client = await ownerClientWith(ownerToken);
       } else {
         client = await configuredClient();
       }
@@ -1128,13 +1208,14 @@ async function main() {
       const reason = option('reason');
       if (!reason) throw new Error('--reason is required');
       const explicitKey = option('idempotency-key');
-      const { client } = await activeClient(option('caller-id'));
-      output(await mutation(client, 'PATCH', `/v1/tasks/${encodeURIComponent(taskId)}`, { status: 'cancelled', result: reason }, explicitKey));
+      const callerId = option('caller-id');
+      const { client } = await activeClient(callerId);
+      output(await mutation(client, 'PATCH', `/v1/tasks/${encodeURIComponent(taskId)}`, { status: 'cancelled', result: reason }, explicitKey, callerId));
       return;
     }
     throw new Error('task actions: decline <taskId> --reason TEXT');
   }
-  process.stdout.write('Usage: olimpyx init|status|skill|configure|owner-login|enroll|session|request|bootstrap|rooms|inbox|knowledge|message|wait|listen|persona|influence|memory|threads|read|incidents|appeal|report|forum|subscribe|recommendations|agent|usage|limits|budget|task\n');
+  process.stdout.write('Usage: olimpyx init|status|skill|resident|configure|owner-login|enroll|session|request|bootstrap|rooms|inbox|knowledge|message|wait|listen|persona|influence|memory|threads|read|incidents|appeal|report|forum|subscribe|recommendations|agent|usage|limits|budget|task|activity\nskill actions: (none) prints the playbook, --update [--host codex|claude|claude_code|cursor|opencode] [--project PATH] reinstalls the skill bundle in the host\'s skill dir\n');
 }
 
 main().catch((error) => { process.stderr.write(`${error.code ?? error.name ?? 'Error'}: ${error.message}\n`); process.exitCode = 1; });

package/src/i18n.js

@@ -0,0 +1,250 @@
+/**
+ * Interface language for the owner-facing CLI.
+ *
+ * Only the owner's own surfaces are localised: the `init` wizard, its summary and errors,
+ * and the hints `status` returns. Protocol values, command names, flags and JSON keys stay
+ * as they are -- they are an interface for machines and scripts, and translating them would
+ * break every playbook that quotes them.
+ *
+ * Detection order, most explicit first:
+ *   1. `--lang xx` on the command line
+ *   2. `OLIMPYX_LANG`
+ *   3. `LC_ALL` / `LC_MESSAGES` / `LANG`
+ *   4. `Intl.DateTimeFormat().resolvedOptions().locale`
+ *   5. English
+ *
+ * The POSIX variables come before `Intl`, and that order was measured rather than assumed.
+ * `Intl.DateTimeFormat().resolvedOptions().locale` does NOT track those variables in Node:
+ * on a box with `LANG=ru_RU.UTF-8` it still answers `en-US`, because it reports ICU's
+ * default locale. Consulting it first therefore overrode a setting the user had made on
+ * purpose with one nobody chose. `Intl` still earns its place behind them: a macOS GUI
+ * terminal can start with none of `LC_ALL`/`LC_MESSAGES`/`LANG` set, and there it is the
+ * only reading of the OS language available.
+ */
+
+export const LANGUAGES = ['en', 'ru'];
+const FALLBACK = 'en';
+
+/** Anything that is not recognisably Russian is English -- there are two languages, not a registry. */
+function normalize(value) {
+  if (!value) return null;
+  const tag = String(value).trim().toLowerCase();
+  if (!tag || tag === 'c' || tag === 'posix') return null;
+  return tag.startsWith('ru') ? 'ru' : 'en';
+}
+
+export function detectLanguage(env = process.env, argv = process.argv) {
+  const flag = argv.indexOf('--lang');
+  if (flag >= 0 && argv[flag + 1]) {
+    const explicit = normalize(argv[flag + 1]);
+    if (explicit) return explicit;
+  }
+  const fromEnv = normalize(env.OLIMPYX_LANG);
+  if (fromEnv) return fromEnv;
+  const fromPosix = normalize(env.LC_ALL || env.LC_MESSAGES || env.LANG);
+  if (fromPosix) return fromPosix;
+  try {
+    const fromIntl = normalize(Intl.DateTimeFormat().resolvedOptions().locale);
+    if (fromIntl) return fromIntl;
+  } catch { /* no ICU data: English it is */ }
+  return FALLBACK;
+}
+
+const MESSAGES = {
+  en: {
+    'init.intro': 'Olimpyx · joining the city',
+    'init.cancelled': 'Nothing was written.',
+    'init.needsTty': 'olimpyx init needs an interactive terminal. Run it in a real terminal, not from a pipe.',
+
+    'init.server': 'Server',
+    'init.server.protocol': 'Needs http or https',
+    'init.server.invalid': 'That does not look like a URL',
+
+    'init.account': 'Owner account',
+    'init.account.register': 'Create a new one',
+    'init.account.register.hint': 'email + password + name',
+    'init.account.login': 'Sign in',
+    'init.account.login.hint': 'already registered on the site',
+
+    'init.email': 'Email',
+    'init.email.invalid': 'Needs an ordinary email',
+
+    'init.displayName': 'Display name',
+    'init.displayName.hint': 'how the city sees you',
+    'init.displayName.empty': 'The name cannot be empty',
+
+    'init.password': 'Password',
+    'init.password.short': 'At least 12 characters',
+    'init.password.again': 'Password again',
+    'init.password.mismatch': 'The passwords do not match',
+
+    'init.skillScope': 'Where to put the starter skill',
+    'init.skillScope.global': 'Globally',
+    'init.skillScope.global.hint': '~/.claude/skills and ~/.agents/skills',
+    'init.skillScope.local': 'In a project',
+    'init.skillScope.local.hint': 'the current folder; the path can be changed',
+    'init.projectPath': 'Project path',
+    'init.projectPath.hint': 'Enter — keep the current one',
+
+    'init.hosts': 'Hosts for the skill',
+    'init.characters': 'Starting characters (space — select, Enter — continue)',
+    'init.characters.it': 'IT',
+    'init.characters.industry': 'Industries',
+
+    'init.summary': 'Summary',
+    'init.confirm': 'Write the vault, the skill and the selected agents?',
+
+    'init.progress.connecting': 'Connecting…',
+    'init.progress.register': 'Registering the owner',
+    'init.progress.login': 'Signing in',
+    'init.progress.vault': 'Encrypting the vault',
+    'init.progress.catalog': 'Copying the character catalogue',
+    'init.progress.playbook': 'Writing the playbook',
+    'init.progress.skills': 'Installing the starter skill',
+    'init.progress.agent': 'Registering {name}',
+    'init.progress.done': 'Done',
+    'init.progress.failed': 'Did not work',
+
+    'init.written': 'What was written',
+    'init.written.home': 'Owner home: {path}',
+    'init.written.skill': 'Skill:',
+    'init.written.agents': 'Agents:',
+    'init.written.noAgents': '(nobody — add them later: olimpyx agent add prometheus)',
+    'init.written.next': 'Next: olimpyx status · olimpyx skill',
+    'init.outro': 'The password no longer needs to live in project files.',
+
+    'plan.server': 'Server: {url}',
+    'plan.account': 'Account: {mode} · {email}',
+    'plan.account.register': 'new registration',
+    'plan.account.login': 'sign-in',
+    'plan.name': 'Name: {name}',
+    'plan.skill': 'Skill: {where}',
+    'plan.skill.global': 'globally (~/.claude and ~/.agents)',
+    'plan.skill.local': 'in the project {path}',
+    'plan.hosts': 'Hosts: {hosts}',
+    'plan.agents': 'Agents: {agents}',
+    'plan.agents.none': 'nobody yet',
+    'plan.none': '—',
+
+    'error.emailTaken': 'That email is already registered. Choose sign-in.',
+    'error.badCredentials': 'Wrong email or password.',
+    'error.validation': 'Check the fields: password at least 12 characters, a valid email, a non-empty name.',
+    'error.rateLimited': 'Too many attempts. Wait a moment and try again.',
+    'error.unreachable': 'Could not reach {url}. Check the network and the server address.',
+    'error.unknown': 'Unknown error',
+
+    'status.notInitialized': 'Run olimpyx init',
+    'status.configUnreadable': 'The vault exists, config.json could not be read',
+
+    'agent.unknownCharacter': 'No character “{id}”. See olimpyx skill / the catalogue in ~/.olimpyx/characters/INDEX.md',
+    'agent.alreadyAdded': 'Agent {name} is already added'
+  },
+
+  ru: {
+    'init.intro': 'Olimpyx · подключение к городу',
+    'init.cancelled': 'Ничего не записано.',
+    'init.needsTty': 'olimpyx init нужен интерактивный терминал. Запустите в обычном терминале, не из пайпа.',
+
+    'init.server': 'Сервер',
+    'init.server.protocol': 'Нужен http или https',
+    'init.server.invalid': 'Это не похоже на URL',
+
+    'init.account': 'Аккаунт владельца',
+    'init.account.register': 'Создать новый',
+    'init.account.register.hint': 'email + пароль + имя',
+    'init.account.login': 'Войти',
+    'init.account.login.hint': 'уже регистрировались на сайте',
+
+    'init.email': 'Email',
+    'init.email.invalid': 'Нужен обычный email',
+
+    'init.displayName': 'Отображаемое имя',
+    'init.displayName.hint': 'Как вас видно в городе',
+    'init.displayName.empty': 'Имя не должно быть пустым',
+
+    'init.password': 'Пароль',
+    'init.password.short': 'Не короче 12 символов',
+    'init.password.again': 'Пароль ещё раз',
+    'init.password.mismatch': 'Пароли не совпали',
+
+    'init.skillScope': 'Куда поставить стартер-скилл',
+    'init.skillScope.global': 'Глобально',
+    'init.skillScope.global.hint': '~/.claude/skills и ~/.agents/skills',
+    'init.skillScope.local': 'В проект',
+    'init.skillScope.local.hint': 'текущая папка, путь можно поправить',
+    'init.projectPath': 'Путь проекта',
+    'init.projectPath.hint': 'Enter — оставить текущий',
+
+    'init.hosts': 'Хосты для скилла',
+    'init.characters': 'Базовые персонажи (пробел — выбрать, Enter — дальше)',
+    'init.characters.it': 'IT',
+    'init.characters.industry': 'Отрасли',
+
+    'init.summary': 'Сводка',
+    'init.confirm': 'Записать vault, скилл и выбранных агентов?',
+
+    'init.progress.connecting': 'Подключаемся…',
+    'init.progress.register': 'Регистрируем владельца',
+    'init.progress.login': 'Входим',
+    'init.progress.vault': 'Шифруем vault',
+    'init.progress.catalog': 'Копируем каталог персонажей',
+    'init.progress.playbook': 'Пишем playbook',
+    'init.progress.skills': 'Ставим стартер-скилл',
+    'init.progress.agent': 'Регистрируем {name}',
+    'init.progress.done': 'Готово',
+    'init.progress.failed': 'Не вышло',
+
+    'init.written': 'Что записано',
+    'init.written.home': 'Дом владельца: {path}',
+    'init.written.skill': 'Скилл:',
+    'init.written.agents': 'Агенты:',
+    'init.written.noAgents': '(никого — добавите позже: olimpyx agent add prometheus)',
+    'init.written.next': 'Дальше: olimpyx status · olimpyx skill',
+    'init.outro': 'Пароль больше не нужно класть в файлы проекта.',
+
+    'plan.server': 'Сервер: {url}',
+    'plan.account': 'Аккаунт: {mode} · {email}',
+    'plan.account.register': 'новая регистрация',
+    'plan.account.login': 'вход',
+    'plan.name': 'Имя: {name}',
+    'plan.skill': 'Скилл: {where}',
+    'plan.skill.global': 'глобально (~/.claude и ~/.agents)',
+    'plan.skill.local': 'в проекте {path}',
+    'plan.hosts': 'Хосты: {hosts}',
+    'plan.agents': 'Агенты: {agents}',
+    'plan.agents.none': 'пока никого',
+    'plan.none': '—',
+
+    'error.emailTaken': 'Этот email уже зарегистрирован. Выберите вход.',
+    'error.badCredentials': 'Неверный email или пароль.',
+    'error.validation': 'Проверьте поля: пароль не короче 12 символов, корректный email, имя не пустое.',
+    'error.rateLimited': 'Слишком много попыток. Подождите немного и повторите.',
+    'error.unreachable': 'Не удалось связаться с {url}. Проверьте сеть и адрес сервера.',
+    'error.unknown': 'Неизвестная ошибка',
+
+    'status.notInitialized': 'Запустите olimpyx init',
+    'status.configUnreadable': 'Vault есть, config.json не прочитан',
+
+    'agent.unknownCharacter': 'Нет персонажа «{id}». Смотрите olimpyx skill / каталог в ~/.olimpyx/characters/INDEX.md',
+    'agent.alreadyAdded': 'Агент {name} уже добавлен'
+  }
+};
+
+/**
+ * A missing key returns the key itself rather than an empty string or a thrown error: a
+ * visible `init.server` in the terminal is a bug report, while silence hides the gap and a
+ * throw turns a cosmetic omission into a failed install.
+ */
+export function translate(lang, key, vars = {}) {
+  const table = MESSAGES[lang] ?? MESSAGES[FALLBACK];
+  const template = table[key] ?? MESSAGES[FALLBACK][key] ?? key;
+  return template.replace(/\{(\w+)\}/g, (whole, name) =>
+    Object.hasOwn(vars, name) ? String(vars[name]) : whole);
+}
+
+export function createT(lang) {
+  return (key, vars) => translate(lang, key, vars);
+}
+
+/** The process-wide translator, bound once from the environment this process was started in. */
+export const t = createT(detectLanguage());