@myvillage/cli 1.10.2 → 1.17.0

package/src/commands/wisdom.js

@@ -0,0 +1,185 @@
+import chalk from 'chalk';
+import { readFileSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { isAuthenticated } from '../utils/auth.js';
+import { brand, villageSpinner } from '../utils/brand.js';
+import { agentExists } from '../utils/local-agent.js';
+import {
+  listVillageBooks,
+  exportVillageBook,
+  importVillageBook,
+} from '../utils/api.js';
+import {
+  parseWisdom,
+  serializeWisdom,
+  slugify,
+  getAgentWisdomDir,
+  ensureWisdomDir,
+  readAgentWisdom,
+  writeWisdomFile,
+} from '../utils/wisdom.js';
+
+function requireAuth() {
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  ✗ Authentication required. Run \'myvillage login\' first.'));
+    return false;
+  }
+  return true;
+}
+
+function resolveAgentName(name, action) {
+  if (!name) {
+    console.log(chalk.red(`  ✗ Specify an agent: myvillage wisdom ${action} --agent <name>\n`));
+    return null;
+  }
+  if (!agentExists(name)) {
+    console.log(chalk.red(`  ✗ Agent "${name}" not found.\n`));
+    return null;
+  }
+  return name;
+}
+
+// ── list ────────────────────────────────────────────────
+
+export async function wisdomListCommand(options = {}) {
+  if (options.remote) {
+    if (!requireAuth()) return;
+    try {
+      const result = await listVillageBooks({ bookTypeId: 'wisdom' });
+      // The API can return either an array directly or wrapped in { data }
+      const books = Array.isArray(result) ? result : result?.data || [];
+      const wisdom = books.filter(b => b.bookType?.name === 'wisdom' || !b.bookType);
+      if (wisdom.length === 0) {
+        console.log(brand.teal('  No community wisdom files published yet.\n'));
+        return;
+      }
+      console.log(brand.teal(`  ${wisdom.length} wisdom file(s) on the network:\n`));
+      for (const w of wisdom) {
+        console.log(`  ${brand.gold(w.id)}  ${chalk.bold(w.name)}`);
+        if (w.description) console.log(`    ${chalk.dim(w.description)}`);
+      }
+      console.log('');
+    } catch (err) {
+      const msg = err.response?.data?.error || err.message;
+      console.log(chalk.red(`  ✗ Failed to list remote wisdom: ${msg}\n`));
+    }
+    return;
+  }
+
+  // Local mode: list every wisdom file across every agent on disk
+  if (!options.agent) {
+    console.log(chalk.yellow('  Hint: pass --agent <name> to list one agent\'s wisdom, or --remote to list community-published wisdom.\n'));
+    return;
+  }
+  if (!resolveAgentName(options.agent, 'list')) return;
+  const files = readAgentWisdom(options.agent);
+  if (files.length === 0) {
+    console.log(brand.teal(`  Agent "${options.agent}" has no wisdom files yet.\n`));
+    return;
+  }
+  console.log(brand.teal(`  ${files.length} local wisdom file(s) for "${options.agent}":\n`));
+  for (const w of files) {
+    const linked = w.villageBookId ? brand.gold(` (synced ${w.villageBookId})`) : chalk.dim(' (local-only)');
+    console.log(`  ${chalk.bold(w.name)}${linked}`);
+    if (w.description) console.log(`    ${chalk.dim(w.description)}`);
+    console.log(`    ${chalk.dim(w.path)}`);
+  }
+  console.log('');
+}
+
+// ── pull ────────────────────────────────────────────────
+
+export async function wisdomPullCommand(id, options = {}) {
+  if (!requireAuth()) return;
+  if (!id) {
+    console.log(chalk.red('  ✗ Specify a village book id: myvillage wisdom pull <id> --into <agent>\n'));
+    return;
+  }
+  if (!options.into) {
+    console.log(chalk.red('  ✗ Specify a target agent: myvillage wisdom pull <id> --into <agent>\n'));
+    return;
+  }
+  if (!resolveAgentName(options.into, 'pull')) return;
+
+  const spinner = villageSpinner('Fetching wisdom from the network...').start();
+  try {
+    const text = await exportVillageBook(id);
+    const { frontmatter } = parseWisdom(text);
+    const slug = slugify(frontmatter.name || id);
+    const dir = ensureWisdomDir(options.into);
+    const filePath = join(dir, `${slug}.wisdom`);
+    writeWisdomFile(filePath, parseWisdom(text)); // re-serialize for consistent formatting
+    spinner.succeed(`Wisdom "${frontmatter.name || id}" saved to ${filePath}`);
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    spinner.fail(`Failed to pull wisdom: ${msg}`);
+  }
+}
+
+// ── push ────────────────────────────────────────────────
+
+export async function wisdomPushCommand(filePath) {
+  if (!requireAuth()) return;
+  if (!filePath) {
+    console.log(chalk.red('  ✗ Specify a .wisdom file: myvillage wisdom push <file>\n'));
+    return;
+  }
+  if (!existsSync(filePath)) {
+    console.log(chalk.red(`  ✗ File not found: ${filePath}\n`));
+    return;
+  }
+
+  const content = readFileSync(filePath, 'utf-8');
+  const spinner = villageSpinner('Publishing wisdom to the network...').start();
+  try {
+    const result = await importVillageBook({ content });
+    const book = result?.data || result;
+    if (book?.id) {
+      // Save the assigned id back into the local file so future pushes update
+      // the same row instead of creating duplicates.
+      const parsed = parseWisdom(content);
+      parsed.frontmatter.villageBookId = book.id;
+      writeWisdomFile(filePath, parsed);
+      spinner.succeed(`Published as ${book.id}`);
+    } else {
+      spinner.succeed('Published.');
+    }
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    spinner.fail(`Failed to push wisdom: ${msg}`);
+  }
+}
+
+// ── new ─────────────────────────────────────────────────
+
+export async function wisdomNewCommand(name, options = {}) {
+  if (!name) {
+    console.log(chalk.red('  ✗ Specify a name: myvillage wisdom new <name> --agent <agent>\n'));
+    return;
+  }
+  if (!options.agent) {
+    console.log(chalk.red('  ✗ Specify a target agent: myvillage wisdom new <name> --agent <agent>\n'));
+    return;
+  }
+  if (!resolveAgentName(options.agent, 'new')) return;
+
+  const slug = slugify(name);
+  const dir = ensureWisdomDir(options.agent);
+  const filePath = join(dir, `${slug}.wisdom`);
+  if (existsSync(filePath)) {
+    console.log(chalk.yellow(`  ${filePath} already exists; edit it instead.\n`));
+    return;
+  }
+
+  const template = serializeWisdom({
+    frontmatter: {
+      name: slug,
+      description: options.description || 'Describe what this skill does and when to apply it.',
+      trigger: options.trigger || 'Describe the condition that should activate this skill.',
+    },
+    body: '<!-- The body of this wisdom file. Write it as a short skill: tone, structure, examples. The agent loads it into its system prompt every iteration. -->\n',
+  });
+  writeWisdomFile(filePath, parseWisdom(template));
+  console.log(brand.green(`  ✓ Wisdom scaffolded at ${filePath}`));
+  console.log(brand.teal(`    Edit the body, then publish with: myvillage wisdom push ${filePath}\n`));
+}

package/src/index.js

@@ -2,6 +2,12 @@ import { Command } from 'commander';
 import { createRequire } from 'module';
 import updateNotifier from 'update-notifier';
 import { loginCommand } from './commands/login.js';
+import {
+  mediaDraftCreateCommand,
+  mediaDraftEditCommand,
+  mediaDraftListCommand,
+  mediaDraftStatusCommand,
+} from './commands/media.js';
 import { logoutCommand } from './commands/logout.js';
 import { createGameCommand } from './commands/create-game.js';
 import { createCommand } from './commands/create-app.js';
@@ -45,7 +51,25 @@ import {
   agentLogsCommand,
   agentAddToolCommand,
   agentRemoveToolCommand,
+  agentTaskListCommand,
+  agentTaskAssignCommand,
+  agentMemoryCommand,
+  agentRecallCommand,
+  agentRememberCommand,
 } from './commands/agent-local.js';
+import {
+  agentGrantCommand,
+  agentRevokeCommand,
+  agentGrantsCommand,
+} from './commands/agent-grant.js';
+import {
+  agentRegisterClientCommand,
+  agentListClientsCommand,
+  agentViewClientCommand,
+  agentEditClientCommand,
+  agentDeactivateClientCommand,
+  agentRotateClientKeyCommand,
+} from './commands/agent-client.js';
 import {
   bizreqsNewCommand,
   bizreqsSpecCommand,
@@ -69,6 +93,12 @@ import { checkinCommand } from './commands/checkin.js';
 import { discoverCommand } from './commands/discover.js';
 import { logCommand } from './commands/log.js';
 import { storyCommand } from './commands/story.js';
+import {
+  wisdomListCommand,
+  wisdomPullCommand,
+  wisdomPushCommand,
+  wisdomNewCommand,
+} from './commands/wisdom.js';
 import {
   soulprintInitCommand,
   soulprintIngestCommand,
@@ -408,6 +438,98 @@ export function run() {
     .description('Remove an MCP server tool from a local agent')
     .action(agentRemoveToolCommand);
 
+  // Task queue commands — assign and inspect work for a developer's agent
+  agentCmd
+    .command('task-list <name>')
+    .description('List tasks queued for a local agent')
+    .option('--status <status>', 'Filter by status (PENDING|IN_PROGRESS|COMPLETED|FAILED|CANCELLED)')
+    .option('--limit <n>', 'Max number of tasks to show', '20')
+    .action(agentTaskListCommand);
+
+  agentCmd
+    .command('task-assign <name>')
+    .description('Assign a task to a local agent (it will pick it up on next poll)')
+    .option('--type <type>', 'Task type (e.g., CLIENT_TASK, GENERATE_POST, SHARE_KNOWLEDGE)')
+    .option('--instruction <text>', 'Free-text instruction (required for CLIENT_TASK)')
+    .option('--input <json>', 'JSON-encoded structured input payload')
+    .option('--priority <n>', 'Priority 1-10 (lower runs first)', '5')
+    .action(agentTaskAssignCommand);
+
+  // Agent memory (short-term KV state) and recall (long-term searchable memory)
+  agentCmd
+    .command('memory <name> <action> [args...]')
+    .description('Read/write an agent\'s short-term memory: list | get <key> | set <key> <value> | delete <key>')
+    .action((name, action, args = []) => agentMemoryCommand(name, action, ...args));
+
+  agentCmd
+    .command('recall <name> <query>')
+    .description('Search this agent\'s long-term memory (Knowledge submissions it authored)')
+    .option('--limit <n>', 'Max results to show', '10')
+    .action(agentRecallCommand);
+
+  agentCmd
+    .command('remember <name> <text>')
+    .description('Save a memory to this agent\'s long-term store (Knowledge submission with source=AI_AGENT)')
+    .option('--summary <text>', 'Short summary of the memory')
+    .option('--themes <list>', 'Comma-separated tags')
+    .option('--sharing <option>', 'PRIVATE | VILLAGE_ONLY | PUBLIC', 'PRIVATE')
+    .action(agentRememberCommand);
+
+  // Per-agent OAuth credential grants
+  agentCmd
+    .command('grants <name>')
+    .description('List active OAuth credential grants for a local agent')
+    .action(agentGrantsCommand);
+
+  agentCmd
+    .command('grant <name> <provider>')
+    .description('Grant the agent access to a connected OAuth provider (google|microsoft|zoom)')
+    .action(agentGrantCommand);
+
+  agentCmd
+    .command('revoke <name> <provider>')
+    .description('Revoke an OAuth provider grant from the agent')
+    .action(agentRevokeCommand);
+
+  // Client agent registration commands
+  agentCmd
+    .command('register-client')
+    .description('Register a client application for agent automation')
+    .option('--agent <handle>', 'Agent handle')
+    .option('--client-id <id>', 'Client identifier (lowercase)')
+    .option('--name <name>', 'Client display name')
+    .option('--url <url>', 'Client base URL')
+    .option('--workflow <type>', 'Workflow type (e.g., submission_processor)')
+    .option('--schedule <cron>', 'Cron schedule expression')
+    .option('--timezone <tz>', 'Timezone (default: America/Chicago)')
+    .option('--env-file <path>', 'Write API key to this .env file')
+    .action(agentRegisterClientCommand);
+
+  agentCmd
+    .command('list-clients')
+    .description('List all registered client agent configs')
+    .action(agentListClientsCommand);
+
+  agentCmd
+    .command('view-client <configId>')
+    .description('View a client agent config')
+    .action(agentViewClientCommand);
+
+  agentCmd
+    .command('edit-client <configId>')
+    .description('Edit a client agent config')
+    .action(agentEditClientCommand);
+
+  agentCmd
+    .command('deactivate-client <configId>')
+    .description('Deactivate a client agent config')
+    .action(agentDeactivateClientCommand);
+
+  agentCmd
+    .command('rotate-client-key <configId>')
+    .description('Rotate the API key for a client agent config')
+    .action(agentRotateClientKeyCommand);
+
   // ── Village Content Pipeline ───────────────────────────
 
   program
@@ -432,6 +554,49 @@ export function run() {
     .description('Share a story or wisdom with the network')
     .action(storyCommand);
 
+  // ── Media: Soulprint Reels (mobile-app posts) ──────────
+
+  const mediaCmd = program
+    .command('media')
+    .description('Manage Soulprint Reels (internal social posts shown in the mobile app)');
+
+  const mediaDraftCmd = mediaCmd
+    .command('draft')
+    .description('Reel draft commands');
+
+  mediaDraftCmd
+    .command('create')
+    .description('Create a new reel draft (video, photo, carousel, audio, text)')
+    .option('-f, --file <path>', 'Attach a media file (repeatable)', (v, prev) => prev ? [...prev, v] : [v])
+    .option('-a, --asset-type <type>', 'Asset type when --file is given (IMAGE, VIDEO, THUMBNAIL, DOCUMENT)')
+    .option('--submit', 'Auto-submit the draft for review after creation')
+    .action(mediaDraftCreateCommand);
+
+  mediaDraftCmd
+    .command('edit <id>')
+    .description('Edit a DRAFT or REJECTED reel draft')
+    .action(mediaDraftEditCommand);
+
+  mediaDraftCmd
+    .command('list')
+    .description('List reel drafts')
+    .option('--status <status>', 'Filter by status (DRAFT, SUBMITTED, IN_REVIEW, APPROVED, REJECTED, PUBLISHED)')
+    .option('--content-type <type>', 'Filter by content type (VIDEO, PHOTO, CAROUSEL, AUDIO, TEXT)')
+    .option('--platform <platform>', '[Deprecated] Legacy platform alias — maps forward to content type')
+    .option('--visibility <visibility>', 'Filter by visibility (PUBLIC, COMMUNITY, PRIVATE)')
+    .option('--community-id <id>', 'Filter by community')
+    .option('--search <query>', 'Search captions / titles / quotes')
+    .option('-n, --limit <number>', 'Number of drafts', '20')
+    .option('--offset <number>', 'Pagination offset', '0')
+    .option('--sort <sort>', 'Sort: newest, oldest, publish_date', 'newest')
+    .option('--json', 'Output raw JSON')
+    .action(mediaDraftListCommand);
+
+  mediaDraftCmd
+    .command('status <id>')
+    .description('Show status of a reel draft')
+    .action(mediaDraftStatusCommand);
+
   // ── BizReqs: Business Requirements Pipeline ───────────
 
   const bizreqsCmd = program
@@ -483,6 +648,40 @@ export function run() {
 
   // ── SoulPrint Studio: Model Training Pipeline ───────────
 
+  // \u2500\u2500 Wisdom: agent skill packs (Books of Wisdom) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+  const wisdomCmd = program
+    .command('wisdom')
+    .description('Manage .wisdom files \u2014 agent skill packs backed by the network\'s Books of Wisdom');
+
+  wisdomCmd
+    .command('list')
+    .description('List wisdom files (use --remote for community-published, --agent for local)')
+    .option('--remote', 'List community-published wisdom on the network')
+    .option('--agent <name>', 'List a local agent\'s wisdom files')
+    .action(wisdomListCommand);
+
+  wisdomCmd
+    .command('pull <id>')
+    .description('Fetch a community wisdom file and save it into a local agent')
+    .requiredOption('--into <agent>', 'Local agent to save the wisdom file into')
+    .action(wisdomPullCommand);
+
+  wisdomCmd
+    .command('push <file>')
+    .description('Publish a .wisdom file to the network so other agents can use it')
+    .action(wisdomPushCommand);
+
+  wisdomCmd
+    .command('new <name>')
+    .description('Scaffold a new local .wisdom file for an agent')
+    .requiredOption('--agent <name>', 'Local agent to add the wisdom file to')
+    .option('--description <text>', 'Short description shown in the agent\'s skill list')
+    .option('--trigger <text>', 'Condition that should activate this skill')
+    .action(wisdomNewCommand);
+
+  // \u2500\u2500 SoulPrint Studio (legacy): training pipeline \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
   const soulprintCmd = program
     .command('soulprint')
     .description('SoulPrint Studio \u2014 datasets, training, and model publishing');

package/src/utils/agentic-templates.js

@@ -40,6 +40,7 @@ export function createAgenticAppProject(targetDir, options) {
     includeRestApi = true,
     mcpToolGroups = [],
     oauthCredentials = null,
+    agentConfig = null,
   } = options;
 
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
@@ -88,7 +89,7 @@ export function createAgenticAppProject(targetDir, options) {
   writeFileSync(join(targetDir, 'package.json'), generatePackageJson(slug, description, includeMcp));
   writeFileSync(join(targetDir, 'next.config.mjs'), generateNextConfig());
   writeFileSync(join(targetDir, '.gitignore'), generateGitignore());
-  writeFileSync(join(targetDir, '.env.local'), generateEnv(oauthCredentials, hasOAuth, includeMcp));
+  writeFileSync(join(targetDir, '.env.local'), generateEnv(oauthCredentials, hasOAuth, includeMcp, agentConfig));
   writeFileSync(join(targetDir, '.env.example'), generateEnvExample(hasOAuth, includeMcp));
   writeFileSync(join(targetDir, 'README.md'), generateReadme(name, description, hasOAuth, includeMcp, includeRestApi, features));
   writeFileSync(join(targetDir, 'jsconfig.json'), generateJsConfig());
@@ -214,7 +215,7 @@ out/
 `;
 }
 
-function generateEnv(oauthCredentials, hasOAuth, includeMcp) {
+function generateEnv(oauthCredentials, hasOAuth, includeMcp, agentConfig = null) {
   const lines = [];
 
   if (hasOAuth) {
@@ -233,6 +234,11 @@ function generateEnv(oauthCredentials, hasOAuth, includeMcp) {
     lines.push('MYVILLAGEOS_MCP_URL=https://mcp.myvillageproject.ai');
   }
 
+  if (agentConfig?.apiKey) {
+    lines.push(`MYVILLAGE_AGENT_API_KEY=${agentConfig.apiKey}`);
+    lines.push(`MYVILLAGE_AGENT_CLIENT_ID=${agentConfig.clientId}`);
+  }
+
   lines.push('ANTHROPIC_API_KEY=');
 
   return lines.join('\n') + '\n';
@@ -254,6 +260,8 @@ function generateEnvExample(hasOAuth, includeMcp) {
     lines.push('MYVILLAGEOS_MCP_URL=https://mcp.myvillageproject.ai');
   }
 
+  lines.push('MYVILLAGE_AGENT_API_KEY=');
+  lines.push('MYVILLAGE_AGENT_CLIENT_ID=');
   lines.push('ANTHROPIC_API_KEY=');
 
   return lines.join('\n') + '\n';

package/src/utils/api.js

@@ -418,6 +418,44 @@ export async function listPostsByFilters(params = {}) {
   return response.data;
 }
 
+// ── Client Agent Configs API (/api/client-agents/configs) ──
+
+export async function registerClientAgent(data) {
+  const client = getPlatformClient();
+  const response = await client.post('/client-agents/configs', data);
+  return response.data;
+}
+
+export async function listClientAgentConfigs() {
+  const client = getPlatformClient();
+  const response = await client.get('/client-agents/configs');
+  return response.data;
+}
+
+export async function getClientAgentConfig(configId) {
+  const client = getPlatformClient();
+  const response = await client.get(`/client-agents/configs/${encodeURIComponent(configId)}`);
+  return response.data;
+}
+
+export async function updateClientAgentConfig(configId, data) {
+  const client = getPlatformClient();
+  const response = await client.patch(`/client-agents/configs/${encodeURIComponent(configId)}`, data);
+  return response.data;
+}
+
+export async function deactivateClientAgent(configId) {
+  const client = getPlatformClient();
+  const response = await client.delete(`/client-agents/configs/${encodeURIComponent(configId)}`);
+  return response.data;
+}
+
+export async function rotateClientAgentKey(configId) {
+  const client = getPlatformClient();
+  const response = await client.post(`/client-agents/configs/${encodeURIComponent(configId)}/rotate-key`);
+  return response.data;
+}
+
 // ── BizReqs API Client (/api/bizreqs) ───────────────────
 
 export function getBizReqsClient() {
@@ -564,3 +602,122 @@ export async function submitGameForReview(gameId) {
   const response = await client.put(`/games/${encodeURIComponent(gameId)}`, { status: 'SUBMITTED' });
   return response.data;
 }
+
+// ── Village Agents (developer agents) ───────────────────
+
+// AgentProfiles owned by the caller that aren't yet linked to a VillageAgent.
+// Used by the CLI "attach existing network identity" picker.
+export async function listMyUnlinkedAgentProfiles() {
+  const client = getNetworkClient();
+  const response = await client.get('/agents/my', { params: { unlinked: 'true' } });
+  return response.data;
+}
+
+// Create a VillageAgent. Optionally either:
+//   - link to an existing AgentProfile via `agentProfileId`
+//   - auto-create a fresh AgentProfile via `createNetworkIdentity: true`
+export async function createVillageAgent(data) {
+  const client = getPlatformClient();
+  const response = await client.post('/village-agents', data);
+  return response.data;
+}
+
+export async function listVillageAgents() {
+  const client = getPlatformClient();
+  const response = await client.get('/village-agents');
+  return response.data;
+}
+
+export async function getVillageAgent(id) {
+  const client = getPlatformClient();
+  const response = await client.get(`/village-agents/${encodeURIComponent(id)}`);
+  return response.data;
+}
+
+export async function updateVillageAgent(id, data) {
+  const client = getPlatformClient();
+  const response = await client.patch(`/village-agents/${encodeURIComponent(id)}`, data);
+  return response.data;
+}
+
+// ── Agent Task Queue ────────────────────────────────────
+
+export async function listAgentTasks(villageAgentId, params = {}) {
+  const client = getPlatformClient();
+  const response = await client.get(
+    `/village-agents/${encodeURIComponent(villageAgentId)}/tasks`,
+    { params },
+  );
+  return response.data;
+}
+
+export async function assignAgentTask(villageAgentId, data) {
+  const client = getPlatformClient();
+  const response = await client.post(
+    `/village-agents/${encodeURIComponent(villageAgentId)}/tasks`,
+    data,
+  );
+  return response.data;
+}
+
+export async function claimAgentTask(villageAgentId, taskId) {
+  const client = getPlatformClient();
+  const response = await client.post(
+    `/village-agents/${encodeURIComponent(villageAgentId)}/tasks/${encodeURIComponent(taskId)}/claim`,
+  );
+  return response.data;
+}
+
+// completeAgentTask is also used for "fail" — pass `errorMessage` to mark FAILED,
+// otherwise the task is marked COMPLETED with the given `output`.
+export async function completeAgentTask(villageAgentId, taskId, data = {}) {
+  const client = getPlatformClient();
+  const response = await client.post(
+    `/village-agents/${encodeURIComponent(villageAgentId)}/tasks/${encodeURIComponent(taskId)}/complete`,
+    data,
+  );
+  return response.data;
+}
+
+// ── Wisdom (VillageBooks repurposed as agent skill packs) ──────────
+
+export async function listVillageBooks(params = {}) {
+  const client = getPlatformClient();
+  const response = await client.get('/village-books', { params });
+  return response.data;
+}
+
+// Returns the raw .wisdom file text (YAML frontmatter + markdown body).
+export async function exportVillageBook(id) {
+  const client = getPlatformClient();
+  const response = await client.get(
+    `/village-books/${encodeURIComponent(id)}/export`,
+    { responseType: 'text', transformResponse: (data) => data },
+  );
+  return response.data;
+}
+
+export async function importVillageBook(payload) {
+  const client = getPlatformClient();
+  const response = await client.post('/village-books/import', payload);
+  return response.data;
+}
+
+// ── Knowledge (long-term agent memory) ──────────────────
+
+// Filter / search knowledge submissions. Pass `createdByAgentId` to narrow
+// to a specific agent's own memories.
+export async function listKnowledgeFiltered(params = {}) {
+  const client = getPlatformClient();
+  const response = await client.get('/knowledge/filtered', { params });
+  return response.data;
+}
+
+// Write a memory by submitting a Knowledge entry attributed to the agent.
+// Backed by /api/agent-tools/share-knowledge — the agent_profile_id override
+// makes the entry appear in this specific agent's recall results.
+export async function shareKnowledgeAsAgent(data) {
+  const client = getPlatformClient();
+  const response = await client.post('/agent-tools/share-knowledge', data);
+  return response.data;
+}