@myvillage/cli 1.5.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/commands/bizreqs.js

@@ -100,31 +100,7 @@ const recommendationParams = z.object({
 
 // ── Helper: Get Anthropic client ────────────────────────
 
-async function getAnthropicProvider() {
-  const { createAnthropic } = await import('@ai-sdk/anthropic');
-  const config = getConfig();
-  let apiKey = config.anthropicApiKey || process.env.ANTHROPIC_API_KEY;
-
-  if (!apiKey) {
-    console.log(chalk.yellow('\n  Anthropic API key required for AI-powered intake.'));
-    console.log(brand.teal('  Get yours at: https://console.anthropic.com\n'));
-
-    const { key } = await inquirer.prompt([{
-      type: 'password',
-      name: 'key',
-      message: 'Anthropic API key:',
-      mask: '*',
-      validate: (input) => input.trim().length > 0 || 'API key is required',
-    }]);
-
-    apiKey = key.trim();
-    const { setConfig } = await import('../utils/config.js');
-    setConfig({ anthropicApiKey: apiKey });
-    console.log(brand.green('  ✓ API key saved to ~/.myvillage/config.json\n'));
-  }
-
-  return createAnthropic({ apiKey });
-}
+import { getAnthropicProvider } from '../utils/ai.js';
 
 
 // ── bizreqs list ────────────────────────────────────────

package/src/commands/checkin.js

@@ -0,0 +1,149 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { z } from 'zod';
+import { isAuthenticated } from '../utils/auth.js';
+import { brand, villageSpinner } from '../utils/brand.js';
+import { createPost } from '../utils/api.js';
+import { resolveVillageContext } from '../utils/village-resolver.js';
+import { getAnthropicProvider } from '../utils/ai.js';
+import { formatCheckinSummary } from '../utils/formatters.js';
+import { discoverLogic } from './discover.js';
+
+const extractionSchema = z.object({
+  themes: z.array(z.string()).describe('Key themes from the check-in (1-4 short labels)'),
+  needs: z.array(z.string()).describe('Things the village needs help with (0-3 short labels)'),
+  offers: z.array(z.string()).describe('Things the village can offer others (0-3 short labels)'),
+  buildTrack: z.string().optional().describe('Primary build track if mentioned: game, portal, agent, data, robot, or general'),
+  summary: z.string().describe('A 2-3 sentence summary combining all responses into a cohesive check-in update'),
+});
+
+export async function checkinCommand(options) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red("  \u2717 Authentication required. Run 'myvillage login' first."));
+    return;
+  }
+
+  const ctx = await resolveVillageContext();
+  if (!ctx) return;
+
+  console.log();
+  console.log(brand.gold('  \u2743 Village Check-in'));
+  console.log(chalk.dim('  Answer a few questions about your village. AI will help organize it.\n'));
+
+  // Conversational prompts
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'work',
+      message: 'What did your village work on recently?',
+      validate: (v) => v.trim().length > 0 || 'Please share what you worked on.',
+    },
+    {
+      type: 'input',
+      name: 'stuck',
+      message: 'Any problems you\'re stuck on?',
+      default: '',
+    },
+    {
+      type: 'input',
+      name: 'share',
+      message: 'Anything you want to share with the network?',
+      default: '',
+    },
+  ]);
+
+  // AI structuring
+  const spinner = villageSpinner('Organizing your check-in...').start();
+
+  let extracted;
+  try {
+    const anthropic = await getAnthropicProvider();
+    const { generateText } = await import('ai');
+
+    const userContent = [
+      `What we worked on: ${answers.work}`,
+      answers.stuck ? `Problems we're stuck on: ${answers.stuck}` : null,
+      answers.share ? `What we want to share: ${answers.share}` : null,
+    ].filter(Boolean).join('\n');
+
+    const result = await generateText({
+      model: anthropic('claude-haiku-4-5-20251001'),
+      system: `You are a community network coordinator. Extract structured metadata from a village check-in and write a concise summary. Always call the extract_checkin tool with your analysis.`,
+      messages: [{ role: 'user', content: userContent }],
+      tools: {
+        extract_checkin: {
+          description: 'Extract structured metadata from a village check-in',
+          parameters: extractionSchema,
+        },
+      },
+      toolChoice: { type: 'tool', toolName: 'extract_checkin' },
+      maxTokens: 500,
+    });
+
+    const toolCall = result.toolCalls?.[0];
+    if (!toolCall?.args) {
+      throw new Error('AI did not return structured data');
+    }
+    extracted = toolCall.args;
+    spinner.succeed('Check-in organized');
+  } catch (err) {
+    spinner.fail('AI structuring failed — posting raw check-in');
+    // Fallback: post without AI structuring
+    extracted = {
+      themes: [],
+      needs: [],
+      offers: [],
+      buildTrack: 'general',
+      summary: [answers.work, answers.stuck, answers.share].filter(Boolean).join(' '),
+    };
+  }
+
+  // Build tags
+  const tags = ['checkin'];
+  if (extracted.buildTrack) tags.push(`track:${extracted.buildTrack}`);
+  for (const t of extracted.themes) tags.push(`theme:${t}`);
+  for (const n of extracted.needs) tags.push(`need:${n}`);
+  for (const o of extracted.offers) tags.push(`offer:${o}`);
+
+  // Create post
+  try {
+    const post = await createPost({
+      communitySlug: ctx.community.slug,
+      postType: 'DISCUSSION',
+      title: `Village Check-in: ${ctx.village.name}`,
+      body: extracted.summary,
+      tags,
+    });
+
+    formatCheckinSummary(post, {
+      villageName: ctx.village.name,
+      buildTrack: extracted.buildTrack,
+      themes: extracted.themes,
+      needs: extracted.needs,
+      offers: extracted.offers,
+    });
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    console.log(chalk.red(`  \u2717 Failed to post check-in: ${msg}`));
+    return;
+  }
+
+  // Auto-discover prompt
+  if (!options.skipDiscover) {
+    const { runDiscover } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'runDiscover',
+      message: 'Look for connections with other villages?',
+      default: true,
+    }]);
+
+    if (runDiscover) {
+      await discoverLogic(ctx, {
+        themes: extracted.themes,
+        needs: extracted.needs,
+        offers: extracted.offers,
+        track: extracted.buildTrack,
+      });
+    }
+  }
+}

package/src/commands/discover.js

@@ -0,0 +1,220 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { isAuthenticated, loadCredentials } from '../utils/auth.js';
+import { brand, villageSpinner } from '../utils/brand.js';
+import {
+  listPosts,
+  listPostsByFilters,
+  createPost,
+  getVillagerVillages,
+  getVillageCommunities,
+} from '../utils/api.js';
+import { resolveVillageContext } from '../utils/village-resolver.js';
+import { formatConnection } from '../utils/formatters.js';
+
+/**
+ * Parse prefixed tags into a structured map.
+ * e.g., ['checkin', 'track:game', 'theme:ai', 'need:mentors'] →
+ *   { themes: ['ai'], needs: ['mentors'], offers: [], track: 'game' }
+ */
+function parseTags(tags = []) {
+  const result = { themes: [], needs: [], offers: [], track: null };
+  for (const tag of tags) {
+    if (tag.startsWith('theme:')) result.themes.push(tag.replace('theme:', ''));
+    else if (tag.startsWith('need:')) result.needs.push(tag.replace('need:', ''));
+    else if (tag.startsWith('offer:')) result.offers.push(tag.replace('offer:', ''));
+    else if (tag.startsWith('track:')) result.track = tag.replace('track:', '');
+  }
+  return result;
+}
+
+/**
+ * Score a candidate post against the user's tags.
+ */
+function scoreMatch(myTags, theirTags) {
+  let score = 0;
+  const matchTypes = [];
+
+  // Need-to-offer matches (3 points each)
+  for (const need of myTags.needs) {
+    if (theirTags.offers.includes(need)) {
+      score += 3;
+      matchTypes.push(`They offer "${need}" (you need it)`);
+    }
+  }
+  for (const offer of myTags.offers) {
+    if (theirTags.needs.includes(offer)) {
+      score += 3;
+      matchTypes.push(`They need "${offer}" (you offer it)`);
+    }
+  }
+
+  // Same build track (2 points)
+  if (myTags.track && theirTags.track && myTags.track === theirTags.track) {
+    score += 2;
+    matchTypes.push(`Same track: ${myTags.track}`);
+  }
+
+  // Shared themes (1 point each)
+  for (const theme of myTags.themes) {
+    if (theirTags.themes.includes(theme)) {
+      score += 1;
+      matchTypes.push(`Shared theme: ${theme}`);
+    }
+  }
+
+  return { score, matchTypes };
+}
+
+/**
+ * Core discover logic, shared between standalone and post-checkin invocation.
+ */
+export async function discoverLogic(ctx, myTags) {
+  const spinner = villageSpinner('Searching for connections...').start();
+
+  try {
+    const creds = loadCredentials();
+
+    // 1. Get all the user's villages' communities (for cross-village search)
+    const villagesResult = await getVillagerVillages(ctx.villagerUuid);
+    const allVillages = villagesResult?.data || [];
+
+    const communityIds = [];
+    for (const village of allVillages) {
+      const commResult = await getVillageCommunities(village.id);
+      const comms = commResult?.data || [];
+      for (const c of comms) {
+        if (!communityIds.includes(c.id)) {
+          communityIds.push(c.id);
+        }
+      }
+    }
+
+    if (communityIds.length === 0) {
+      spinner.fail('No village communities found to search.');
+      return;
+    }
+
+    // 2. Fetch recent posts (last 14 days)
+    const since = new Date(Date.now() - 14 * 24 * 60 * 60 * 1000).toISOString();
+    const postsResult = await listPostsByFilters({
+      communityIds: communityIds.join(','),
+      tags: 'checkin,build-log,knowledge-contribution',
+      since,
+      pageSize: 50,
+      sort: 'new',
+    });
+
+    const posts = postsResult?.data || [];
+
+    // 3. Filter out current user's own posts
+    const otherPosts = posts.filter((p) => p.villagerId !== ctx.villagerUuid);
+
+    if (otherPosts.length === 0) {
+      spinner.info('No connections found right now \u2014 check back after more villages check in.');
+      return;
+    }
+
+    // 4. Score and rank matches
+    const scored = otherPosts.map((post) => {
+      const theirTags = parseTags(post.tags);
+      const { score, matchTypes } = scoreMatch(myTags, theirTags);
+      const villageName = post.community?.name || 'Unknown Village';
+      return { post, score, matchTypes, villageName, theirTags };
+    });
+
+    const topMatches = scored
+      .filter((m) => m.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 3);
+
+    spinner.stop();
+
+    if (topMatches.length === 0) {
+      console.log(chalk.dim('\n  No connections found right now \u2014 check back after more villages check in.\n'));
+      return;
+    }
+
+    console.log(brand.gold(`\n  Found ${topMatches.length} connection${topMatches.length > 1 ? 's' : ''}:\n`));
+
+    // 5. Display and optionally share each connection
+    for (const match of topMatches) {
+      formatConnection({
+        villageName: match.villageName,
+        topic: match.theirTags.themes[0] || match.theirTags.track || 'general',
+        matchType: match.matchTypes.join(', '),
+        score: match.score,
+      });
+
+      const { share } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'share',
+        message: 'Share this connection with the network?',
+        default: false,
+      }]);
+
+      if (share) {
+        const description = `Connection between ${ctx.village.name} and ${match.villageName}: ${match.matchTypes.join('; ')}`;
+        const connectionTags = ['connection'];
+        if (match.theirTags.track) connectionTags.push(`track:${match.theirTags.track}`);
+        for (const t of match.theirTags.themes) connectionTags.push(`theme:${t}`);
+
+        try {
+          await createPost({
+            communitySlug: ctx.community.slug,
+            postType: 'DISCUSSION',
+            title: `Connection: ${ctx.village.name} \u21C4 ${match.villageName}`,
+            body: description,
+            tags: connectionTags,
+          });
+          console.log(brand.green('  \u2713 Connection shared!\n'));
+        } catch (err) {
+          const msg = err.response?.data?.error || err.message;
+          console.log(chalk.red(`  \u2717 Failed to share connection: ${msg}\n`));
+        }
+      }
+    }
+  } catch (err) {
+    spinner.fail(`Discovery failed: ${err.message}`);
+  }
+}
+
+/**
+ * Standalone discover command — fetches user's most recent check-in,
+ * parses its tags, then runs discoverLogic.
+ */
+export async function discoverCommand(options) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red("  \u2717 Authentication required. Run 'myvillage login' first."));
+    return;
+  }
+
+  const ctx = await resolveVillageContext();
+  if (!ctx) return;
+
+  // Fetch user's most recent check-in
+  const spinner = villageSpinner('Loading your latest check-in...').start();
+
+  try {
+    const result = await listPosts({
+      communitySlug: ctx.community.slug,
+      authorId: ctx.villagerUuid,
+      pageSize: 1,
+      sort: 'new',
+    });
+
+    const posts = result?.data || [];
+    const checkin = posts.find((p) => p.tags?.includes('checkin'));
+
+    if (!checkin) {
+      spinner.info('No recent check-in found. Run `myvillage checkin` first to share what your village is working on.');
+      return;
+    }
+
+    spinner.succeed('Check-in loaded');
+    const myTags = parseTags(checkin.tags);
+    await discoverLogic(ctx, myTags);
+  } catch (err) {
+    spinner.fail(`Failed to load check-in: ${err.message}`);
+  }
+}

package/src/commands/log.js

@@ -0,0 +1,59 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { isAuthenticated } from '../utils/auth.js';
+import { brand } from '../utils/brand.js';
+import { createPost } from '../utils/api.js';
+import { resolveVillageContext } from '../utils/village-resolver.js';
+
+const TRACKS = ['game', 'portal', 'agent', 'data', 'robot', 'general'];
+
+export async function logCommand(text, options) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red("  \u2717 Authentication required. Run 'myvillage login' first."));
+    return;
+  }
+
+  const ctx = await resolveVillageContext();
+  if (!ctx) return;
+
+  // Get log text
+  let logText = text;
+  if (!logText) {
+    const { input } = await inquirer.prompt([{
+      type: 'input',
+      name: 'input',
+      message: 'What did you work on?',
+      validate: (v) => v.trim().length > 0 || 'Please enter something.',
+    }]);
+    logText = input.trim();
+  }
+
+  // Get track
+  let track = options.track;
+  if (!track) {
+    const { selected } = await inquirer.prompt([{
+      type: 'list',
+      name: 'selected',
+      message: 'Build track:',
+      choices: TRACKS,
+    }]);
+    track = selected;
+  }
+
+  // Build tags and post
+  const tags = ['build-log', `track:${track}`];
+
+  try {
+    await createPost({
+      communitySlug: ctx.community.slug,
+      postType: 'DISCUSSION',
+      body: logText,
+      tags,
+    });
+
+    console.log(brand.green(`  \u2713 Build log posted to ${ctx.village.name} [${track}]`));
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    console.log(chalk.red(`  \u2717 Failed to post build log: ${msg}`));
+  }
+}

package/src/commands/login.js

@@ -268,6 +268,7 @@ export async function loginCommand(options) {
       user_email: userInfo.email,
       user_name: userInfo.name,
       villager_id: userInfo.villager?.villagerId || null,
+      villager_uuid: userInfo.villager?.id || null,
     });
 
     spinner.succeed('Authentication complete!');

package/src/commands/story.js

@@ -0,0 +1,68 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { isAuthenticated } from '../utils/auth.js';
+import { brand } from '../utils/brand.js';
+import { createPost } from '../utils/api.js';
+import { resolveVillageContext } from '../utils/village-resolver.js';
+
+export async function storyCommand(options) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red("  \u2717 Authentication required. Run 'myvillage login' first."));
+    return;
+  }
+
+  const ctx = await resolveVillageContext();
+  if (!ctx) return;
+
+  // Guided prompts
+  const answers = await inquirer.prompt([
+    {
+      type: 'editor',
+      name: 'story',
+      message: 'What story, memory, or piece of wisdom would you like to share?',
+      validate: (v) => v.trim().length > 0 || 'Please share something.',
+    },
+    {
+      type: 'input',
+      name: 'source',
+      message: 'Who is this from? (you, a family elder, a community member)',
+      default: 'me',
+    },
+    {
+      type: 'input',
+      name: 'connection',
+      message: 'Is this connected to something the village is building? (optional)',
+    },
+  ]);
+
+  // Build tags
+  const tags = ['knowledge-contribution'];
+  const sourceName = answers.source.trim();
+  if (sourceName && sourceName.toLowerCase() !== 'me') {
+    tags.push(`source:${sourceName}`);
+  }
+  if (answers.connection?.trim()) {
+    tags.push(`theme:${answers.connection.trim()}`);
+  }
+
+  // Format body with attribution
+  let body = answers.story.trim();
+  if (sourceName && sourceName.toLowerCase() !== 'me') {
+    body = `"${body}"\n\n\u2014 ${sourceName}`;
+  }
+
+  try {
+    await createPost({
+      communitySlug: ctx.community.slug,
+      postType: 'DISCUSSION',
+      title: 'Knowledge Contribution',
+      body,
+      tags,
+    });
+
+    console.log(brand.green(`  \u2713 Story shared with ${ctx.village.name}`));
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    console.log(chalk.red(`  \u2717 Failed to share story: ${msg}`));
+  }
+}

package/src/index.js

@@ -53,6 +53,10 @@ import {
   bizreqsStatusCommand,
   bizreqsImportCommand,
 } from './commands/bizreqs.js';
+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 {
   soulprintInitCommand,
   soulprintIngestCommand,
@@ -321,6 +325,30 @@ export function run() {
     .description('Remove an MCP server tool from a local agent')
     .action(agentRemoveToolCommand);
 
+  // ── Village Content Pipeline ───────────────────────────
+
+  program
+    .command('checkin')
+    .description('Check in with your village and share updates')
+    .option('--skip-discover', 'Skip the auto-discover step')
+    .action(checkinCommand);
+
+  program
+    .command('discover')
+    .description('Find connections between villages')
+    .action(discoverCommand);
+
+  program
+    .command('log [text]')
+    .description('Quick build log entry')
+    .option('-t, --track <track>', 'Build track (game, portal, agent, data, robot, general)')
+    .action(logCommand);
+
+  program
+    .command('story')
+    .description('Share a story or wisdom with the network')
+    .action(storyCommand);
+
   // ── BizReqs: Business Requirements Pipeline ───────────
 
   const bizreqsCmd = program

package/src/utils/ai.js

@@ -0,0 +1,30 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { getConfig } from './config.js';
+import { brand } from './brand.js';
+
+export async function getAnthropicProvider() {
+  const { createAnthropic } = await import('@ai-sdk/anthropic');
+  const config = getConfig();
+  let apiKey = config.anthropicApiKey || process.env.ANTHROPIC_API_KEY;
+
+  if (!apiKey) {
+    console.log(chalk.yellow('\n  Anthropic API key required for AI features.'));
+    console.log(brand.teal('  Get yours at: https://console.anthropic.com\n'));
+
+    const { key } = await inquirer.prompt([{
+      type: 'password',
+      name: 'key',
+      message: 'Anthropic API key:',
+      mask: '*',
+      validate: (input) => input.trim().length > 0 || 'API key is required',
+    }]);
+
+    apiKey = key.trim();
+    const { setConfig } = await import('./config.js');
+    setConfig({ anthropicApiKey: apiKey });
+    console.log(brand.green('  \u2713 API key saved to ~/.myvillage/config.json\n'));
+  }
+
+  return createAnthropic({ apiKey });
+}

package/src/utils/api.js

@@ -379,6 +379,37 @@ export async function registerOAuthClient(name, appType, redirectUris) {
   return response.data;
 }
 
+// ── Platform API Client (/api) ──────────────────────────
+
+export function getPlatformClient() {
+  const config = getConfig();
+  return createClient(config.platformBaseUrl);
+}
+
+export async function getVillagerVillages(villagerUuid) {
+  const client = getPlatformClient();
+  const response = await client.get(`/villagers/${villagerUuid}/villages`);
+  return response.data;
+}
+
+export async function getVillagerByVillagerId(villagerId) {
+  const client = getPlatformClient();
+  const response = await client.get(`/villagers/by-villager-id/${villagerId}`);
+  return response.data;
+}
+
+export async function getVillageCommunities(villageUuid) {
+  const client = getNetworkClient();
+  const response = await client.get('/communities', { params: { villageId: villageUuid } });
+  return response.data;
+}
+
+export async function listPostsByFilters(params = {}) {
+  const client = getNetworkClient();
+  const response = await client.get('/posts', { params });
+  return response.data;
+}
+
 // ── BizReqs API Client (/api/bizreqs) ───────────────────
 
 export function getBizReqsClient() {

package/src/utils/config.js

@@ -11,6 +11,7 @@ const DEFAULT_CONFIG = {
   bizreqsBaseUrl: 'https://portal.myvillageproject.ai/api/bizreqs',
   oauthBaseUrl: 'https://portal.myvillageproject.ai/api/oauth',
   soulprintBaseUrl: 'https://soulprint-studio.myvillageproject.ai/api',
+  platformBaseUrl: 'https://portal.myvillageproject.ai/api',
   clientId: 'mvos_aG_c729fuQxvvqYHOnkgTQ',
   callbackPort: 3737,
   anthropicApiKey: null,

package/src/utils/formatters.js

@@ -743,3 +743,88 @@ export function formatPagination(meta) {
     console.log(chalk.dim(`  ── More results available. Run with --cursor=${meta.nextCursor} to see next page\n`));
   }
 }
+
+// ── MAN Content Pipeline ────────────────────────────────
+
+export function formatCheckinSummary(post, meta) {
+  const b = (s) => chalk.hex('#B07C00')(s);
+  const width = 56;
+  const bdr = '\u2500'.repeat(width);
+
+  const lines = [''];
+  lines.push(`  ${b('\u250C' + bdr + '\u2510')}`);
+  lines.push(`  ${b('\u2502')}  ${brand.gold('\u2743 Village Check-in')}${' '.repeat(width - 19)}${b('\u2502')}`);
+  lines.push(`  ${b('\u2502' + '\u2500'.repeat(width) + '\u2502')}`);
+
+  if (meta.villageName) {
+    const vl = `  Village:  ${meta.villageName}`;
+    lines.push(`  ${b('\u2502')}${brand.cream(vl).padEnd(width + 12)}${b('\u2502')}`);
+  }
+  if (meta.buildTrack) {
+    const tl = `  Track:    ${meta.buildTrack}`;
+    lines.push(`  ${b('\u2502')}${brand.teal(tl).padEnd(width + 12)}${b('\u2502')}`);
+  }
+  if (meta.themes?.length) {
+    const th = `  Themes:   ${meta.themes.join(', ')}`;
+    lines.push(`  ${b('\u2502')}${chalk.white(th).padEnd(width + 12)}${b('\u2502')}`);
+  }
+  if (meta.needs?.length) {
+    const nd = `  Needs:    ${meta.needs.join(', ')}`;
+    lines.push(`  ${b('\u2502')}${chalk.yellow(nd).padEnd(width + 12)}${b('\u2502')}`);
+  }
+  if (meta.offers?.length) {
+    const of_ = `  Offers:   ${meta.offers.join(', ')}`;
+    lines.push(`  ${b('\u2502')}${brand.green(of_).padEnd(width + 12)}${b('\u2502')}`);
+  }
+  if (post?.data?.id) {
+    const id = `  Post ID:  ${post.data.id.slice(0, 8)}...`;
+    lines.push(`  ${b('\u2502')}${chalk.dim(id).padEnd(width + 12)}${b('\u2502')}`);
+  }
+
+  lines.push(`  ${b('\u2514' + bdr + '\u2518')}`);
+  lines.push('');
+
+  console.log(lines.join('\n'));
+}
+
+export function formatConnection(connection) {
+  const b = (s) => chalk.hex('#B07C00')(s);
+  const width = 56;
+  const bdr = '\u2500'.repeat(width);
+
+  const lines = [''];
+  lines.push(`  ${b('\u250C' + bdr + '\u2510')}`);
+  lines.push(`  ${b('\u2502')}  ${brand.gold('\u21C4 Connection Found')}${' '.repeat(width - 20)}${b('\u2502')}`);
+  lines.push(`  ${b('\u2502' + '\u2500'.repeat(width) + '\u2502')}`);
+
+  if (connection.villageName) {
+    const vl = `  Village:    ${connection.villageName}`;
+    lines.push(`  ${b('\u2502')}${brand.cream(vl).padEnd(width + 12)}${b('\u2502')}`);
+  }
+  if (connection.topic) {
+    const tp = `  Topic:      ${connection.topic}`;
+    lines.push(`  ${b('\u2502')}${chalk.white(tp).padEnd(width + 12)}${b('\u2502')}`);
+  }
+  if (connection.matchType) {
+    const mt = `  Match:      ${connection.matchType}`;
+    lines.push(`  ${b('\u2502')}${brand.teal(mt).padEnd(width + 12)}${b('\u2502')}`);
+  }
+  if (connection.score !== undefined) {
+    const sc = `  Relevance:  ${'\u2605'.repeat(Math.min(connection.score, 5))}${'\u2606'.repeat(Math.max(0, 5 - connection.score))}`;
+    lines.push(`  ${b('\u2502')}${brand.gold(sc).padEnd(width + 12)}${b('\u2502')}`);
+  }
+
+  lines.push(`  ${b('\u2514' + bdr + '\u2518')}`);
+  lines.push('');
+
+  console.log(lines.join('\n'));
+}
+
+export function formatBuildLog(post) {
+  const tags = post.tags || [];
+  const track = tags.find((t) => t.startsWith('track:'))?.replace('track:', '') || 'general';
+  const body = post.body?.length > 60 ? post.body.slice(0, 57) + '...' : post.body || '';
+  const time = relativeTime(post.createdAt);
+
+  console.log(`  ${brand.teal(`[${track}]`)} ${chalk.white(body)}  ${chalk.dim(time)}`);
+}

package/src/utils/man-hooks.js

@@ -0,0 +1,16 @@
+import chalk from 'chalk';
+
+/**
+ * Trigger a MAN post from an automated event (deploy, publish, etc.).
+ * Stub implementation — future commands will call this to auto-generate MAN posts.
+ *
+ * @param {object} params
+ * @param {string} params.trigger - What triggered this (e.g., 'deploy', 'publish')
+ * @param {string} params.artifactId - ID of the artifact (game ID, model ID, etc.)
+ * @param {string} params.summary - Human-readable summary of what happened
+ * @param {string} params.villageId - Village UUID
+ * @param {string} params.communitySlug - Target community slug
+ */
+export async function triggerMANPost({ trigger, artifactId, summary, villageId, communitySlug }) {
+  console.log(chalk.dim(`  [MAN hook] ${trigger}: ${summary} (not yet wired — future feature)`));
+}

package/src/utils/village-resolver.js

@@ -0,0 +1,104 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { loadCredentials } from './auth.js';
+import { brand, villageSpinner } from './brand.js';
+import {
+  getVillagerVillages,
+  getVillagerByVillagerId,
+  getVillageCommunities,
+  joinCommunity,
+} from './api.js';
+
+/**
+ * Resolves a villager's village context: which village they're acting on behalf of
+ * and the corresponding MAN community.
+ *
+ * Returns { villagerUuid, village, community } or null if resolution fails.
+ */
+export async function resolveVillageContext() {
+  const creds = loadCredentials();
+  if (!creds) return null;
+
+  const spinner = villageSpinner('Resolving village context...').start();
+
+  try {
+    // 1. Get villager UUID
+    let villagerUuid = creds.villager_uuid;
+
+    if (!villagerUuid && creds.villager_id) {
+      const result = await getVillagerByVillagerId(creds.villager_id);
+      villagerUuid = result?.data?.id || result?.id;
+    }
+
+    if (!villagerUuid) {
+      spinner.fail('Could not resolve villager profile.');
+      console.log(chalk.dim('  Try logging out and back in: myvillage logout && myvillage login'));
+      return null;
+    }
+
+    // 2. Get associated villages
+    const villagesResult = await getVillagerVillages(villagerUuid);
+    const villages = villagesResult?.data || [];
+
+    if (villages.length === 0) {
+      spinner.fail('You are not associated with any villages.');
+      console.log(chalk.dim('  Join a village at portal.myvillageproject.ai to get started.'));
+      return null;
+    }
+
+    spinner.stop();
+
+    // 3. Select village
+    let village;
+    if (villages.length === 1) {
+      village = villages[0];
+      console.log(brand.teal(`  Village: ${village.name}`));
+    } else {
+      const { selected } = await inquirer.prompt([{
+        type: 'list',
+        name: 'selected',
+        message: 'Which village are you representing?',
+        choices: villages.map((v) => ({
+          name: `${v.name} (${v.city}, ${v.state})`,
+          value: v,
+        })),
+      }]);
+      village = selected;
+    }
+
+    // 4. Get village's dedicated community
+    const commSpinner = villageSpinner('Finding village community...').start();
+    const commResult = await getVillageCommunities(village.id);
+    const communities = commResult?.data || [];
+
+    // Find the community linked to this village
+    const community = communities.find((c) => c.villageId === village.id) || communities[0];
+
+    if (!community) {
+      commSpinner.fail('No MAN community found for this village.');
+      console.log(chalk.dim('  A community needs to be set up for your village first.'));
+      return null;
+    }
+
+    // 5. Auto-join community (ignore 409 = already member)
+    try {
+      await joinCommunity(community.slug);
+    } catch (err) {
+      if (err.response?.status !== 409 && err.response?.status !== 400) {
+        // Only throw if it's not "already a member"
+        const msg = err.response?.data?.error || '';
+        if (!msg.toLowerCase().includes('already')) {
+          throw err;
+        }
+      }
+    }
+
+    commSpinner.succeed(`Community: ${community.name}`);
+
+    return { villagerUuid, village, community };
+  } catch (err) {
+    spinner.stop();
+    console.log(chalk.red(`  \u2717 Failed to resolve village context: ${err.message}`));
+    return null;
+  }
+}