opencode-agora 0.2.2 → 0.4.0

package/dist/cli/app.js

@@ -1,24 +1,89 @@
 import { execSync } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import pkg from '../../package.json';
+import { spawn } from 'node:child_process';
 import { formatConfigJson } from '../config.js';
+import { formatNumber } from '../format.js';
+import { COMMANDS, renderManual } from './commands-meta.js';
+import { runInteractiveMenu } from './menu.js';
+import { runTui } from './tui.js';
 import { detectOpenCodeConfigPath, doctorOpenCodeConfig, loadOpenCodeConfig, writeOpenCodeConfig } from '../config-files.js';
-import { createInstallPlan, getInstallKind, getMarketplaceItems, getTrendingTags } from '../marketplace.js';
+import { createInstallPlan, getInstallKind, getMarketplaceItems, getTrendingTags, similarItems } from '../marketplace.js';
+import { communityBoardsSource, communityThreadsSource, communityThreadSource, createThreadSource, createReplySource, voteSource, flagSource } from '../community/client.js';
+import { normalizeNewsSource, DEFAULT_NEWS_CONFIG, hostFromUrl } from '../news/types.js';
+import { rankItems } from '../news/score.js';
+import { readCache, writeCache, isStale } from '../news/cache.js';
+import { hnSource } from '../news/sources/hn.js';
+import { redditSource } from '../news/sources/reddit.js';
+import { githubTrendingSource } from '../news/sources/github-trending.js';
+import { arxivSource } from '../news/sources/arxiv.js';
 import { scanProject, generateInitPlan, applyInitPlan, runCommands } from '../init.js';
+import { installAgoraCommand } from '../commands.js';
 import { sampleWorkflows, dataRefreshedAt } from '../data.js';
 import { createDiscussionSource, discussionsSource, findMarketplaceSource, createReviewSource, findTutorialSource, listReviewsSource, profileSource, publishPackageSource, publishWorkflowSource, searchMarketplaceSource, trendingMarketplaceSource, tutorialsSource } from '../live.js';
 import { clearAuthState, detectAgoraDataDir, getAuthState, getAgoraStatePath, loadAgoraState, removeItemFromState, resolveSavedItems, saveItemToState, setAuthState, writeAgoraState } from '../state.js';
-const VERSION = pkg.version;
-const booleanFlags = new Set(['api', 'help', 'json', 'live', 'offline', 'version', 'verbose', 'write']);
+import { createStyler, renderBanner, renderBox, renderMeander, shouldUseColor, supportsTrueColor } from '../ui.js';
+import { loadPreferences, writePreferences, prefsPath } from '../preferences.js';
+import { appendHistory, loadHistory, clearHistory } from '../history.js';
+const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+export const AGORA_VERSION = pkg.version;
+const VERSION = AGORA_VERSION;
+// Active terminal styler. Reassigned once per `runCli` invocation from the
+// caller's stream + env; defaults to plain so any direct formatter use is safe.
+let style = createStyler(false);
+const booleanFlags = new Set([
+    'api',
+    'continue',
+    'dryRun',
+    'help',
+    'json',
+    'live',
+    'mcp',
+    'offline',
+    'table',
+    'version',
+    'verbose',
+    'write'
+]);
+/**
+ * Returns true only when both stdout and stdin are real interactive TTYs AND the
+ * environment supports colour (i.e. not NO_COLOR or TERM=dumb). The gate keeps
+ * the interactive menu away from pipes, CI, and the test harness, all of which
+ * use non-TTY mock streams.
+ */
+function isInteractive(io, env) {
+    if (env.NO_COLOR != null)
+        return false;
+    if (env.TERM === 'dumb')
+        return false;
+    const stdoutTTY = Boolean(io.stdout.isTTY);
+    const stdinTTY = Boolean(process.stdin.isTTY);
+    return stdoutTTY && stdinTTY;
+}
 export async function runCli(argv, io) {
     const parsed = parseArgs(argv);
+    const env = io.env ?? {};
+    const useColor = shouldUseColor(io.stdout, env, Boolean(parsed.flags.json));
+    style = createStyler(useColor, supportsTrueColor(env));
     if (parsed.flags.version) {
         writeLine(io.stdout, VERSION);
         return 0;
     }
-    if (!parsed.command || parsed.flags.help) {
-        writeLine(io.stdout, usage());
+    if (parsed.flags.help) {
+        if (parsed.command && COMMANDS.some((c) => c.name === parsed.command)) {
+            writeLine(io.stdout, commandManual(parsed.command));
+        }
+        else {
+            writeLine(io.stdout, usage());
+        }
+        return 0;
+    }
+    if (!parsed.command) {
+        if (isInteractive(io, env)) {
+            const { runShell } = await import('./shell.js');
+            return runShell(io, style);
+        }
+        writeLine(io.stdout, welcome(useColor, supportsTrueColor(env)));
         return 0;
     }
     try {
@@ -56,16 +121,65 @@ export async function runCli(argv, io) {
             case 'profile':
                 return await commandProfile(parsed, io);
             case 'auth':
-                return commandAuth(parsed, io);
+                return await commandAuth(parsed, io);
+            case 'login':
+                return await commandAuth({ ...parsed, args: ['login', ...parsed.args], command: 'auth' }, io);
+            case 'logout':
+                return await commandAuth({ ...parsed, args: ['logout'], command: 'auth' }, io);
+            case 'whoami':
+                return await commandAuth({ ...parsed, args: ['status'], command: 'auth', flags: { ...parsed.flags, json: true } }, io);
             case 'config':
                 return await commandConfig(parsed, io);
+            case 'mcp':
+                return await commandMcp(parsed, io);
+            case 'chat':
+                return await commandChat(parsed, io);
             case 'init':
                 return await commandInit(parsed, io);
             case 'use':
                 return await commandUse(parsed, io);
-            case 'help':
-                writeLine(io.stdout, usage());
+            case 'similar':
+                return await commandSimilar(parsed, io);
+            case 'compare':
+                return await commandCompare(parsed, io);
+            case 'news':
+                return await commandNews(parsed, io);
+            case 'community':
+                return await commandCommunity(parsed, io);
+            case 'thread':
+                return await commandThread(parsed, io);
+            case 'post':
+                return await commandPost(parsed, io);
+            case 'reply':
+                return await commandReply(parsed, io);
+            case 'vote':
+                return await commandVote(parsed, io);
+            case 'flag':
+                return await commandFlag(parsed, io);
+            case 'preferences':
+                return await commandPreferences(parsed, io);
+            case 'history':
+                return await commandHistory(parsed, io);
+            case 'menu':
+                return await runInteractiveMenu(io, style);
+            case 'tui':
+                return await runTui(io, { initial: 'home' });
+            case 'help': {
+                const helpTarget = parsed.args[0];
+                if (helpTarget) {
+                    const meta = COMMANDS.find((c) => c.name === helpTarget);
+                    if (!meta) {
+                        writeLine(io.stderr, `Unknown command: ${helpTarget}`);
+                        writeLine(io.stderr, 'Run `agora help` for a list of commands.');
+                        return 1;
+                    }
+                    writeLine(io.stdout, commandManual(helpTarget));
+                }
+                else {
+                    writeLine(io.stdout, usage());
+                }
                 return 0;
+            }
             default:
                 writeLine(io.stderr, `Unknown command: ${parsed.command}`);
                 writeLine(io.stderr, 'Run agora help for usage.');
@@ -92,7 +206,9 @@ export function parseArgs(argv) {
             if (inlineValue !== undefined) {
                 flags[key] = inlineValue;
             }
-            else if (!booleanFlags.has(key) && argv[index + 1] && !argv[index + 1].startsWith('-')) {
+            else if (!booleanFlags.has(key) &&
+                argv[index + 1] &&
+                (!argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) {
                 flags[key] = argv[index + 1];
                 index += 1;
             }
@@ -103,7 +219,9 @@ export function parseArgs(argv) {
         }
         if (arg.startsWith('-') && arg.length > 1) {
             const key = shortFlag(arg);
-            if (!booleanFlags.has(key) && argv[index + 1] && !argv[index + 1].startsWith('-')) {
+            if (!booleanFlags.has(key) &&
+                argv[index + 1] &&
+                (!argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) {
                 flags[key] = argv[index + 1];
                 index += 1;
             }
@@ -123,30 +241,61 @@ export function parseArgs(argv) {
 async function commandSearch(parsed, io) {
     const query = parsed.args.join(' ');
     const category = stringFlag(parsed, 'category', 'c') || 'all';
-    const limit = numberFlag(parsed, 'limit', 'n') || 10;
-    const result = await searchMarketplaceSource({ ...sourceOptions(parsed, io), query, category, limit });
+    const sortBy = stringFlag(parsed, 'sort', 's') || 'relevance';
+    const sortOrder = (stringFlag(parsed, 'order', 'o') || 'desc');
+    const table = Boolean(parsed.flags.table);
+    const page = numberFlag(parsed, 'page', 'p') || 1;
+    const perPage = numberFlag(parsed, 'perPage', 'pp') || 0;
+    const limit = perPage > 0 ? perPage : (numberFlag(parsed, 'limit', 'n') || 10);
+    const result = await searchMarketplaceSource({
+        ...sourceOptions(parsed, io),
+        query,
+        category,
+        limit,
+        sortBy: sortBy,
+        sortOrder,
+        page,
+        perPage
+    });
     const results = result.data;
     warnFallback(result, io);
     if (parsed.flags.json) {
-        writeJson(io.stdout, sourcePayload(result, { query, category, count: results.length, items: results }));
+        writeJson(io.stdout, sourcePayload(result, { query, category, sortBy, sortOrder, page, count: results.length, items: results }));
         return 0;
     }
     if (results.length === 0) {
         writeLine(io.stdout, `No results found for "${query}".`);
         return 0;
     }
-    const sourceLabel = result.source === 'offline'
-        ? `source: offline, refreshed ${dataRefreshedAt}`
-        : `source: ${result.source}`;
-    writeLine(io.stdout, `Agora search: ${query || 'all'} (${results.length} shown, ${sourceLabel})`);
-    writeLine(io.stdout, formatItemList(results));
+    writeLine(io.stdout, header('agora search', [`"${query || 'all'}"`, `${results.length} results`, sourceLabel(result)]));
+    writeLine(io.stdout, '');
+    if (table) {
+        writeLine(io.stdout, formatItemTable(results));
+    }
+    else {
+        writeLine(io.stdout, formatItemList(results));
+    }
+    if (perPage > 0) {
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, style.dim(`Page ${page} · ${perPage} per page. Use --page N to navigate.`));
+    }
+    appendHistory(detectDataDir(parsed, io), {
+        type: 'search',
+        query,
+        timestamp: new Date().toISOString(),
+        results: results.length,
+    });
     return 0;
 }
 async function commandBrowse(parsed, io) {
     const id = parsed.args[0];
     if (!id)
         return usageError(io, 'browse requires an item id');
-    const result = await findMarketplaceSource({ ...sourceOptions(parsed, io), id, type: stringFlag(parsed, 'type', 't') });
+    const result = await findMarketplaceSource({
+        ...sourceOptions(parsed, io),
+        id,
+        type: stringFlag(parsed, 'type', 't')
+    });
     const item = result.data;
     warnFallback(result, io);
     if (!item)
@@ -156,11 +305,22 @@ async function commandBrowse(parsed, io) {
         return 0;
     }
     writeLine(io.stdout, formatItemDetail(item));
+    const related = similarItems(id, { limit: 3, type: item.kind === 'workflow' ? 'workflow' : undefined });
+    if (related.length > 0) {
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, style.dim('Related:'));
+        for (const rel of related) {
+            const tagOverlap = (item.tags ?? []).filter((t) => (rel.tags ?? []).includes(t));
+            const reason = tagOverlap.length > 0 ? ` (shares tags: ${tagOverlap.join(', ')})` : '';
+            writeLine(io.stdout, `  ${style.accent(rel.id.padEnd(28))} ${style.dim(formatNumber(rel.installs ?? 0) + ' installs')}${style.dim(reason)}`);
+        }
+    }
     return 0;
 }
 async function commandTrending(parsed, io) {
     const category = stringFlag(parsed, 'category', 'c') || parsed.args[0] || 'all';
     const limit = numberFlag(parsed, 'limit', 'n') || 5;
+    const table = Boolean(parsed.flags.table);
     const result = await trendingMarketplaceSource({ ...sourceOptions(parsed, io), category, limit });
     const items = result.data;
     warnFallback(result, io);
@@ -168,32 +328,373 @@ async function commandTrending(parsed, io) {
         writeJson(io.stdout, sourcePayload(result, { category, count: items.length, tags: getTrendingTags(), items }));
         return 0;
     }
-    writeLine(io.stdout, `Trending in Agora (${category}, source: ${result.source})`);
-    writeLine(io.stdout, formatItemList(items));
-    writeLine(io.stdout, `Tags: ${getTrendingTags().join(', ')}`);
+    writeLine(io.stdout, header('agora trending', [category, sourceLabel(result)]));
+    writeLine(io.stdout, '');
+    if (table) {
+        writeLine(io.stdout, formatItemTable(items));
+    }
+    else {
+        writeLine(io.stdout, formatItemList(items));
+    }
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, `${style.dim('tags')}  ${getTrendingTags().join(', ')}`);
     return 0;
 }
 async function commandWorkflows(parsed, io) {
     const query = parsed.args.join(' ');
     const limit = numberFlag(parsed, 'limit', 'n') || 10;
-    const result = await searchMarketplaceSource({ ...sourceOptions(parsed, io), query, category: 'workflow', limit });
-    const workflows = result.data.filter((item) => item.kind === 'workflow');
+    const result = await searchMarketplaceSource({
+        ...sourceOptions(parsed, io),
+        query,
+        category: 'workflow',
+        limit
+    });
+    const workflows = result.data;
     warnFallback(result, io);
     if (parsed.flags.json) {
         writeJson(io.stdout, sourcePayload(result, { query, count: workflows.length, workflows }));
         return 0;
     }
-    writeLine(io.stdout, `Agora workflows (${workflows.length} shown, source: ${result.source})`);
+    writeLine(io.stdout, header('agora workflows', [`${workflows.length} results`, sourceLabel(result)]));
+    writeLine(io.stdout, '');
     writeLine(io.stdout, formatItemList(workflows));
     return 0;
 }
+async function commandSimilar(parsed, io) {
+    const id = parsed.args[0];
+    if (!id)
+        return usageError(io, 'similar requires an item id');
+    const type = stringFlag(parsed, 'type', 't');
+    const limit = numberFlag(parsed, 'limit', 'n') || 5;
+    const results = similarItems(id, { limit, type });
+    if (parsed.flags.json) {
+        writeJson(io.stdout, { id, type: type || 'all', count: results.length, items: results });
+        return 0;
+    }
+    if (results.length === 0) {
+        writeLine(io.stdout, `No similar items found for "${id}".`);
+        return 0;
+    }
+    writeLine(io.stdout, header('agora similar', [`to ${id}`, `${results.length} results`]));
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, formatItemList(results));
+    return 0;
+}
+async function commandCompare(parsed, io) {
+    const ids = parsed.args;
+    if (ids.length < 2)
+        return usageError(io, 'compare requires at least two item ids');
+    const typeMap = (type) => type === 'package' || type === 'workflow' ? type : undefined;
+    const type = typeMap(stringFlag(parsed, 'type', 't'));
+    const items = [];
+    for (const id of ids) {
+        const item = await findMarketplaceSource({ ...sourceOptions(parsed, io), id, type });
+        if (!item.data) {
+            writeLine(io.stderr, `Item not found: ${id}`);
+            return 1;
+        }
+        items.push(item.data);
+    }
+    if (parsed.flags.json) {
+        writeJson(io.stdout, { ids, count: items.length, items });
+        return 0;
+    }
+    const sharedTags = items.length > 1
+        ? items.map((i) => new Set(i.tags ?? [])).reduce((a, b) => new Set([...a].filter((t) => b.has(t))))
+        : new Set();
+    const attrs = [
+        { label: 'name', get: (i) => i.name },
+        { label: 'author', get: (i) => i.author },
+        { label: 'installs', get: (i) => formatNumber(i.installs ?? 0) },
+        { label: 'stars', get: (i) => formatNumber(i.stars ?? 0) },
+        { label: 'category', get: (i) => i.category },
+        { label: 'tags', get: (i) => (i.tags ?? []).join(', ') },
+    ];
+    if (items.some((i) => i.kind === 'package' && i.npmPackage)) {
+        attrs.push({
+            label: 'npmPackage',
+            get: (i) => (i.kind === 'package' && i.npmPackage) || '-',
+        });
+    }
+    if (items.some((i) => i.createdAt)) {
+        attrs.push({
+            label: 'created',
+            get: (i) => (i.createdAt || '').slice(0, 10),
+        });
+    }
+    const colW = Math.max(12, ...items.map((i) => Math.max(i.id.length, i.name.length, 10)));
+    const labelW = Math.max(...attrs.map((a) => a.label.length));
+    const totalW = labelW + 3 + items.length * (colW + 3) + 1;
+    const top = style.accent('┌') + '─'.repeat(labelW + 2) + style.accent('┬') + '─'.repeat(totalW - labelW - 6) + style.accent('┐');
+    const bot = style.accent('└') + '─'.repeat(labelW + 2) + style.accent('┴') + '─'.repeat(totalW - labelW - 6) + style.accent('┘');
+    const hdrCells = items.map((i, idx) => {
+        const name = idx === 0 ? style.bold(style.accent(i.id)) : style.accent(i.id);
+        return name.padEnd(colW);
+    });
+    const hdr = style.accent('│') + ' '.repeat(labelW + 2) + style.accent('│') + ' ' + hdrCells.join(style.accent(' │ ') + ' ') + style.accent(' │');
+    const rows = attrs.map((attr) => {
+        const cells = items.map((item) => {
+            const val = attr.get(item);
+            if (attr.label === 'tags') {
+                return val.split(', ').map((t) => sharedTags.has(t) ? style.accent(t) : style.dim(t)).join(', ').padEnd(colW);
+            }
+            return (attr.label === 'name' || attr.label === 'npmPackage' ? val : style.dim(val)).padEnd(colW);
+        });
+        return style.accent('│') + ' ' + style.dim(attr.label.padEnd(labelW)) + ' ' + style.accent('│') + ' ' + cells.join(style.accent(' │ ') + ' ') + style.accent(' │');
+    });
+    const sepLine = style.accent('├') + '─'.repeat(labelW + 2) + style.accent('┼') + '─'.repeat(totalW - labelW - 6) + style.accent('┤');
+    writeLine(io.stdout, header('agora compare', items.map((i) => i.id)));
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, [top, hdr, sepLine, ...rows, bot].join('\n'));
+    if (sharedTags.size > 0) {
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, style.dim('Shared tags highlighted in accent.'));
+    }
+    return 0;
+}
+async function commandNews(parsed, io) {
+    const query = parsed.args.join(' ');
+    const sourceOpt = stringFlag(parsed, 'source', 's');
+    const source = sourceOpt ? normalizeNewsSource(sourceOpt) : undefined;
+    const limit = numberFlag(parsed, 'limit', 'n') || 20;
+    const refresh = Boolean(parsed.flags.refresh);
+    const dataDir = detectDataDir(parsed, io);
+    let cached = readCache(dataDir);
+    const now = new Date();
+    const config = DEFAULT_NEWS_CONFIG;
+    const adapters = [
+        ['hn', hnSource],
+        ['reddit', redditSource],
+        ['github-trending', githubTrendingSource],
+        ['arxiv', arxivSource],
+    ];
+    const fetchWithTimeout = (fn, ms = 10000) => Promise.race([fn(), new Promise((_, r) => setTimeout(() => r(new Error('timeout')), ms))]);
+    const refreshSource = async (src, adapter) => {
+        try {
+            const fresh = await fetchWithTimeout(() => adapter.fetch({}));
+            cached = cached.filter((i) => i.source !== src);
+            cached.push(...fresh);
+        }
+        catch {
+            // keep stale
+        }
+    };
+    if (refresh) {
+        for (const [src, adapter] of adapters) {
+            await refreshSource(src, adapter);
+        }
+    }
+    else {
+        for (const [src, adapter] of adapters) {
+            const cfg = config.sources[src];
+            if (cfg?.enabled && isStale(cached, src, cfg.ttlMinutes, now)) {
+                await refreshSource(src, adapter);
+            }
+        }
+    }
+    const ranked = rankItems(cached, config, now);
+    writeCache(dataDir, cached);
+    let items = ranked;
+    if (query) {
+        const q = query.toLowerCase();
+        items = items.filter((i) => i.title.toLowerCase().includes(q) || i.tags.some((t) => t.includes(q)));
+    }
+    if (source) {
+        items = items.filter((i) => i.source === source);
+    }
+    items = items.slice(0, limit);
+    if (parsed.flags.json) {
+        writeJson(io.stdout, { count: items.length, items, source: source || 'all' });
+        return 0;
+    }
+    if (items.length === 0) {
+        writeLine(io.stdout, 'No news items found.');
+        return 0;
+    }
+    writeLine(io.stdout, header('agora news', [`${items.length} stories`, source ? `source: ${source}` : 'all sources']));
+    writeLine(io.stdout, '');
+    for (const item of items) {
+        const ageH = Math.round((now.getTime() - new Date(item.publishedAt).getTime()) / 3600000);
+        const age = ageH < 1 ? '<1h' : ageH < 24 ? `${ageH}h` : `${Math.round(ageH / 24)}d`;
+        const host = hostFromUrl(item.url);
+        writeLine(io.stdout, `${style.accent(item.source.padEnd(6))} ${style.dim(age.padEnd(4))} ${style.accent(formatNumber(item.engagement).padStart(7))}  ${style.dim('s' + item.score.toFixed(2))}   ${item.title}`);
+        if (host)
+            writeLine(io.stdout, `       ${style.dim(host)}`);
+        if (query)
+            writeLine(io.stdout, '');
+    }
+    return 0;
+}
+async function commandCommunity(parsed, io) {
+    const board = parsed.args[0];
+    const sort = (stringFlag(parsed, 'sort') || 'active');
+    const opts = sourceOptions(parsed, io);
+    if (board) {
+        const result = await communityThreadsSource(opts, board, sort);
+        const threads = result.data.threads;
+        if (parsed.flags.json) {
+            writeJson(io.stdout, { board, sort, count: threads.length, threads });
+            return 0;
+        }
+        if (threads.length === 0) {
+            writeLine(io.stdout, `No threads in /${board}.`);
+            return 0;
+        }
+        writeLine(io.stdout, header(`agora community /${board}`, [`${threads.length} threads`, `sort: ${sort}`]));
+        writeLine(io.stdout, '');
+        for (const t of threads) {
+            const ageH = Math.round((Date.now() - new Date(t.createdAt).getTime()) / 3600000);
+            writeLine(io.stdout, `  ${style.accent(t.title)}`);
+            writeLine(io.stdout, `     ${style.dim(t.author + ' \u00b7 ' + ageH + 'h \u00b7 ' + t.score + '\u2191 \u00b7 ' + t.replyCount + ' replies')}`);
+        }
+        return 0;
+    }
+    const boardsResult = await communityBoardsSource(opts);
+    const boards = boardsResult.data.boards;
+    if (parsed.flags.json) {
+        writeJson(io.stdout, { boards });
+        return 0;
+    }
+    writeLine(io.stdout, header('agora community', [`${boards.length} boards`]));
+    writeLine(io.stdout, '');
+    for (const b of boards) {
+        writeLine(io.stdout, `  ${style.accent('/' + b.id.padEnd(12))} ${style.dim(b.threadCount + ' threads, ' + b.newToday + ' new today')}`);
+    }
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, style.dim('Run `agora community <board>` to see threads.'));
+    return 0;
+}
+async function commandThread(parsed, io) {
+    const id = parsed.args[0];
+    if (!id)
+        return usageError(io, 'thread requires a thread id');
+    const opts = sourceOptions(parsed, io);
+    const result = await communityThreadSource(opts, id);
+    const { thread, replies } = result.data;
+    if (!thread)
+        return usageError(io, `Thread not found: ${id}`);
+    if (parsed.flags.json) {
+        writeJson(io.stdout, { thread, replies });
+        return 0;
+    }
+    const ageH = Math.round((Date.now() - new Date(thread.createdAt).getTime()) / 3600000);
+    writeLine(io.stdout, style.bold(thread.title));
+    writeLine(io.stdout, `${style.dim(thread.author + ' \u00b7 ' + ageH + 'h \u00b7 ' + thread.score + '\u2191 \u00b7 ' + thread.replyCount + ' replies')}`);
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, thread.content);
+    if (replies.length > 0) {
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, style.dim('--- replies ---'));
+        for (const r of replies) {
+            const rAgeH = Math.round((Date.now() - new Date(r.createdAt).getTime()) / 3600000);
+            writeLine(io.stdout, `  ${style.dim(r.author + ' \u00b7 ' + rAgeH + 'h')} ${style.accent(r.score + '\u2191')}`);
+            writeLine(io.stdout, `  ${r.content}`);
+        }
+    }
+    return 0;
+}
+async function commandPost(parsed, io) {
+    const source = writeSourceOptions(parsed, io);
+    if (!source.ok)
+        return usageError(io, source.error);
+    const board = (stringFlag(parsed, 'board') || stringFlag(parsed, 'b'));
+    const title = requiredStringFlag(parsed, 'title');
+    const content = contentInput(parsed, io);
+    if (!board || !title || !content) {
+        return usageError(io, 'post requires --board, --title and --content or --content-file');
+    }
+    const result = await createThreadSource(source.options, { board, title, content });
+    if (parsed.flags.json) {
+        writeJson(io.stdout, sourcePayload(result, { thread: result.data.thread }));
+        return 0;
+    }
+    writeLine(io.stdout, `Posted to /${board}: ${style.accent(result.data.thread?.title || title)}`);
+    writeLine(io.stdout, `${sourceLabel(result)}`);
+    return 0;
+}
+async function commandReply(parsed, io) {
+    const parentId = parsed.args[0];
+    if (!parentId)
+        return usageError(io, 'reply requires a thread or reply id');
+    const source = writeSourceOptions(parsed, io);
+    if (!source.ok)
+        return usageError(io, source.error);
+    const content = contentInput(parsed, io);
+    if (!content)
+        return usageError(io, 'reply requires --content or --content-file');
+    const result = await createReplySource(source.options, parentId, {
+        content,
+        parentId: stringFlag(parsed, 'parentId'),
+    });
+    if (parsed.flags.json) {
+        writeJson(io.stdout, sourcePayload(result, { reply: result.data.reply }));
+        return 0;
+    }
+    writeLine(io.stdout, `Replied to ${style.accent(parentId)}`);
+    writeLine(io.stdout, `${sourceLabel(result)}`);
+    return 0;
+}
+async function commandVote(parsed, io) {
+    const id = parsed.args[0];
+    if (!id)
+        return usageError(io, 'vote requires a thread or reply id');
+    const source = writeSourceOptions(parsed, io);
+    if (!source.ok)
+        return usageError(io, source.error);
+    const up = parsed.flags.up === true;
+    const down = parsed.flags.down === true;
+    if (!up && !down)
+        return usageError(io, 'vote requires --up or --down');
+    const value = up ? 1 : -1;
+    const targetType = (stringFlag(parsed, 'type') || 'discussion');
+    await voteSource(source.options, id, { value, targetType });
+    if (parsed.flags.json) {
+        writeJson(io.stdout, { id, value, targetType, success: true });
+        return 0;
+    }
+    writeLine(io.stdout, up ? `Upvoted ${style.accent(id)}` : `Downvoted ${style.accent(id)}`);
+    return 0;
+}
+async function commandFlag(parsed, io) {
+    const id = parsed.args[0];
+    if (!id)
+        return usageError(io, 'flag requires an item id');
+    const flagMarketplace = (kind) => !kind || kind === 'package' || kind === 'workflow';
+    const reasonOpt = stringFlag(parsed, 'reason');
+    const validReasons = ['spam', 'harassment', 'undisclosed-llm', 'malicious', 'other'];
+    const reason = (reasonOpt && validReasons.includes(reasonOpt) ? reasonOpt : 'other');
+    const type = stringFlag(parsed, 'type') || 'discussion';
+    if (flagMarketplace(type)) {
+        writeLine(io.stdout, `Flagged ${style.accent(id)} for ${reason} (${type})`);
+        if (parsed.flags.json) {
+            writeJson(io.stdout, { id, reason, type, success: true });
+        }
+        return 0;
+    }
+    const source = writeSourceOptions(parsed, io);
+    if (!source.ok)
+        return usageError(io, source.error);
+    const targetType = (type === 'discussion' || type === 'reply' ? type : 'discussion');
+    await flagSource(source.options, id, { reason, targetType, notes: stringFlag(parsed, 'notes') });
+    if (parsed.flags.json) {
+        writeJson(io.stdout, { id, reason, targetType, success: true });
+        return 0;
+    }
+    writeLine(io.stdout, `Flagged ${style.accent(id)} for ${reason}`);
+    return 0;
+}
 async function commandTutorials(parsed, io) {
     const query = parsed.args.join(' ');
     const level = tutorialLevelFlag(parsed);
     if (!level.ok)
         return usageError(io, level.error);
     const limit = numberFlag(parsed, 'limit', 'n') || 20;
-    const result = await tutorialsSource({ ...sourceOptions(parsed, io), query, level: level.value, limit });
+    const result = await tutorialsSource({
+        ...sourceOptions(parsed, io),
+        query,
+        level: level.value,
+        limit
+    });
     const tutorials = result.data;
     warnFallback(result, io);
     if (parsed.flags.json) {
@@ -204,14 +705,22 @@ async function commandTutorials(parsed, io) {
         writeLine(io.stdout, query ? `No tutorials match "${query}".` : 'No tutorials found.');
         return 0;
     }
-    writeLine(io.stdout, `Agora tutorials (${tutorials.length} shown, source: ${result.source})`);
+    writeLine(io.stdout, header('agora tutorials', [`${tutorials.length} results`, sourceLabel(result)]));
+    writeLine(io.stdout, '');
     writeLine(io.stdout, formatTutorialList(tutorials));
     return 0;
 }
 async function commandTutorial(parsed, io) {
     const id = parsed.args[0];
-    if (!id)
-        return usageError(io, 'tutorial requires a tutorial id');
+    if (!id) {
+        const { sampleTutorials } = await import('../data.js');
+        writeLine(io.stdout, header('agora tutorial', [`${sampleTutorials.length} available tutorials`]));
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, sampleTutorials.map((t) => `  ${style.accent(t.id.padEnd(22))} ${style.dim(t.title)} ${style.dim('[' + t.level + ']')}`).join('\n'));
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, style.dim('Run `agora tutorial <id>` to start a tutorial.'));
+        return 0;
+    }
     const step = tutorialStepNumber(parsed);
     if (!step.ok)
         return usageError(io, step.error);
@@ -244,14 +753,17 @@ async function commandDiscussions(parsed, io) {
         writeLine(io.stdout, 'No discussions found.');
         return 0;
     }
-    writeLine(io.stdout, `Agora discussions (${discussions.length}, source: ${result.source})`);
-    writeLine(io.stdout, discussions.map((discussion, index) => {
+    writeLine(io.stdout, header('agora discussions', [`${discussions.length} results`, sourceLabel(result)]));
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, discussions
+        .map((discussion, index) => {
         return [
-            `${index + 1}. ${discussion.title} [${discussion.category}]`,
+            `${index + 1}. ${style.accent(discussion.title)} ${style.dim('[' + discussion.category + ']')}`,
             `   ${truncate(discussion.content, 88)}`,
-            `   replies ${discussion.replies} | stars ${discussion.stars} | by ${discussion.author}`
+            `   ${style.dim('replies ' + discussion.replies + ' · stars ' + discussion.stars + ' · by ' + discussion.author)}`
         ].join('\n');
-    }).join('\n\n'));
+    })
+        .join('\n\n'));
     return 0;
 }
 async function commandDiscuss(parsed, io) {
@@ -259,7 +771,7 @@ async function commandDiscuss(parsed, io) {
     if (!source.ok)
         return usageError(io, source.error);
     const title = requiredStringFlag(parsed, 'title');
-    const content = contentInput(parsed);
+    const content = contentInput(parsed, io);
     if (!title || !content) {
         return usageError(io, 'discuss requires --title and --content or --content-file');
     }
@@ -275,15 +787,19 @@ async function commandDiscuss(parsed, io) {
         writeJson(io.stdout, sourcePayload(result, { discussion: result.data }));
         return 0;
     }
-    writeLine(io.stdout, `Created discussion ${result.data.id}`);
-    writeLine(io.stdout, `${result.data.title} (${result.source})`);
+    writeLine(io.stdout, `Created discussion ${style.accent(result.data.id)}`);
+    writeLine(io.stdout, `${result.data.title} (${sourceLabel(result)})`);
     return 0;
 }
 async function commandInstall(parsed, io) {
     const id = parsed.args[0];
     if (!id)
         return usageError(io, 'install requires an item id');
-    const source = await findMarketplaceSource({ ...sourceOptions(parsed, io), id, type: stringFlag(parsed, 'type', 't') });
+    const source = await findMarketplaceSource({
+        ...sourceOptions(parsed, io),
+        id,
+        type: stringFlag(parsed, 'type', 't')
+    });
     const item = source.data;
     warnFallback(source, io);
     if (!item)
@@ -315,8 +831,8 @@ async function commandInstall(parsed, io) {
     }
     if (parsed.flags.write) {
         writeOpenCodeConfig(configPath, plan.config);
-        writeLine(io.stdout, `Installed ${item.name}`);
-        writeLine(io.stdout, `Updated ${configPath}`);
+        writeLine(io.stdout, `Installed ${style.accent(item.name)}`);
+        writeLine(io.stdout, `${style.dim('Config')} ${configPath}`);
         if (plan.commands.length) {
             writeLine(io.stdout, 'Installing packages...');
             for (const cmd of plan.commands) {
@@ -333,6 +849,16 @@ async function commandInstall(parsed, io) {
     }
     writeLine(io.stdout, `Install preview: ${item.name}`);
     writeLine(io.stdout, `Target config: ${configPath}`);
+    const perms = item.permissions;
+    if (perms) {
+        writeLine(io.stdout, '\nDeclared permissions:');
+        if (perms.fs?.length)
+            writeLine(io.stdout, `  ${style.dim('filesystem')} ${perms.fs.join(', ')}`);
+        if (perms.net?.length)
+            writeLine(io.stdout, `  ${style.dim('network')}   ${perms.net.join(', ')}`);
+        if (perms.exec?.length)
+            writeLine(io.stdout, `  ${style.dim('exec')}     ${perms.exec.join(', ')}`);
+    }
     if (plan.commands.length) {
         writeLine(io.stdout, '\nCommands:');
         writeLine(io.stdout, plan.commands.join('\n'));
@@ -342,36 +868,271 @@ async function commandInstall(parsed, io) {
     writeLine(io.stdout, '\nRun with --write to update the config file and install packages.');
     return 0;
 }
+async function commandMcp(_parsed, io) {
+    const { runMcpServer } = await import('./mcp-server.js');
+    try {
+        await runMcpServer();
+    }
+    catch (error) {
+        writeLine(io.stderr, error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    return 0;
+}
+export const FREE_MODELS = ['deepseek-v4-flash-free', 'minimax-m2.5-free', 'nemotron-3-super-free'];
+/** Regexp to extract session ID from a JSON opencode event line. */
+function extractSessionId(line) {
+    try {
+        const ev = JSON.parse(line);
+        if (ev.sessionID && typeof ev.sessionID === 'string')
+            return ev.sessionID;
+    }
+    catch {
+        /* not JSON, skip */
+    }
+    return null;
+}
+/**
+ * Persist the most recent chat session ID to the Agora state file so
+ * `--continue` can pick it up.
+ */
+function persistChatSession(dataDir, sessionId) {
+    try {
+        const state = loadAgoraState(dataDir);
+        const updated = {
+            ...state,
+            _meta: { ...(state._meta || {}), lastChatSession: sessionId }
+        };
+        writeAgoraState(dataDir, updated);
+    }
+    catch {
+        // best-effort
+    }
+}
+function loadLastChatSession(dataDir) {
+    try {
+        const state = loadAgoraState(dataDir);
+        return state._meta?.lastChatSession;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function commandChat(parsed, io) {
+    const message = parsed.args.join(' ');
+    const model = stringFlag(parsed, 'model', 'm') || FREE_MODELS[0];
+    const continueMode = parsed.flags.continue === true;
+    const explicitSession = stringFlag(parsed, 'session', 's');
+    const rawJson = parsed.flags.json === true;
+    const modelArg = model.includes('/') ? model : `opencode/${model}`;
+    if (!message) {
+        // TUI mode — hand off to opencode with inherit stdio
+        process.stderr.write(`Agora Chat (${model}) — press Ctrl+C to exit.\n`);
+        const child = spawn('opencode', ['--model', modelArg], {
+            env: io.env,
+            stdio: 'inherit',
+            shell: false
+        });
+        return new Promise((resolve) => {
+            child.on('close', (code) => resolve(code ?? 0));
+            child.on('error', (err) => {
+                writeLine(io.stderr, `Failed to run opencode: ${err.message}`);
+                resolve(1);
+            });
+        });
+    }
+    // One-shot mode — single message via opencode run
+    return new Promise((resolve) => {
+        const args = ['run', '--format', 'json'];
+        args.push('--model', modelArg);
+        if (explicitSession) {
+            args.push('--session', explicitSession);
+        }
+        else if (continueMode) {
+            const dataDir = detectDataDir(parsed, io);
+            const lastSession = loadLastChatSession(dataDir);
+            if (lastSession) {
+                args.push('--session', lastSession);
+            }
+            else {
+                args.push('--continue');
+            }
+        }
+        args.push(message);
+        const stderrChunks = [];
+        let sessionId = null;
+        let wroteNewline = false;
+        const child = spawn('opencode', args, {
+            env: io.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false
+        });
+        child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split('\n').filter(Boolean)) {
+                if (!sessionId)
+                    sessionId = extractSessionId(line);
+                if (rawJson) {
+                    process.stdout.write(line + '\n');
+                    continue;
+                }
+                try {
+                    const ev = JSON.parse(line);
+                    if (ev.type === 'text' && ev.part?.text) {
+                        process.stdout.write(ev.part.text);
+                        wroteNewline = false;
+                    }
+                    if (ev.type === 'step_finish') {
+                        const tokens = ev.part?.tokens;
+                        if (tokens && !rawJson) {
+                            const cost = typeof tokens.cost === 'number' ? ` · $${tokens.cost.toFixed(6)}` : '';
+                            process.stdout.write(`\n\x1b[2m[${tokens.output} tokens${cost}]\x1b[0m\n`);
+                            wroteNewline = true;
+                        }
+                    }
+                }
+                catch {
+                    /* skip malformed lines */
+                }
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderrChunks.push(chunk.toString());
+        });
+        child.on('close', (code) => {
+            if (!wroteNewline)
+                process.stdout.write('\n');
+            const dataDir = detectDataDir(parsed, io);
+            appendHistory(dataDir, {
+                type: 'chat',
+                query: message,
+                timestamp: new Date().toISOString(),
+                model,
+            });
+            if (sessionId) {
+                persistChatSession(dataDir, sessionId);
+                if (!rawJson) {
+                    process.stdout.write(`\x1b[2mSession: ${sessionId.slice(0, 24)}…  `);
+                    process.stdout.write(`Continue: agora chat --session ${sessionId} "..."\x1b[0m\n`);
+                }
+            }
+            if (code !== 0) {
+                const errText = stderrChunks.join('');
+                const modelError = errText.match(/Model not found:.*?Did you mean:\s*(.+?)\?/);
+                if (modelError) {
+                    const suggestions = modelError[1];
+                    writeLine(io.stderr, `\nModel not available. Try: ${suggestions}`);
+                    writeLine(io.stderr, `Example: agora chat -m deepseek-v4-flash-free "your question"`);
+                }
+                else if (errText.includes('not found')) {
+                    writeLine(io.stderr, '\n' + errText.replace(/^.*?ERROR\s+/gm, '').trim());
+                }
+            }
+            resolve(code ?? 0);
+        });
+        child.on('error', (err) => {
+            writeLine(io.stderr, `Failed to run opencode: ${err.message}`);
+            writeLine(io.stderr, 'Is opencode installed and in your PATH?');
+            resolve(1);
+        });
+    });
+}
 async function commandInit(parsed, io) {
     const cwd = io.cwd || process.cwd();
     const scan = scanProject(cwd);
+    const plan = generateInitPlan(scan);
+    const configPath = detectOpenCodeConfigPath({ cwd, env: io.env });
+    const withMcp = parsed.flags.mcp === true;
+    if (withMcp) {
+        plan.config.mcp = plan.config.mcp || {};
+        plan.config.mcp.agora = {
+            type: 'local',
+            command: ['agora', 'mcp'],
+            enabled: true
+        };
+        plan.servers.push('agora');
+        plan.notes.push('Agora MCP server registered — OpenCode can discover marketplace tools.');
+    }
     if (parsed.flags.json) {
-        writeJson(io.stdout, { projectType: scan.type, frameworks: scan.frameworks });
+        if (parsed.flags.dryRun) {
+            writeJson(io.stdout, {
+                projectType: scan.type,
+                frameworks: scan.frameworks,
+                config: plan.config,
+                servers: plan.servers,
+                commands: plan.commands,
+                slashCommand: join(cwd, '.opencode', 'command', 'agora.md'),
+                dryRun: true
+            });
+            return 0;
+        }
+        applyInitPlan(plan, configPath);
+        const commandPath = installAgoraCommand(cwd);
+        const installResults = plan.commands.length ? runCommands(plan.commands) : [];
+        const installed = installResults.filter((r) => r.ok).length;
+        const failed = installResults.filter((r) => !r.ok).length;
+        writeJson(io.stdout, {
+            projectType: scan.type,
+            frameworks: scan.frameworks,
+            config: plan.config,
+            servers: plan.servers,
+            commands: plan.commands,
+            slashCommand: commandPath,
+            installResults,
+            installed,
+            failed
+        });
         return 0;
     }
     writeLine(io.stdout, `Scanning ${cwd}...`);
-    writeLine(io.stdout, `  Project type: ${scan.type}`);
+    writeLine(io.stdout, `  ${style.dim('Project type')} ${scan.type}`);
     if (scan.frameworks.length)
-        writeLine(io.stdout, `  Frameworks: ${scan.frameworks.join(', ')}`);
+        writeLine(io.stdout, `  ${style.dim('Frameworks')} ${scan.frameworks.join(', ')}`);
     if (scan.hasDocker)
-        writeLine(io.stdout, '  Docker: detected');
+        writeLine(io.stdout, `  ${style.dim('Docker')} detected`);
     if (scan.hasTests)
-        writeLine(io.stdout, '  Tests: detected');
+        writeLine(io.stdout, `  ${style.dim('Tests')} detected`);
     if (scan.hasDatabase)
-        writeLine(io.stdout, '  Database: detected');
-    const plan = generateInitPlan(scan);
-    const configPath = detectOpenCodeConfigPath({ cwd, env: io.env });
+        writeLine(io.stdout, `  ${style.dim('Database')} detected`);
     if (!parsed.flags.dryRun) {
         applyInitPlan(plan, configPath);
         writeLine(io.stdout, `\nWrote config to ${configPath}`);
+        const commandPath = installAgoraCommand(cwd);
+        writeLine(io.stdout, `Installed /agora slash command at ${commandPath}`);
         if (plan.commands.length) {
             writeLine(io.stdout, '\nInstalling MCP server packages...');
-            runCommands(plan.commands);
-            writeLine(io.stdout, `  Done (${plan.commands.length} packages)`);
+            const isTTY = Boolean(io.stdout.isTTY);
+            const n = plan.commands.length;
+            const installResults = [];
+            for (let i = 0; i < n; i++) {
+                const [result] = runCommands([plan.commands[i]]);
+                installResults.push(result);
+                if (isTTY && n > 1) {
+                    const pct = ((i + 1) / n) * 100;
+                    const bar = renderMeander({
+                        trueColor: supportsTrueColor(io.env ?? {}),
+                        mode: 'progress',
+                        pct
+                    });
+                    const line = `  ${bar}`;
+                    if (i < n - 1) {
+                        process.stdout.write(`\r\x1b[K${line}`);
+                    }
+                    else {
+                        process.stdout.write(`\r\x1b[K${line}\n`);
+                    }
+                }
+            }
+            const installed = installResults.filter((r) => r.ok).length;
+            const failed = installResults.filter((r) => !r.ok).length;
+            writeLine(io.stdout, `  Installed ${installed} of ${plan.commands.length} packages${failed ? ` (${failed} failed)` : ''}`);
         }
         writeLine(io.stdout, '\n✓ Agora initialized! Restart OpenCode to pick up the changes.');
         writeLine(io.stdout, '  Plugin "opencode-agora" is now registered in your config.');
+        writeLine(io.stdout, '  Type `/agora` in OpenCode to use the marketplace.');
         writeLine(io.stdout, `  ${plan.servers.length} MCP servers configured.`);
+        if (withMcp)
+            writeLine(io.stdout, '  Agora MCP server registered — `agora mcp` is available as an MCP tool.');
         if (plan.workflows.length)
             writeLine(io.stdout, `  ${plan.workflows.length} workflows available via \`agora use\`.`);
         for (const note of plan.notes)
@@ -381,6 +1142,7 @@ async function commandInit(parsed, io) {
         writeLine(io.stdout, '\n--- Dry run ---');
         writeLine(io.stdout, `Target config: ${configPath}`);
         writeLine(io.stdout, formatConfigJson(plan.config));
+        writeLine(io.stdout, `\nSlash command: ${join(cwd, '.opencode', 'command', 'agora.md')}`);
         writeLine(io.stdout, '\nPackages to install:');
         for (const cmd of plan.commands)
             writeLine(io.stdout, `  ${cmd}`);
@@ -390,8 +1152,14 @@ async function commandInit(parsed, io) {
 }
 async function commandUse(parsed, io) {
     const id = parsed.args[0];
-    if (!id)
-        return usageError(io, 'use requires a workflow id');
+    if (!id) {
+        writeLine(io.stdout, header('agora use', [`${sampleWorkflows.length} available workflows`]));
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, sampleWorkflows.map((wf) => `  ${style.accent(wf.id.padEnd(22))} ${style.dim(wf.name)}`).join('\n'));
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, style.dim('Run `agora use <id>` to apply a workflow as a skill.'));
+        return 0;
+    }
     const workflow = sampleWorkflows.find((w) => w.id === id || w.name.toLowerCase() === id.toLowerCase());
     if (!workflow)
         return usageError(io, `Workflow not found: ${id}. Run \`agora workflows\` to see available workflows.`);
@@ -412,11 +1180,13 @@ ${workflow.prompt}
     writeFileSync(skillPath, skillContent, 'utf8');
     const configPath = detectOpenCodeConfigPath({ cwd, env: io.env });
     const loaded = loadOpenCodeConfig(configPath);
-    const plugins = new Set(loaded.config.plugins || []);
+    if (loaded.error)
+        return usageError(io, `${loaded.path}: ${loaded.error}`);
+    const plugins = new Set(loaded.config.plugin || []);
     plugins.add(skillId);
     const updatedConfig = {
         ...loaded.config,
-        plugins: Array.from(plugins),
+        plugin: Array.from(plugins)
     };
     writeOpenCodeConfig(configPath, updatedConfig);
     if (parsed.flags.json) {
@@ -444,51 +1214,133 @@ function commandConfig(parsed, io) {
         writeJson(io.stdout, report);
         return report.valid ? 0 : 1;
     }
-    writeLine(io.stdout, `Config path: ${report.path}`);
-    writeLine(io.stdout, `Exists: ${report.exists ? 'yes' : 'no'}`);
-    writeLine(io.stdout, `Valid: ${report.valid ? 'yes' : 'no'}`);
+    writeLine(io.stdout, `${style.dim('Config path')} ${report.path}`);
+    writeLine(io.stdout, `${style.dim('Exists')} ${report.exists ? 'yes' : 'no'}`);
+    writeLine(io.stdout, `${style.dim('Valid')} ${report.valid ? 'yes' : 'no'}`);
     if (report.error)
-        writeLine(io.stdout, `Error: ${report.error}`);
-    writeLine(io.stdout, `MCP servers: ${report.mcpServers}`);
-    writeLine(io.stdout, `Plugins: ${report.plugins}`);
-    writeLine(io.stdout, `Packages: ${report.packages.length ? report.packages.join(', ') : 'none'}`);
+        writeLine(io.stdout, `${style.dim('Error')} ${report.error}`);
+    writeLine(io.stdout, `${style.dim('MCP servers')} ${report.mcpServers}`);
+    writeLine(io.stdout, `${style.dim('Plugins')} ${report.plugins}`);
+    writeLine(io.stdout, `${style.dim('Packages')} ${report.packages.length ? report.packages.join(', ') : 'none'}`);
     return report.valid ? 0 : 1;
 }
-function commandAuth(parsed, io) {
+async function commandAuth(parsed, io) {
     const subcommand = parsed.args[0] || 'status';
     const dataDir = detectDataDir(parsed, io);
     const state = loadAgoraState(dataDir);
     const existingAuth = getAuthState(state);
     if (subcommand === 'login') {
-        const token = authTokenInput(parsed, io);
-        if (!token) {
-            return usageError(io, 'auth login requires --token, AGORA_TOKEN, or AGORA_API_TOKEN');
+        const explicitToken = authTokenInput(parsed, io);
+        if (explicitToken) {
+            // Token-paste flow (existing behaviour, for CI/automation)
+            const apiUrl = stringFlag(parsed, 'apiUrl') || envString(io, 'AGORA_API_URL') || existingAuth?.apiUrl;
+            const nextState = setAuthState(state, { token: explicitToken, apiUrl });
+            const auth = getAuthState(nextState);
+            writeAgoraState(dataDir, nextState);
+            if (parsed.flags.json) {
+                writeJson(io.stdout, authStatusPayload(dataDir, auth));
+                return 0;
+            }
+            writeLine(io.stdout, 'Stored Agora API token');
+            writeLine(io.stdout, `${style.dim('API URL')} ${auth?.apiUrl || 'not stored'}`);
+            writeLine(io.stdout, `${style.dim('State')} ${getAgoraStatePath(dataDir)}`);
+            return 0;
         }
+        // ── Device-code flow ─────────────────────────────────────────────────
         const apiUrl = stringFlag(parsed, 'apiUrl') || envString(io, 'AGORA_API_URL') || existingAuth?.apiUrl;
-        const nextState = setAuthState(state, { token, apiUrl });
-        const auth = getAuthState(nextState);
-        writeAgoraState(dataDir, nextState);
-        if (parsed.flags.json) {
-            writeJson(io.stdout, authStatusPayload(dataDir, auth));
-            return 0;
+        if (!apiUrl) {
+            return usageError(io, 'auth login requires --api-url, AGORA_API_URL, or stored apiUrl');
+        }
+        const baseUrl = apiUrl.replace(/\/+$/, '');
+        process.stdout.write(`\n${style.accent('Agora Login')}\n`);
+        process.stdout.write(`${style.dim('Connecting to')} ${baseUrl}...\n`);
+        try {
+            const codeRes = await fetch(`${baseUrl}/auth/device/code`, { method: 'POST' });
+            if (!codeRes.ok) {
+                const err = await codeRes.json().catch(() => ({ error: 'request failed' }));
+                return usageError(io, `Device code request failed: ${err.error || codeRes.status}`);
+            }
+            const codeData = (await codeRes.json());
+            const verificationUri = codeData.verification_uri;
+            const userCode = codeData.user_code;
+            const deviceCode = codeData.device_code;
+            const interval = (codeData.interval || 5) * 1000;
+            process.stdout.write(`\n${style.accent(userCode.slice(0, 4) + ' ' + userCode.slice(4))}\n\n`);
+            process.stdout.write(`  ${style.dim('Open in your browser:')} ${verificationUri}\n`);
+            process.stdout.write(`  ${style.dim('Enter code:')}         ${userCode}\n\n`);
+            // Try to open browser automatically
+            try {
+                const url = `${verificationUri}`;
+                if (process.platform === 'darwin') {
+                    execSync(`open '${url}'`, { timeout: 3000 });
+                }
+                else if (process.platform === 'linux') {
+                    execSync(`xdg-open '${url}'`, { timeout: 3000 });
+                }
+                process.stdout.write(`  ${style.dim('Browser opened.')}\n\n`);
+            }
+            catch {
+                process.stdout.write(`  ${style.dim('Open the URL manually.')}\n\n`);
+            }
+            // Poll for token
+            const pollStart = Date.now();
+            const pollTimeout = 15 * 60 * 1000; // 15 minutes
+            for (;;) {
+                await new Promise((r) => setTimeout(r, interval));
+                if (Date.now() - pollStart > pollTimeout) {
+                    return usageError(io, 'Login timed out. Run `agora auth login` to try again.');
+                }
+                process.stdout.write(`\r\x1b[K${style.dim('Waiting for browser authorization...')}`);
+                try {
+                    const tokenRes = await fetch(`${baseUrl}/auth/device/token`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ device_code: deviceCode })
+                    });
+                    if (tokenRes.ok) {
+                        const tokenData = (await tokenRes.json());
+                        const jwt = tokenData.access_token;
+                        process.stdout.write(`\r\x1b[K${style.dim('Authorization received.')}\n`);
+                        const nextState = setAuthState(state, { token: jwt, apiUrl });
+                        writeAgoraState(dataDir, nextState);
+                        if (parsed.flags.json) {
+                            writeJson(io.stdout, authStatusPayload(dataDir, getAuthState(nextState)));
+                            return 0;
+                        }
+                        process.stdout.write(`\n${style.accent('✓ Authenticated')}\n`);
+                        process.stdout.write(`${style.dim('API URL')} ${baseUrl}\n`);
+                        process.stdout.write(`${style.dim('Token expires')} in 1 hour\n`);
+                        process.stdout.write(`${style.dim('State')} ${getAgoraStatePath(dataDir)}\n`);
+                        return 0;
+                    }
+                    const errData = await tokenRes.json().catch(() => ({ error: 'unknown' }));
+                    if (errData.error === 'expired') {
+                        process.stdout.write(`\r\x1b[K`);
+                        return usageError(io, 'Code expired. Run `agora auth login` again.');
+                    }
+                    // "authorization_pending" is expected — keep polling
+                }
+                catch {
+                    // Network error, retry
+                }
+            }
+        }
+        catch (e) {
+            return usageError(io, `Login failed: ${e.message || 'connection error'}`);
         }
-        writeLine(io.stdout, 'Stored Agora API token');
-        writeLine(io.stdout, `API URL: ${auth?.apiUrl || 'not stored'}`);
-        writeLine(io.stdout, `State: ${getAgoraStatePath(dataDir)}`);
-        return 0;
     }
     if (subcommand === 'status') {
         if (parsed.flags.json) {
             writeJson(io.stdout, authStatusPayload(dataDir, existingAuth));
             return 0;
         }
-        writeLine(io.stdout, `Authenticated: ${existingAuth ? 'yes' : 'no'}`);
+        writeLine(io.stdout, `${style.dim('Authenticated')} ${existingAuth ? 'yes' : 'no'}`);
         if (existingAuth) {
-            writeLine(io.stdout, `Token: ${maskToken(existingAuth.token)}`);
-            writeLine(io.stdout, `API URL: ${existingAuth.apiUrl || 'not stored'}`);
-            writeLine(io.stdout, `Saved: ${formatDate(existingAuth.savedAt)}`);
+            writeLine(io.stdout, `${style.dim('Token')} ${maskToken(existingAuth.token)}`);
+            writeLine(io.stdout, `${style.dim('API URL')} ${existingAuth.apiUrl || 'not stored'}`);
+            writeLine(io.stdout, `${style.dim('Saved')} ${formatDate(existingAuth.savedAt)}`);
         }
-        writeLine(io.stdout, `State: ${getAgoraStatePath(dataDir)}`);
+        writeLine(io.stdout, `${style.dim('State')} ${getAgoraStatePath(dataDir)}`);
         return 0;
     }
     if (subcommand === 'logout') {
@@ -514,7 +1366,11 @@ async function commandSave(parsed, io) {
     const id = parsed.args[0];
     if (!id)
         return usageError(io, 'save requires an item id');
-    const source = await findMarketplaceSource({ ...sourceOptions(parsed, io), id, type: stringFlag(parsed, 'type', 't') });
+    const source = await findMarketplaceSource({
+        ...sourceOptions(parsed, io),
+        id,
+        type: stringFlag(parsed, 'type', 't')
+    });
     const item = source.data;
     warnFallback(source, io);
     if (!item)
@@ -535,8 +1391,8 @@ async function commandSave(parsed, io) {
         });
         return 0;
     }
-    writeLine(io.stdout, result.added ? `Saved ${item.id}` : `${item.id} is already saved`);
-    writeLine(io.stdout, `State: ${getAgoraStatePath(dataDir)}`);
+    writeLine(io.stdout, result.added ? `Saved ${style.accent(item.id)}` : `${style.accent(item.id)} is already saved`);
+    writeLine(io.stdout, `${style.dim('State')} ${getAgoraStatePath(dataDir)}`);
     return 0;
 }
 function commandSaved(parsed, io) {
@@ -558,7 +1414,7 @@ function commandSaved(parsed, io) {
         writeLine(io.stdout, 'Run agora save <id> to save a package or workflow.');
         return 0;
     }
-    writeLine(io.stdout, `Saved Agora items (${saved.length})`);
+    writeLine(io.stdout, header('agora saved', [`${saved.length} items`]));
     writeLine(io.stdout, formatSavedList(saved));
     return 0;
 }
@@ -585,7 +1441,7 @@ function commandRemove(parsed, io) {
     if (!result.removed) {
         return usageError(io, `Saved item not found: ${id}`);
     }
-    writeLine(io.stdout, `Removed ${targetId}`);
+    writeLine(io.stdout, `Removed ${style.accent(targetId)}`);
     return 0;
 }
 async function commandPublish(parsed, io) {
@@ -621,12 +1477,12 @@ async function commandPublish(parsed, io) {
             writeJson(io.stdout, sourcePayload(result, { item: result.data }));
             return 0;
         }
-        writeLine(io.stdout, `Published package ${result.data.id}`);
-        writeLine(io.stdout, `${result.data.name} (${result.source})`);
+        writeLine(io.stdout, `Published package ${style.accent(result.data.id)}`);
+        writeLine(io.stdout, `${result.data.name} (${sourceLabel(result)})`);
         return 0;
     }
-    const prompt = promptInput(parsed);
-    if (!prompt) {
+    const prompt = promptInput(parsed, io);
+    if (prompt === undefined) {
         return usageError(io, 'publish workflow requires --prompt or --prompt-file');
     }
     const result = await publishWorkflowSource(source.options, {
@@ -641,8 +1497,8 @@ async function commandPublish(parsed, io) {
         writeJson(io.stdout, sourcePayload(result, { item: result.data }));
         return 0;
     }
-    writeLine(io.stdout, `Published workflow ${result.data.id}`);
-    writeLine(io.stdout, `${result.data.name} (${result.source})`);
+    writeLine(io.stdout, `Published workflow ${style.accent(result.data.id)}`);
+    writeLine(io.stdout, `${result.data.name} (${sourceLabel(result)})`);
     return 0;
 }
 async function commandReview(parsed, io) {
@@ -667,8 +1523,8 @@ async function commandReview(parsed, io) {
         writeJson(io.stdout, sourcePayload(result, { review: result.data }));
         return 0;
     }
-    writeLine(io.stdout, `Reviewed ${result.data.itemId}`);
-    writeLine(io.stdout, `${result.data.rating}/5 by ${result.data.author}`);
+    writeLine(io.stdout, `Reviewed ${style.accent(result.data.itemId)}`);
+    writeLine(io.stdout, `${style.dim(result.data.rating + '/5 by ' + result.data.author)}`);
     return 0;
 }
 async function commandReviews(parsed, io) {
@@ -685,7 +1541,8 @@ async function commandReviews(parsed, io) {
         writeLine(io.stdout, itemId ? `No reviews found for ${itemId}.` : 'No reviews found.');
         return 0;
     }
-    writeLine(io.stdout, `Agora reviews (${result.data.length}, source: ${result.source})`);
+    writeLine(io.stdout, header('agora reviews', [`${result.data.length} results`, sourceLabel(result)]));
+    writeLine(io.stdout, '');
     writeLine(io.stdout, formatReviewList(result.data));
     return 0;
 }
@@ -706,177 +1563,268 @@ async function commandProfile(parsed, io) {
     writeLine(io.stdout, formatProfileDetail(result.data));
     return 0;
 }
+async function commandPreferences(parsed, io) {
+    const dataDir = detectDataDir(parsed, io);
+    const prefs = loadPreferences(dataDir);
+    const sub = parsed.args[0];
+    if (!sub) {
+        if (parsed.flags.json) {
+            writeJson(io.stdout, prefs);
+            return 0;
+        }
+        writeLine(io.stdout, `Preferences (${prefsPath(dataDir)})`);
+        writeLine(io.stdout, `  theme:      ${prefs.theme}`);
+        writeLine(io.stdout, `  verbosity:  ${prefs.verbosity}`);
+        writeLine(io.stdout, `  username:   ${prefs.username || '(not set)'}`);
+        writeLine(io.stdout, `  email:      ${prefs.email || '(not set)'}`);
+        writeLine(io.stdout, `  bio:        ${prefs.bio ? prefs.bio.slice(0, 60) + (prefs.bio.length > 60 ? '...' : '') : '(not set)'}`);
+        writeLine(io.stdout, '');
+        writeLine(io.stdout, '  Set values:  agora preferences <key> <value>');
+        writeLine(io.stdout, '  Keys:        theme, verbosity, username, email, bio');
+        return 0;
+    }
+    const key = sub;
+    const val = parsed.args.slice(1).join(' ');
+    if (!val || !(key in prefs)) {
+        return usageError(io, `Usage: agora preferences <key> <value>\nValid keys: theme, verbosity, username, email, bio`);
+    }
+    if (key === 'theme' && !['dark', 'light', 'auto'].includes(val)) {
+        return usageError(io, 'theme must be: dark, light, or auto');
+    }
+    if (key === 'verbosity' && !['verbose', 'medium', 'quiet'].includes(val)) {
+        return usageError(io, 'verbosity must be: verbose, medium, or quiet');
+    }
+    prefs[key] = val;
+    writePreferences(dataDir, prefs);
+    writeLine(io.stdout, `\u2713 ${key} set to "${val}"`);
+    return 0;
+}
+async function commandHistory(parsed, io) {
+    const dataDir = detectDataDir(parsed, io);
+    const limit = numberFlag(parsed, 'limit', 'n') || 50;
+    if (parsed.flags.clear) {
+        clearHistory(dataDir);
+        writeLine(io.stdout, '\u2713 History cleared');
+        return 0;
+    }
+    const entries = loadHistory(dataDir, limit);
+    if (parsed.flags.json) {
+        writeJson(io.stdout, entries);
+        return 0;
+    }
+    if (entries.length === 0) {
+        writeLine(io.stdout, 'No history yet.');
+        writeLine(io.stdout, 'Searches and chat messages are recorded automatically.');
+        return 0;
+    }
+    writeLine(io.stdout, `Recent history (${entries.length}):`);
+    for (const entry of entries) {
+        const icon = entry.type === 'search' ? '\uD83D\uDD0D' : '\uD83D\uDCAC';
+        const date = new Date(entry.timestamp).toLocaleString();
+        const query = entry.query.length > 60 ? entry.query.slice(0, 60) + '...' : entry.query;
+        writeLine(io.stdout, `  ${icon} ${style.dim(date)}  ${query}`);
+    }
+    writeLine(io.stdout, '');
+    writeLine(io.stdout, style.dim('Use --clear to clear history, --json for JSON output.'));
+    return 0;
+}
 function formatItemList(items) {
-    return items.map((item, index) => {
-        const installs = item.kind === 'package' ? ` | installs ${formatCount(item.installs)}` : '';
+    const idWidth = Math.max(...items.map((item) => item.id.length));
+    return items
+        .map((item) => {
+        const metrics = item.kind === 'package'
+            ? `${formatNumber(item.installs)} installs · ${formatNumber(item.stars)} ★`
+            : `${formatNumber(item.stars)} ★`;
         return [
-            `${index + 1}. ${item.id} [${item.category}]`,
-            `   ${item.name}`,
-            `   ${truncate(item.description, 88)}`,
-            `   stars ${formatCount(item.stars)}${installs} | by ${item.author}`
+            `${style.accent(item.id.padEnd(idWidth))}  ${style.dim(metrics)}`,
+            style.dim(item.name),
+            truncate(item.description, 88),
+            style.dim(`${item.category} · by ${item.author}`)
         ].join('\n');
-    }).join('\n\n');
+    })
+        .join('\n\n');
+}
+function formatItemTable(items) {
+    const idW = Math.max(4, ...items.map((i) => i.id.length));
+    const nameW = Math.max(4, ...items.map((i) => i.name.length));
+    const starW = 6;
+    const installW = 9;
+    const totalW = idW + 3 + nameW + 3 + starW + 3 + installW + 4;
+    const top = '┌' + '─'.repeat(totalW - 2) + '┐';
+    const bot = '└' + '─'.repeat(totalW - 2) + '┘';
+    const sep = '│';
+    const hdr = sep + ' ' + 'id'.padEnd(idW) + ' │ ' + 'name'.padEnd(nameW) + ' │ ' + 'stars'.padStart(starW) + ' │ ' + 'installs'.padStart(installW) + ' │';
+    const rows = items.map((item) => sep + ' ' + style.accent(item.id.padEnd(idW)) + ' │ ' + style.dim(item.name.padEnd(nameW)) + ' │ ' + style.dim(formatNumber(item.stars).padStart(starW)) + ' │ ' + style.dim(formatNumber(item.installs).padStart(installW)) + ' │');
+    return [top, hdr, ...rows, bot].join('\n');
 }
 function formatItemDetail(item) {
     const lines = [
-        `${item.name}`,
-        `id: ${item.id}`,
-        `type: ${item.kind}`,
-        `category: ${item.category}`,
-        `author: ${item.author}`,
-        `stars: ${formatCount(item.stars)}`,
-        `install: ${getInstallKind(item)}`,
+        style.bold(item.name),
+        `${style.dim('id')}        ${style.accent(item.id)}`,
+        `${style.dim('type')}      ${item.kind}`,
+        `${style.dim('category')}  ${item.category}`,
+        `${style.dim('author')}    ${item.author}`,
+        `${style.dim('stars')}     ${formatNumber(item.stars)}`,
+        `${style.dim('install')}   ${getInstallKind(item)}`,
         '',
         item.description,
         '',
-        `tags: ${item.tags.join(', ')}`
+        `${style.dim('tags')}      ${item.tags.join(', ')}`
     ];
     if (item.kind === 'package') {
-        lines.splice(5, 0, `version: ${item.version}`);
-        lines.push(`installs: ${formatCount(item.installs)}`);
+        lines.splice(5, 0, `${style.dim('version')}   ${item.version}`);
+        lines.push(`${style.dim('installs')}  ${formatNumber(item.installs)}`);
         if (item.repository)
-            lines.push(`repository: ${item.repository}`);
+            lines.push(`${style.dim('repo')}      ${item.repository}`);
         if (item.npmPackage)
-            lines.push(`npm: ${item.npmPackage}`);
+            lines.push(`${style.dim('npm')}       ${item.npmPackage}`);
     }
     if (item.kind === 'workflow') {
-        lines.push(`forks: ${item.forks}`);
+        lines.push(`${style.dim('forks')}     ${item.forks}`);
         if (item.model)
-            lines.push(`model: ${item.model}`);
-        lines.push('', 'prompt:', item.prompt);
+            lines.push(`${style.dim('model')}     ${item.model}`);
+        lines.push('', style.dim('prompt'), item.prompt);
     }
     return lines.join('\n');
 }
 function formatSavedList(items) {
-    return items.map((entry, index) => {
+    return items
+        .map((entry, index) => {
         if (!entry.item) {
             return [
-                `${index + 1}. ${entry.saved.id} [missing]`,
-                `   saved ${formatDate(entry.saved.savedAt)}`
+                `${index + 1}. ${style.accent(entry.saved.id)} ${style.dim('[missing]')}`,
+                `   ${style.dim('saved ' + formatDate(entry.saved.savedAt))}`
             ].join('\n');
         }
         return [
-            `${index + 1}. ${entry.item.id} [${entry.item.category}]`,
-            `   ${entry.item.name}`,
+            `${index + 1}. ${style.accent(entry.item.id)} ${style.dim('[' + entry.item.category + ']')}`,
+            `   ${style.dim(entry.item.name)}`,
             `   ${truncate(entry.item.description, 88)}`,
-            `   saved ${formatDate(entry.saved.savedAt)}`
+            `   ${style.dim('saved ' + formatDate(entry.saved.savedAt))}`
         ].join('\n');
-    }).join('\n\n');
+    })
+        .join('\n\n');
 }
 function formatReviewList(reviews) {
-    return reviews.map((review, index) => {
+    return reviews
+        .map((review, index) => {
         return [
-            `${index + 1}. ${review.itemId} [${review.itemType}]`,
-            `   rating ${review.rating}/5 by ${review.author}`,
+            `${index + 1}. ${style.accent(review.itemId)} ${style.dim('[' + review.itemType + ']')}`,
+            `   ${style.dim('rating ' + review.rating + '/5 by ' + review.author)}`,
             `   ${truncate(review.content, 88)}`
         ].join('\n');
-    }).join('\n\n');
+    })
+        .join('\n\n');
 }
 function formatProfileDetail(profile) {
     const lines = [
-        profile.displayName,
-        `username: ${profile.username}`,
-        `packages: ${formatCount(profile.packages)}`,
-        `workflows: ${formatCount(profile.workflows)}`,
-        `discussions: ${formatCount(profile.discussions)}`
+        style.bold(profile.displayName),
+        `${style.dim('username')} ${style.accent(profile.username)}`,
+        `${style.dim('packages')} ${formatNumber(profile.packages)}`,
+        `${style.dim('workflows')} ${formatNumber(profile.workflows)}`,
+        `${style.dim('discussions')} ${formatNumber(profile.discussions)}`
     ];
     if (profile.bio)
-        lines.splice(2, 0, `bio: ${profile.bio}`);
+        lines.splice(2, 0, `${style.dim('bio')} ${profile.bio}`);
     if (profile.avatarUrl)
-        lines.push(`avatar: ${profile.avatarUrl}`);
+        lines.push(`${style.dim('avatar')} ${profile.avatarUrl}`);
     if (profile.joinedAt)
-        lines.push(`joined: ${formatDate(profile.joinedAt)}`);
+        lines.push(`${style.dim('joined')} ${formatDate(profile.joinedAt)}`);
     return lines.join('\n');
 }
 function formatTutorialList(tutorials) {
-    return tutorials.map((tutorial, index) => {
+    return tutorials
+        .map((tutorial, index) => {
         return [
-            `${index + 1}. ${tutorial.id} [${tutorial.level}]`,
-            `   ${tutorial.title}`,
+            `${index + 1}. ${style.accent(tutorial.id)} ${style.dim('[' + tutorial.level + ']')}`,
+            `   ${style.dim(tutorial.title)}`,
             `   ${truncate(tutorial.description, 88)}`,
-            `   ${tutorial.duration} | ${tutorial.steps.length} steps`
+            `   ${style.dim(tutorial.duration + ' | ' + tutorial.steps.length + ' steps')}`
         ].join('\n');
-    }).join('\n\n');
+    })
+        .join('\n\n');
 }
 function formatTutorialStep(tutorial, stepNumber) {
     const payload = tutorialStepPayload(tutorial, stepNumber);
     if (payload.completed) {
         return [
-            `${tutorial.title}`,
-            `Completed ${tutorial.steps.length}/${tutorial.steps.length} steps.`,
+            style.bold(tutorial.title),
+            style.dim(`Completed ${tutorial.steps.length}/${tutorial.steps.length} steps.`),
             'Run agora tutorials for more tutorials.'
         ].join('\n');
     }
     const lines = [
-        `${tutorial.title}`,
-        `id: ${tutorial.id}`,
-        `level: ${tutorial.level}`,
-        `duration: ${tutorial.duration}`,
-        `step: ${payload.stepNumber}/${tutorial.steps.length}`,
+        style.bold(tutorial.title),
+        `${style.dim('id')} ${style.accent(tutorial.id)}`,
+        `${style.dim('level')} ${tutorial.level}`,
+        `${style.dim('duration')} ${tutorial.duration}`,
+        `${style.dim('step')} ${payload.stepNumber}/${tutorial.steps.length}`,
         '',
         payload.title || '',
         payload.content || ''
     ];
     if (payload.code) {
-        lines.push('', 'code:', payload.code);
+        lines.push('', style.dim('code:'), payload.code);
     }
     return lines.join('\n');
 }
-function usage() {
-    return [
-        'Agora CLI',
-        '',
-        'Usage:',
-        '  agora init [--dry-run] [--json]',
-        '  agora use <workflow-id> [--json]',
-        '  agora search <query> [--category mcp|prompt|workflow|skill] [--limit 10] [--json]',
-        '  agora browse <id> [--type package|workflow] [--json]',
-        '  agora trending [all|packages|workflows] [--limit 5] [--json]',
-        '  agora workflows [query] [--limit 10] [--json]',
-        '  agora tutorials [query] [--level beginner|intermediate|advanced] [--limit 20] [--json]',
-        '  agora tutorial <id> [step] [--json]',
-        '  agora discussions [query] [--category question|idea|showcase|discussion] [--json]',
-        '  agora discuss --title <title> (--content <text>|--content-file path) [--category question|idea|showcase|discussion]',
-        '  agora install <id> [--write] [--config path] [--json]',
-        '  agora save <id> [--data-dir path] [--json]',
-        '  agora saved [query] [--data-dir path] [--json]',
-        '  agora remove <id> [--data-dir path] [--json]',
-        '  agora auth login --token <token> [--api-url url] [--data-dir path]',
-        '  agora auth status [--data-dir path] [--json]',
-        '  agora auth logout [--data-dir path]',
-        '  agora publish package --name <name> --description <text> --npm <package> [--token token]',
-        '  agora publish workflow --name <name> --description <text> --prompt-file <path> [--token token]',
-        '  agora review <id> --rating 5 --content <text> [--token token]',
-        '  agora reviews [id] [--type package|workflow]',
-        '  agora profile <username> [--json]',
-        '  agora config doctor [--config path] [--json]',
-        '',
-        'Data source:',
-        '  --api                 Use the live Agora API',
-        '  --api-url <url>       Override AGORA_API_URL',
-        '  --api-timeout <ms>    API timeout before offline fallback',
-        '  --token <token>       API auth token, defaults to env vars or agora auth login',
-        '  --offline             Force local bundled marketplace data',
-        '',
-        'Examples:',
-        '  agora init',
-        '  agora init --dry-run',
-        '  agora use wf-tdd-cycle',
-        '  agora search filesystem',
-        '  agora search filesystem --api',
-        '  agora browse mcp-github',
-        '  agora tutorials mcp',
-        '  agora tutorial tut-mcp-basics 2',
-        '  agora install mcp-github',
-        '  agora install mcp-github --write',
-        '  agora save wf-security-audit',
-        '  agora saved',
-        '  agora auth login --token $AGORA_TOKEN --api-url https://agora.example.com',
-        '  agora discuss --title "MCP question" --content "How are you composing servers?" --category question',
-        '  agora profile alice',
-        '  agora publish package --name @you/server --description "MCP server" --npm @you/server',
-        '  agora review mcp-github --rating 5 --content "Works well"'
+function welcome(color, trueColor) {
+    if (!color) {
+        return [
+            '',
+            `agora · Developers' CLI marketplace and community hub · v${VERSION}`,
+            '',
+            '  Search    agora search <query>',
+            '  Browse    agora trending · agora browse <id>',
+            '  Learn     agora tutorials · agora tutorial <id>',
+            '  Install   agora install <id> [--write]',
+            '  Setup     agora init [--mcp] · agora use <workflow>',
+            '  Auth      agora login [--api-url <url>]',
+            ''
+        ].join('\n');
+    }
+    const banner = renderBanner({ color, trueColor });
+    const box = renderBox('Welcome to Agora', [
+        "Developers' CLI marketplace and community hub - type a command, bash or chat:",
+        `v${VERSION} · run \`agora help\` to get started`
+    ], { color, trueColor });
+    const hint = [
+        `${style.dim('Search')}    agora search <query>`,
+        `${style.dim('Browse')}    agora trending · agora browse <id>`,
+        `${style.dim('Learn')}     agora tutorials · agora tutorial <id>`,
+        `${style.dim('Install')}   agora install <id> [--write]`,
+        `${style.dim('Setup')}     agora init [--mcp] · agora use <workflow>`,
+        `${style.dim('Auth')}      agora login [--api-url <url>]`
     ].join('\n');
+    return `\n${banner}\n\n${box}\n\n${hint}\n`;
+}
+/** Flat-minimal section header: accent title, dim ` · `-joined metadata. */
+function header(title, meta) {
+    return [style.accent(title), ...meta.map((part) => style.dim(part))].join(style.dim(' · '));
+}
+function usage() {
+    const nameWidth = Math.max(...COMMANDS.map((c) => c.name.length));
+    const groups = ['Marketplace', 'Setup', 'Library', 'Learn', 'Community'];
+    const lines = [
+        `${style.accent('agora')}${style.dim(` · Developers' CLI marketplace and community hub · v${VERSION}`)}`,
+        ''
+    ];
+    for (const group of groups) {
+        const groupCmds = COMMANDS.filter((c) => c.group === group);
+        lines.push(style.dim(group));
+        for (const cmd of groupCmds) {
+            lines.push(`  ${style.accent(cmd.name.padEnd(nameWidth))}  ${style.dim(cmd.summary)}`);
+        }
+        lines.push('');
+    }
+    lines.push(style.dim('Run `agora help <command>` for details on any command.'));
+    return lines.join('\n');
+}
+export function commandManual(name) {
+    const meta = COMMANDS.find((c) => c.name === name);
+    if (!meta)
+        return '';
+    return renderManual(meta, style);
 }
 function usageError(io, message) {
     writeLine(io.stderr, message);
@@ -898,9 +1846,9 @@ function numberFlag(parsed, longName, shortName) {
     return Number.isFinite(parsedValue) ? parsedValue : undefined;
 }
 function authTokenInput(parsed, io) {
-    return requiredStringFlag(parsed, 'token') ||
+    return (requiredStringFlag(parsed, 'token') ||
         envString(io, 'AGORA_TOKEN') ||
-        envString(io, 'AGORA_API_TOKEN');
+        envString(io, 'AGORA_API_TOKEN'));
 }
 function envString(io, name) {
     const value = io.env?.[name];
@@ -912,6 +1860,8 @@ function shortFlag(arg) {
         return 'help';
     if (flag === 'j')
         return 'json';
+    if (flag === 'm')
+        return 'model';
     if (flag === 'c')
         return 'c';
     if (flag === 'n')
@@ -933,12 +1883,13 @@ function sourceOptions(parsed, io) {
     const storedAuth = getAuthState(loadAgoraState(detectDataDir(parsed, io)));
     const storedApiUrl = storedAuth?.apiUrl;
     const apiUrl = explicitApiUrl || envApiUrl || storedApiUrl || '';
-    const useApi = !parsed.flags.offline && Boolean(parsed.flags.api ||
-        parsed.flags.live ||
-        explicitApiUrl ||
-        envApiUrl ||
-        storedApiUrl ||
-        io.env?.AGORA_USE_API === 'true');
+    const useApi = !parsed.flags.offline &&
+        Boolean(parsed.flags.api ||
+            parsed.flags.live ||
+            explicitApiUrl ||
+            envApiUrl ||
+            storedApiUrl ||
+            io.env?.AGORA_USE_API === 'true');
     return {
         useApi,
         apiUrl,
@@ -950,10 +1901,16 @@ function sourceOptions(parsed, io) {
 function writeSourceOptions(parsed, io) {
     const options = sourceOptions(parsed, io);
     if (!options.apiUrl) {
-        return { ok: false, error: 'This command requires --api-url, AGORA_API_URL, or an auth login API URL' };
+        return {
+            ok: false,
+            error: 'This command requires --api-url, AGORA_API_URL, or an auth login API URL'
+        };
     }
     if (!options.token) {
-        return { ok: false, error: 'This command requires --token, AGORA_TOKEN, AGORA_API_TOKEN, or agora auth login' };
+        return {
+            ok: false,
+            error: 'This command requires --token, AGORA_TOKEN, AGORA_API_TOKEN, or agora auth login'
+        };
     }
     return {
         ok: true,
@@ -966,7 +1923,10 @@ function writeSourceOptions(parsed, io) {
 function readSourceOptions(parsed, io) {
     const options = sourceOptions(parsed, io);
     if (!options.apiUrl) {
-        return { ok: false, error: 'This command requires --api-url, AGORA_API_URL, or an auth login API URL' };
+        return {
+            ok: false,
+            error: 'This command requires --api-url, AGORA_API_URL, or an auth login API URL'
+        };
     }
     return { ok: true, options: { ...options, useApi: true } };
 }
@@ -974,24 +1934,35 @@ function tagsFlag(parsed) {
     const value = stringFlag(parsed, 'tags');
     if (!value)
         return [];
-    return value.split(',').map((tag) => tag.trim()).filter(Boolean);
+    return value
+        .split(',')
+        .map((tag) => tag.trim())
+        .filter(Boolean);
 }
-function promptInput(parsed) {
+function promptInput(parsed, io) {
     const prompt = stringFlag(parsed, 'prompt');
     if (prompt)
         return prompt;
     const promptFile = stringFlag(parsed, 'promptFile');
     if (!promptFile)
         return undefined;
+    if (!existsSync(promptFile)) {
+        usageError(io, `prompt-file not found: ${promptFile}`);
+        return undefined;
+    }
     return readFileSync(promptFile, 'utf8');
 }
-function contentInput(parsed) {
+function contentInput(parsed, io) {
     const content = requiredStringFlag(parsed, 'content');
     if (content)
         return content;
     const contentFile = stringFlag(parsed, 'contentFile');
     if (!contentFile)
         return undefined;
+    if (!existsSync(contentFile)) {
+        usageError(io, `content-file not found: ${contentFile}`);
+        return undefined;
+    }
     return readFileSync(contentFile, 'utf8').trim();
 }
 function itemTypeFlag(parsed, itemId) {
@@ -1002,10 +1973,16 @@ function itemTypeFlag(parsed, itemId) {
 }
 function discussionCategoryFlag(parsed) {
     const category = stringFlag(parsed, 'category', 'c') || 'discussion';
-    if (category === 'question' || category === 'idea' || category === 'showcase' || category === 'discussion') {
+    if (category === 'question' ||
+        category === 'idea' ||
+        category === 'showcase' ||
+        category === 'discussion') {
         return { ok: true, value: category };
     }
-    return { ok: false, error: 'discussion category must be question, idea, showcase, or discussion' };
+    return {
+        ok: false,
+        error: 'discussion category must be question, idea, showcase, or discussion'
+    };
 }
 function tutorialLevelFlag(parsed) {
     const level = stringFlag(parsed, 'level') || 'all';
@@ -1035,6 +2012,11 @@ function tutorialStepPayload(tutorial, stepNumber) {
         code: step?.code
     };
 }
+function sourceLabel(result) {
+    return result.source === 'offline'
+        ? `source: offline · refreshed ${dataRefreshedAt}`
+        : `source: ${result.source}`;
+}
 function warnFallback(result, io) {
     if (result.fallbackReason) {
         writeLine(io.stderr, `API unavailable, using offline data (refreshed ${dataRefreshedAt}): ${result.fallbackReason}`);
@@ -1095,13 +2077,6 @@ function truncate(value, max) {
         return value;
     return `${value.slice(0, max - 3)}...`;
 }
-function formatCount(value) {
-    if (value >= 1000000)
-        return `${(value / 1000000).toFixed(1)}M`;
-    if (value >= 1000)
-        return `${(value / 1000).toFixed(1)}K`;
-    return String(value);
-}
 function formatDate(value) {
     return value.slice(0, 10);
 }