bitcompass 0.3.5 → 0.3.7

package/dist/commands/commands.d.ts

@@ -1,5 +1,9 @@
-export declare const runCommandsSearch: (query?: string) => Promise<void>;
-export declare const runCommandsList: () => Promise<void>;
+export declare const runCommandsSearch: (query?: string, options?: {
+    listOnly?: boolean;
+}) => Promise<void>;
+export declare const runCommandsList: (options?: {
+    table?: boolean;
+}) => Promise<void>;
 export declare const runCommandsPull: (id?: string, options?: {
     global?: boolean;
     copy?: boolean;

package/dist/commands/commands.js

@@ -4,7 +4,8 @@ import chalk from 'chalk';
 import { loadCredentials } from '../auth/config.js';
 import { searchRules, fetchRules, getRuleById, insertRule } from '../api/client.js';
 import { pullRuleToFile } from '../lib/rule-file-ops.js';
-export const runCommandsSearch = async (query) => {
+import { formatList, shouldUseTable } from '../lib/list-format.js';
+export const runCommandsSearch = async (query, options) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
         process.exit(1);
@@ -17,6 +18,10 @@ export const runCommandsSearch = async (query) => {
         console.log(chalk.yellow('No commands found.'));
         return;
     }
+    if (options?.listOnly) {
+        formatList(list.map((r) => ({ id: r.id, title: r.title, kind: r.kind })), { useTable: shouldUseTable(), showKind: true });
+        return;
+    }
     const choice = await inquirer.prompt([
         {
             name: 'id',
@@ -31,7 +36,7 @@ export const runCommandsSearch = async (query) => {
         console.log(rule.body);
     }
 };
-export const runCommandsList = async () => {
+export const runCommandsList = async (options) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
         process.exit(1);
@@ -39,9 +44,12 @@ export const runCommandsList = async () => {
     const spinner = ora('Loading commands…').start();
     const list = await fetchRules('command');
     spinner.stop();
-    list.forEach((r) => console.log(`${chalk.cyan(r.title)}  ${chalk.dim(r.id)}`));
-    if (list.length === 0)
+    if (list.length === 0) {
         console.log(chalk.yellow('No commands yet.'));
+        return;
+    }
+    const useTable = shouldUseTable(options?.table);
+    formatList(list.map((r) => ({ id: r.id, title: r.title, kind: r.kind })), { useTable, showKind: false });
 };
 export const runCommandsPull = async (id, options) => {
     if (!loadCredentials()) {
@@ -82,8 +90,9 @@ export const runCommandsPull = async (id, options) => {
     }
     catch (error) {
         spinner.fail(chalk.red('Failed to pull command'));
-        console.error(chalk.red(error.message));
-        process.exit(1);
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(message));
+        process.exit(message.includes('not found') ? 2 : 1);
     }
 };
 export const runCommandsPush = async (file) => {

package/dist/commands/config-cmd.js

@@ -16,7 +16,7 @@ export const runConfigSet = (key, value) => {
     const config = loadConfig();
     if (!CONFIG_KEYS.includes(key)) {
         console.error(chalk.red('Unknown key. Use one of:'), CONFIG_KEYS.join(', '));
-        process.exit(1);
+        process.exit(2);
     }
     config[key] = value;
     saveConfig(config);
@@ -26,7 +26,7 @@ export const runConfigGet = (key) => {
     const config = loadConfig();
     if (!CONFIG_KEYS.includes(key)) {
         console.error(chalk.red('Unknown key.'));
-        process.exit(1);
+        process.exit(2);
     }
     const val = config[key] ?? process.env[`BITCOMPASS_${key.toUpperCase()}`];
     console.log(val ?? '');

package/dist/commands/glossary.d.ts

@@ -0,0 +1 @@
+export declare const runGlossary: () => void;

package/dist/commands/glossary.js

@@ -0,0 +1,16 @@
+import chalk from 'chalk';
+import { readFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Path to glossary.md in the CLI package (works when run from source or installed). */
+const getGlossaryPath = () => join(__dirname, '..', '..', 'glossary.md');
+export const runGlossary = () => {
+    const path = getGlossaryPath();
+    if (!existsSync(path)) {
+        console.error(chalk.red('Glossary file not found.'));
+        process.exit(1);
+    }
+    const content = readFileSync(path, 'utf8');
+    console.log(content.trim());
+};

package/dist/commands/log.d.ts

@@ -1,9 +1,11 @@
 import type { TimeFrame } from '../lib/git-analysis.js';
+export type LogProgressStep = 'analyzing' | 'pushing';
 /**
  * Shared logic: resolve repo, compute period, gather summary + git analysis, insert log.
  * Used by both CLI and MCP. Returns the created log id or throws.
+ * Optional onProgress callback for CLI to show step-wise spinner (e.g. analyzing → pushing).
  */
-export declare const buildAndPushActivityLog: (timeFrame: TimeFrame, cwd: string) => Promise<{
+export declare const buildAndPushActivityLog: (timeFrame: TimeFrame, cwd: string, onProgress?: (step: LogProgressStep) => void) => Promise<{
     id: string;
 }>;
 /**
@@ -13,7 +15,7 @@ export declare const buildAndPushActivityLogWithPeriod: (period: {
     period_start: string;
     period_end: string;
     since: string;
-}, timeFrame: TimeFrame, cwd: string) => Promise<{
+}, timeFrame: TimeFrame, cwd: string, onProgress?: (step: LogProgressStep) => void) => Promise<{
     id: string;
 }>;
 /** Parse argv for log: [start] or [start, end] or [start, '-', end]. Returns { start, end } or null for interactive. */
@@ -21,4 +23,8 @@ export declare const parseLogArgs: (args: string[]) => {
     start: string;
     end?: string;
 } | null;
+/** Thrown for invalid date args; CLI should exit with code 2. */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
 export declare const runLog: (args?: string[]) => Promise<void>;

package/dist/commands/log.js

@@ -1,18 +1,21 @@
 import inquirer from 'inquirer';
+import ora from 'ora';
 import chalk from 'chalk';
 import { insertActivityLog } from '../api/client.js';
 import { loadCredentials } from '../auth/config.js';
-import { getRepoRoot, getRepoSummary, getGitAnalysis, getPeriodForTimeFrame, getPeriodForCustomDates, } from '../lib/git-analysis.js';
+import { getRepoRoot, getRepoSummary, getGitAnalysis, getPeriodForTimeFrame, getPeriodForCustomDates, parseDate, } from '../lib/git-analysis.js';
 /**
  * Shared logic: resolve repo, compute period, gather summary + git analysis, insert log.
  * Used by both CLI and MCP. Returns the created log id or throws.
+ * Optional onProgress callback for CLI to show step-wise spinner (e.g. analyzing → pushing).
  */
-export const buildAndPushActivityLog = async (timeFrame, cwd) => {
+export const buildAndPushActivityLog = async (timeFrame, cwd, onProgress) => {
     const repoRoot = getRepoRoot(cwd);
     if (!repoRoot) {
         throw new Error('Not a git repository. Run from a project with git or pass a valid repo path.');
     }
     const period = getPeriodForTimeFrame(timeFrame);
+    onProgress?.('analyzing');
     const repo_summary = getRepoSummary(repoRoot);
     const git_analysis = getGitAnalysis(repoRoot, period.since);
     const payload = {
@@ -22,17 +25,19 @@ export const buildAndPushActivityLog = async (timeFrame, cwd) => {
         repo_summary: repo_summary,
         git_analysis: git_analysis,
     };
+    onProgress?.('pushing');
     const created = await insertActivityLog(payload);
     return { id: created.id };
 };
 /**
  * Push an activity log for a custom date or date range. timeFrame is used for display (day/week/month).
  */
-export const buildAndPushActivityLogWithPeriod = async (period, timeFrame, cwd) => {
+export const buildAndPushActivityLogWithPeriod = async (period, timeFrame, cwd, onProgress) => {
     const repoRoot = getRepoRoot(cwd);
     if (!repoRoot) {
         throw new Error('Not a git repository. Run from a project with git or pass a valid repo path.');
     }
+    onProgress?.('analyzing');
     const repo_summary = getRepoSummary(repoRoot);
     const git_analysis = getGitAnalysis(repoRoot, period.since, period.period_end);
     const payload = {
@@ -42,6 +47,7 @@ export const buildAndPushActivityLogWithPeriod = async (period, timeFrame, cwd)
         repo_summary: repo_summary,
         git_analysis: git_analysis,
     };
+    onProgress?.('pushing');
     const created = await insertActivityLog(payload);
     return { id: created.id };
 };
@@ -62,6 +68,13 @@ export const parseLogArgs = (args) => {
     }
     throw new Error('Usage: bitcompass log [YYYY-MM-DD] or bitcompass log [YYYY-MM-DD] [YYYY-MM-DD] or bitcompass log [YYYY-MM-DD] - [YYYY-MM-DD]');
 };
+/** Thrown for invalid date args; CLI should exit with code 2. */
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
 /** Choose time_frame for a custom range by span (day ≤ 1, week ≤ 7, else month). */
 const timeFrameForRange = (start, end) => {
     const a = new Date(start);
@@ -85,13 +98,33 @@ export const runLog = async (args = []) => {
         process.exit(1);
     }
     const parsed = parseLogArgs(args);
+    const spinner = ora('Analyzing repository…').start();
+    const onProgress = (step) => {
+        spinner.text = step === 'analyzing' ? 'Analyzing repository…' : 'Pushing activity log…';
+    };
     if (parsed) {
+        if (!parseDate(parsed.start)) {
+            spinner.stop();
+            throw new ValidationError(`Invalid date "${parsed.start}". Use YYYY-MM-DD (e.g. 2025-02-06).`);
+        }
+        if (parsed.end !== undefined && !parseDate(parsed.end)) {
+            spinner.stop();
+            throw new ValidationError(`Invalid date "${parsed.end}". Use YYYY-MM-DD (e.g. 2025-02-06).`);
+        }
         const period = getPeriodForCustomDates(parsed.start, parsed.end);
         const timeFrame = parsed.end ? timeFrameForRange(parsed.start, parsed.end) : 'day';
-        const result = await buildAndPushActivityLogWithPeriod(period, timeFrame, cwd);
-        console.log(chalk.green('Log saved.'), chalk.dim(result.id));
+        try {
+            const result = await buildAndPushActivityLogWithPeriod(period, timeFrame, cwd, onProgress);
+            spinner.succeed(chalk.green('Log saved.'));
+            console.log(chalk.dim(result.id));
+        }
+        catch (err) {
+            spinner.fail(chalk.red(err instanceof Error ? err.message : 'Failed'));
+            throw err;
+        }
         return;
     }
+    spinner.stop();
     const choice = await inquirer.prompt([
         {
             name: 'time_frame',
@@ -105,6 +138,14 @@ export const runLog = async (args = []) => {
         },
     ]);
     const timeFrame = choice.time_frame;
-    const result = await buildAndPushActivityLog(timeFrame, cwd);
-    console.log(chalk.green('Log saved.'), chalk.dim(result.id));
+    spinner.start('Analyzing repository…');
+    try {
+        const result = await buildAndPushActivityLog(timeFrame, cwd, onProgress);
+        spinner.succeed(chalk.green('Log saved.'));
+        console.log(chalk.dim(result.id));
+    }
+    catch (err) {
+        spinner.fail(chalk.red(err instanceof Error ? err.message : 'Failed'));
+        throw err;
+    }
 };

package/dist/commands/login.js

@@ -83,6 +83,42 @@ const CALLBACK_SUCCESS_HTML = `<!DOCTYPE html>
       font-size: 0.8125rem;
       color: ${STYLES.muted};
     }
+    .verify-block {
+      margin-top: 1rem;
+      padding-top: 1rem;
+      border-top: 1px solid ${STYLES.border};
+      font-size: 0.8125rem;
+      color: ${STYLES.muted};
+    }
+    .cmd-row {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: 0.5rem;
+      margin-top: 0.5rem;
+      flex-wrap: wrap;
+    }
+    .cmd {
+      font-family: ui-monospace, monospace;
+      font-size: 0.8125rem;
+      padding: 0.375rem 0.75rem;
+      background: ${STYLES.background};
+      border: 1px solid ${STYLES.border};
+      border-radius: 0.375rem;
+      color: ${STYLES.foreground};
+    }
+    .copy-btn {
+      font-size: 0.8125rem;
+      padding: 0.375rem 0.75rem;
+      background: ${STYLES.primary};
+      color: ${STYLES.primaryForeground};
+      border: none;
+      border-radius: 0.375rem;
+      cursor: pointer;
+      font-weight: 500;
+    }
+    .copy-btn:hover { opacity: 0.9; }
+    .copy-btn.copied { background: ${STYLES.muted}; cursor: default; }
   </style>
 </head>
 <body>
@@ -96,7 +132,31 @@ const CALLBACK_SUCCESS_HTML = `<!DOCTYPE html>
     <h1>You're all set</h1>
     <p class="muted">You're logged in successfully. You can close this window safely—your credentials are saved and the CLI is ready to use.</p>
     <p class="hint">Return to your terminal to continue.</p>
+    <div class="verify-block">
+      <p class="muted" style="margin:0">Verify in terminal:</p>
+      <div class="cmd-row">
+        <code class="cmd" id="whoami-cmd">bitcompass whoami</code>
+        <button type="button" class="copy-btn" id="copy-btn" aria-label="Copy command">Copy</button>
+      </div>
+    </div>
   </div>
+  <script>
+    (function() {
+      var btn = document.getElementById('copy-btn');
+      var cmd = document.getElementById('whoami-cmd');
+      if (!btn || !cmd) return;
+      btn.addEventListener('click', function() {
+        navigator.clipboard.writeText('bitcompass whoami').then(function() {
+          btn.textContent = 'Copied!';
+          btn.classList.add('copied');
+          setTimeout(function() {
+            btn.textContent = 'Copy';
+            btn.classList.remove('copied');
+          }, 2000);
+        });
+      });
+    })();
+  </script>
 </body>
 </html>`;
 const escapeHtml = (s) => s

package/dist/commands/rules.d.ts

@@ -1,5 +1,9 @@
-export declare const runRulesSearch: (query?: string) => Promise<void>;
-export declare const runRulesList: () => Promise<void>;
+export declare const runRulesSearch: (query?: string, options?: {
+    listOnly?: boolean;
+}) => Promise<void>;
+export declare const runRulesList: (options?: {
+    table?: boolean;
+}) => Promise<void>;
 export declare const runRulesPull: (id?: string, options?: {
     global?: boolean;
     copy?: boolean;

package/dist/commands/rules.js

@@ -4,7 +4,8 @@ import chalk from 'chalk';
 import { loadCredentials } from '../auth/config.js';
 import { searchRules, fetchRules, getRuleById, insertRule } from '../api/client.js';
 import { pullRuleToFile } from '../lib/rule-file-ops.js';
-export const runRulesSearch = async (query) => {
+import { formatList, shouldUseTable } from '../lib/list-format.js';
+export const runRulesSearch = async (query, options) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
         process.exit(1);
@@ -17,6 +18,10 @@ export const runRulesSearch = async (query) => {
         console.log(chalk.yellow('No rules found.'));
         return;
     }
+    if (options?.listOnly) {
+        formatList(list.map((r) => ({ id: r.id, title: r.title, kind: r.kind })), { useTable: shouldUseTable(), showKind: true });
+        return;
+    }
     const choice = await inquirer.prompt([
         {
             name: 'id',
@@ -31,7 +36,7 @@ export const runRulesSearch = async (query) => {
         console.log(rule.body);
     }
 };
-export const runRulesList = async () => {
+export const runRulesList = async (options) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
         process.exit(1);
@@ -39,9 +44,12 @@ export const runRulesList = async () => {
     const spinner = ora('Loading rules…').start();
     const list = await fetchRules('rule');
     spinner.stop();
-    list.forEach((r) => console.log(`${chalk.cyan(r.title)}  ${chalk.dim(r.id)}`));
-    if (list.length === 0)
+    if (list.length === 0) {
         console.log(chalk.yellow('No rules yet.'));
+        return;
+    }
+    const useTable = shouldUseTable(options?.table);
+    formatList(list.map((r) => ({ id: r.id, title: r.title, kind: r.kind })), { useTable, showKind: false });
 };
 export const runRulesPull = async (id, options) => {
     if (!loadCredentials()) {
@@ -82,8 +90,9 @@ export const runRulesPull = async (id, options) => {
     }
     catch (error) {
         spinner.fail(chalk.red('Failed to pull rule'));
-        console.error(chalk.red(error.message));
-        process.exit(1);
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(message));
+        process.exit(message.includes('not found') ? 2 : 1);
     }
 };
 export const runRulesPush = async (file) => {

package/dist/commands/skills.d.ts

@@ -1,5 +1,9 @@
-export declare const runSkillsSearch: (query?: string) => Promise<void>;
-export declare const runSkillsList: () => Promise<void>;
+export declare const runSkillsSearch: (query?: string, options?: {
+    listOnly?: boolean;
+}) => Promise<void>;
+export declare const runSkillsList: (options?: {
+    table?: boolean;
+}) => Promise<void>;
 export declare const runSkillsPull: (id?: string, options?: {
     global?: boolean;
     copy?: boolean;

package/dist/commands/skills.js

@@ -4,7 +4,8 @@ import chalk from 'chalk';
 import { loadCredentials } from '../auth/config.js';
 import { searchRules, fetchRules, getRuleById, insertRule } from '../api/client.js';
 import { pullRuleToFile } from '../lib/rule-file-ops.js';
-export const runSkillsSearch = async (query) => {
+import { formatList, shouldUseTable } from '../lib/list-format.js';
+export const runSkillsSearch = async (query, options) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
         process.exit(1);
@@ -17,6 +18,10 @@ export const runSkillsSearch = async (query) => {
         console.log(chalk.yellow('No skills found.'));
         return;
     }
+    if (options?.listOnly) {
+        formatList(list.map((r) => ({ id: r.id, title: r.title, kind: r.kind })), { useTable: shouldUseTable(), showKind: true });
+        return;
+    }
     const choice = await inquirer.prompt([
         {
             name: 'id',
@@ -31,7 +36,7 @@ export const runSkillsSearch = async (query) => {
         console.log(rule.body);
     }
 };
-export const runSkillsList = async () => {
+export const runSkillsList = async (options) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
         process.exit(1);
@@ -39,9 +44,12 @@ export const runSkillsList = async () => {
     const spinner = ora('Loading skills…').start();
     const list = await fetchRules('skill');
     spinner.stop();
-    list.forEach((r) => console.log(`${chalk.cyan(r.title)}  ${chalk.dim(r.id)}`));
-    if (list.length === 0)
+    if (list.length === 0) {
         console.log(chalk.yellow('No skills yet.'));
+        return;
+    }
+    const useTable = shouldUseTable(options?.table);
+    formatList(list.map((r) => ({ id: r.id, title: r.title, kind: r.kind })), { useTable, showKind: false });
 };
 export const runSkillsPull = async (id, options) => {
     if (!loadCredentials()) {
@@ -82,8 +90,9 @@ export const runSkillsPull = async (id, options) => {
     }
     catch (error) {
         spinner.fail(chalk.red('Failed to pull skill'));
-        console.error(chalk.red(error.message));
-        process.exit(1);
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(message));
+        process.exit(message.includes('not found') ? 2 : 1);
     }
 };
 export const runSkillsPush = async (file) => {

package/dist/commands/solutions.d.ts

@@ -1,4 +1,9 @@
-export declare const runSolutionsSearch: (query?: string) => Promise<void>;
+export declare const runSolutionsSearch: (query?: string, options?: {
+    listOnly?: boolean;
+}) => Promise<void>;
+export declare const runSolutionsList: (options?: {
+    table?: boolean;
+}) => Promise<void>;
 export declare const runSolutionsPull: (id?: string, options?: {
     global?: boolean;
     copy?: boolean;

package/dist/commands/solutions.js

@@ -4,7 +4,8 @@ import chalk from 'chalk';
 import { loadCredentials } from '../auth/config.js';
 import { searchRules, fetchRules, getRuleById, insertRule } from '../api/client.js';
 import { pullRuleToFile } from '../lib/rule-file-ops.js';
-export const runSolutionsSearch = async (query) => {
+import { formatList, shouldUseTable } from '../lib/list-format.js';
+export const runSolutionsSearch = async (query, options) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
         process.exit(1);
@@ -17,6 +18,10 @@ export const runSolutionsSearch = async (query) => {
         console.log(chalk.yellow('No solutions found.'));
         return;
     }
+    if (options?.listOnly) {
+        formatList(list.map((r) => ({ id: r.id, title: r.title, kind: r.kind })), { useTable: shouldUseTable(), showKind: true });
+        return;
+    }
     const choice = await inquirer.prompt([
         {
             name: 'id',
@@ -31,6 +36,21 @@ export const runSolutionsSearch = async (query) => {
         console.log(rule.body);
     }
 };
+export const runSolutionsList = async (options) => {
+    if (!loadCredentials()) {
+        console.error(chalk.red('Not logged in. Run bitcompass login.'));
+        process.exit(1);
+    }
+    const spinner = ora('Loading solutions…').start();
+    const list = await fetchRules('solution');
+    spinner.stop();
+    if (list.length === 0) {
+        console.log(chalk.yellow('No solutions yet.'));
+        return;
+    }
+    const useTable = shouldUseTable(options?.table);
+    formatList(list.map((r) => ({ id: r.id, title: r.title, kind: r.kind })), { useTable, showKind: false });
+};
 export const runSolutionsPull = async (id, options) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
@@ -70,8 +90,9 @@ export const runSolutionsPull = async (id, options) => {
     }
     catch (error) {
         spinner.fail(chalk.red('Failed to pull solution'));
-        console.error(chalk.red(error.message));
-        process.exit(1);
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(message));
+        process.exit(message.includes('not found') ? 2 : 1);
     }
 };
 export const runSolutionsPush = async (file) => {

package/dist/index.js

@@ -10,12 +10,17 @@ import { runInit } from './commands/init.js';
 import { runLogin } from './commands/login.js';
 import { runLogout } from './commands/logout.js';
 import { runMcpStart, runMcpStatus } from './commands/mcp.js';
-import { runLog } from './commands/log.js';
+import { runLog, ValidationError } from './commands/log.js';
 import { runRulesList, runRulesPull, runRulesPush, runRulesSearch } from './commands/rules.js';
-import { runSolutionsPull, runSolutionsPush, runSolutionsSearch } from './commands/solutions.js';
+import { runSolutionsList, runSolutionsPull, runSolutionsPush, runSolutionsSearch } from './commands/solutions.js';
 import { runSkillsList, runSkillsPull, runSkillsPush, runSkillsSearch } from './commands/skills.js';
 import { runCommandsList, runCommandsPull, runCommandsPush, runCommandsSearch } from './commands/commands.js';
+import { runGlossary } from './commands/glossary.js';
 import { runWhoami } from './commands/whoami.js';
+// Disable chalk colors when NO_COLOR is set or --no-color is passed (must run before any command)
+if (process.env.NO_COLOR !== undefined || process.argv.includes('--no-color')) {
+    chalk.level = 0;
+}
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = join(__dirname, '..', 'package.json');
@@ -25,7 +30,8 @@ const program = new Command();
 program
     .name('bitcompass')
     .description('BitCompass CLI - rules, solutions, and MCP server')
-    .version(version, '-v, -V, --version', 'display version number');
+    .version(version, '-v, -V, --version', 'display version number')
+    .option('--no-color', 'Disable colored output');
 program
     .command('login')
     .description('Log in with Google (opens browser)')
@@ -38,6 +44,10 @@ program
     .command('whoami')
     .description('Show current user (email)')
     .action(runWhoami);
+program
+    .command('glossary')
+    .description('Show glossary (rules, solutions, skills, commands)')
+    .action(runGlossary);
 program
     .command('init')
     .description('Configure project: editor/AI provider and output folder for rules/docs/commands')
@@ -45,7 +55,19 @@ program
 program
     .command('log [dates...]')
     .description('Collect repo summary and git activity, then push to your activity logs. Optional: bitcompass log YYYY-MM-DD or bitcompass log YYYY-MM-DD YYYY-MM-DD')
-    .action((dates) => runLog(dates ?? []).catch(handleErr));
+    .addHelpText('after', `
+Examples:
+  bitcompass log
+  bitcompass log 2025-02-01
+  bitcompass log 2025-02-01 2025-02-05
+`)
+    .action((dates) => runLog(dates ?? []).catch((err) => {
+    if (err instanceof ValidationError) {
+        console.error(chalk.red(err.message));
+        process.exit(2);
+    }
+    handleErr(err);
+}));
 const configCmd = program.command('config').description('Show or set config');
 configCmd.action(runConfigList);
 configCmd.command('list').description('List config values').action(runConfigList);
@@ -53,45 +75,86 @@ configCmd.command('set <key> <value>').description('Set supabaseUrl, supabaseAno
 configCmd.command('get <key>').description('Get a config value').action((key) => runConfigGet(key));
 // rules
 const rules = program.command('rules').description('Manage rules');
-rules.command('search [query]').description('Search rules').action((query) => runRulesSearch(query).catch(handleErr));
-rules.command('list').description('List rules').action(() => runRulesList().catch(handleErr));
+rules
+    .command('search [query]')
+    .description('Search rules')
+    .option('-l, --list', 'List results only; do not prompt to select')
+    .action((query, cmd) => runRulesSearch(query, { listOnly: cmd?.opts()?.list }).catch(handleErr));
+rules
+    .command('list')
+    .description('List rules')
+    .option('--table', 'Show output in aligned columns (default when TTY)')
+    .addHelpText('after', '\nExamples:\n  bitcompass rules list\n  bitcompass rules list --table\n')
+    .action((opts) => runRulesList({ table: opts.table }).catch(handleErr));
 rules
     .command('pull [id]')
     .description('Pull a rule by ID or choose from list (creates symbolic link by default)')
     .option('-g, --global', 'Install globally to ~/.cursor/rules/ for all projects')
     .option('--copy', 'Copy file instead of creating symbolic link')
+    .addHelpText('after', '\nExamples:\n  bitcompass rules pull <id>\n  bitcompass rules pull <id> --global\n  bitcompass rules pull <id> --copy\n')
     .action((id, options) => runRulesPull(id, options).catch(handleErr));
 rules.command('push [file]').description('Push a rule (file or interactive)').action((file) => runRulesPush(file).catch(handleErr));
 // solutions
 const solutions = program.command('solutions').description('Manage solutions');
-solutions.command('search [query]').description('Search solutions').action((query) => runSolutionsSearch(query).catch(handleErr));
+solutions
+    .command('search [query]')
+    .description('Search solutions')
+    .option('-l, --list', 'List results only; do not prompt to select')
+    .action((query, cmd) => runSolutionsSearch(query, { listOnly: cmd?.opts()?.list }).catch(handleErr));
+solutions
+    .command('list')
+    .description('List solutions')
+    .option('--table', 'Show output in aligned columns (default when TTY)')
+    .addHelpText('after', '\nExamples:\n  bitcompass solutions list\n  bitcompass solutions list --table\n')
+    .action((opts) => runSolutionsList({ table: opts.table }).catch(handleErr));
 solutions
     .command('pull [id]')
     .description('Pull a solution by ID or choose from list (creates symbolic link by default)')
     .option('-g, --global', 'Install globally to ~/.cursor/rules/ for all projects')
     .option('--copy', 'Copy file instead of creating symbolic link')
+    .addHelpText('after', '\nExamples:\n  bitcompass solutions pull <id>\n  bitcompass solutions pull <id> --global\n')
     .action((id, options) => runSolutionsPull(id, options).catch(handleErr));
 solutions.command('push [file]').description('Push a solution (file or interactive)').action((file) => runSolutionsPush(file).catch(handleErr));
 // skills
 const skills = program.command('skills').description('Manage skills');
-skills.command('search [query]').description('Search skills').action((query) => runSkillsSearch(query).catch(handleErr));
-skills.command('list').description('List skills').action(() => runSkillsList().catch(handleErr));
+skills
+    .command('search [query]')
+    .description('Search skills')
+    .option('-l, --list', 'List results only; do not prompt to select')
+    .action((query, cmd) => runSkillsSearch(query, { listOnly: cmd?.opts()?.list }).catch(handleErr));
+skills
+    .command('list')
+    .description('List skills')
+    .option('--table', 'Show output in aligned columns (default when TTY)')
+    .addHelpText('after', '\nExamples:\n  bitcompass skills list\n  bitcompass skills list --table\n')
+    .action((opts) => runSkillsList({ table: opts.table }).catch(handleErr));
 skills
     .command('pull [id]')
     .description('Pull a skill by ID or choose from list (creates symbolic link by default)')
     .option('-g, --global', 'Install globally to ~/.cursor/rules/ for all projects')
     .option('--copy', 'Copy file instead of creating symbolic link')
+    .addHelpText('after', '\nExamples:\n  bitcompass skills pull <id>\n  bitcompass skills pull <id> --global\n')
     .action((id, options) => runSkillsPull(id, options).catch(handleErr));
 skills.command('push [file]').description('Push a skill (file or interactive)').action((file) => runSkillsPush(file).catch(handleErr));
 // commands
 const commands = program.command('commands').description('Manage commands');
-commands.command('search [query]').description('Search commands').action((query) => runCommandsSearch(query).catch(handleErr));
-commands.command('list').description('List commands').action(() => runCommandsList().catch(handleErr));
+commands
+    .command('search [query]')
+    .description('Search commands')
+    .option('-l, --list', 'List results only; do not prompt to select')
+    .action((query, cmd) => runCommandsSearch(query, { listOnly: cmd?.opts()?.list }).catch(handleErr));
+commands
+    .command('list')
+    .description('List commands')
+    .option('--table', 'Show output in aligned columns (default when TTY)')
+    .addHelpText('after', '\nExamples:\n  bitcompass commands list\n  bitcompass commands list --table\n')
+    .action((opts) => runCommandsList({ table: opts.table }).catch(handleErr));
 commands
     .command('pull [id]')
     .description('Pull a command by ID or choose from list (creates symbolic link by default)')
     .option('-g, --global', 'Install globally to ~/.cursor/rules/ for all projects')
     .option('--copy', 'Copy file instead of creating symbolic link')
+    .addHelpText('after', '\nExamples:\n  bitcompass commands pull <id>\n  bitcompass commands pull <id> --global\n')
     .action((id, options) => runCommandsPull(id, options).catch(handleErr));
 commands.command('push [file]').description('Push a command (file or interactive)').action((file) => runCommandsPush(file).catch(handleErr));
 // mcp
@@ -102,4 +165,11 @@ function handleErr(err) {
     console.error(chalk.red(err instanceof Error ? err.message : String(err)));
     process.exit(1);
 }
+if (process.argv.slice(2).length === 0) {
+    console.log(chalk.cyan('BitCompass') +
+        chalk.dim(' – rules, solutions, and MCP server. Run ') +
+        chalk.cyan('bitcompass --help') +
+        chalk.dim(' for commands.'));
+    process.exit(0);
+}
 program.parse();

package/dist/lib/git-analysis.d.ts

@@ -37,6 +37,11 @@ export declare const getRepoSummary: (repoRoot: string) => RepoSummary;
  * period_end is now; period_start and since are the start of the window.
  */
 export declare const getPeriodForTimeFrame: (timeFrame: TimeFrame) => PeriodBounds;
+/**
+ * Parse an ISO date string (YYYY-MM-DD) to Date at start of day (UTC).
+ * Returns null for invalid or non-calendar dates (e.g. 2025-02-30).
+ */
+export declare const parseDate: (s: string) => Date | null;
 /**
  * Compute period for custom date(s). Single date = that day; two dates = range (inclusive).
  * period_end is end of last day (23:59:59.999).

package/dist/lib/git-analysis.js

@@ -74,8 +74,9 @@ export const getPeriodForTimeFrame = (timeFrame) => {
 };
 /**
  * Parse an ISO date string (YYYY-MM-DD) to Date at start of day (UTC).
+ * Returns null for invalid or non-calendar dates (e.g. 2025-02-30).
  */
-const parseDate = (s) => {
+export const parseDate = (s) => {
     const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s.trim());
     if (!match)
         return null;
@@ -94,13 +95,13 @@ const parseDate = (s) => {
 export const getPeriodForCustomDates = (startDateStr, endDateStr) => {
     const startDate = parseDate(startDateStr);
     if (!startDate) {
-        throw new Error(`Invalid start date: ${startDateStr}. Use YYYY-MM-DD.`);
+        throw new Error(`Invalid start date: ${startDateStr}. Use YYYY-MM-DD (e.g. 2025-02-06).`);
     }
     let periodEnd;
     if (endDateStr !== undefined && endDateStr.trim() !== '') {
         const endDate = parseDate(endDateStr);
         if (!endDate)
-            throw new Error(`Invalid end date: ${endDateStr}. Use YYYY-MM-DD.`);
+            throw new Error(`Invalid end date: ${endDateStr}. Use YYYY-MM-DD (e.g. 2025-02-06).`);
         if (endDate < startDate)
             throw new Error('End date must be on or after start date.');
         periodEnd = new Date(endDate);

package/dist/lib/list-format.d.ts

@@ -0,0 +1,15 @@
+export interface ListRow {
+    id: string;
+    title: string;
+    kind?: string;
+}
+/**
+ * Format a list of rules/items for terminal output.
+ * When useTable is true (TTY or --table), prints aligned columns; otherwise one line per row for scripts/CI.
+ */
+export declare const formatList: (list: ListRow[], options: {
+    useTable: boolean;
+    showKind?: boolean;
+}) => void;
+/** Use table format when stdout is a TTY or when tableFlag is true. */
+export declare const shouldUseTable: (tableFlag?: boolean) => boolean;

package/dist/lib/list-format.js

@@ -0,0 +1,34 @@
+import chalk from 'chalk';
+const ID_COLUMN_WIDTH = 36;
+const TITLE_MAX_WIDTH = 50;
+const KIND_WIDTH = 10;
+/**
+ * Format a list of rules/items for terminal output.
+ * When useTable is true (TTY or --table), prints aligned columns; otherwise one line per row for scripts/CI.
+ */
+export const formatList = (list, options) => {
+    if (list.length === 0)
+        return;
+    const { useTable, showKind = false } = options;
+    if (useTable) {
+        const titleWidth = Math.min(TITLE_MAX_WIDTH, Math.max(...list.map((r) => r.title.length), 5));
+        const headerKind = showKind ? chalk.dim('Kind'.padEnd(KIND_WIDTH)) + ' ' : '';
+        console.log(chalk.bold('ID'.padEnd(ID_COLUMN_WIDTH)) +
+            ' ' +
+            chalk.bold('Title'.padEnd(titleWidth)) +
+            (showKind ? ' ' + chalk.bold('Kind') : ''));
+        const sep = '-'.repeat(ID_COLUMN_WIDTH + 1 + titleWidth + (showKind ? KIND_WIDTH + 2 : 0));
+        console.log(chalk.dim(sep));
+        for (const r of list) {
+            const id = r.id.length > ID_COLUMN_WIDTH ? r.id.slice(0, ID_COLUMN_WIDTH - 1) + '…' : r.id.padEnd(ID_COLUMN_WIDTH);
+            const title = r.title.length > titleWidth ? r.title.slice(0, titleWidth - 1) + '…' : r.title.padEnd(titleWidth);
+            const kindPart = showKind ? ' ' + (r.kind ?? '').padEnd(KIND_WIDTH) : '';
+            console.log(chalk.dim(id) + ' ' + chalk.cyan(title) + kindPart);
+        }
+    }
+    else {
+        list.forEach((r) => console.log(`${chalk.cyan(r.title)}  ${chalk.dim(r.id)}`));
+    }
+};
+/** Use table format when stdout is a TTY or when tableFlag is true. */
+export const shouldUseTable = (tableFlag) => Boolean(tableFlag ?? process.stdout.isTTY);

package/dist/mcp/server.js

@@ -1,8 +1,16 @@
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { AUTH_REQUIRED_MSG, insertRule, searchRules, getRuleById, fetchRules, updateRule, deleteRule, fetchActivityLogs, getActivityLogById, } from '../api/client.js';
 import { buildAndPushActivityLog } from '../commands/log.js';
 import { loadCredentials } from '../auth/config.js';
 import { getProjectConfig } from '../auth/project-config.js';
 import { pullRuleToFile } from '../lib/rule-file-ops.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// From dist/mcp/server.js (or src/mcp/server.ts when run via Bun), package.json is at package root
+const packageJsonPath = join(__dirname, '..', '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+const VERSION = packageJson.version ?? '0.0.0';
 /** When token is missing, we fail initialize so Cursor shows "Needs authentication" (yellow) instead of success (green). */
 const NEEDS_AUTH_ERROR_MESSAGE = 'Needs authentication';
 const NEEDS_AUTH_ERROR_CODE = -32001; // Server error: auth required
@@ -44,7 +52,7 @@ function createStdioServer() {
                     result: {
                         protocolVersion: '2024-11-05',
                         capabilities: { tools: {}, prompts: {} },
-                        serverInfo: { name: 'bitcompass', version: '0.1.0' },
+                        serverInfo: { name: 'bitcompass', version: VERSION },
                     },
                 });
                 return;
@@ -57,29 +65,33 @@ function createStdioServer() {
                         tools: [
                             {
                                 name: 'search-rules',
-                                description: 'Search BitCompass rules by query',
+                                description: 'Use when the user wants to find rules, solutions, skills, or commands by keyword or topic. Returns a list of matching items with id, title, kind, author, and a short body snippet. Optionally filter by kind (rule, solution, skill, command) and limit results.',
                                 inputSchema: {
                                     type: 'object',
-                                    properties: { query: { type: 'string' }, kind: { type: 'string', enum: ['rule', 'solution', 'skill', 'command'] }, limit: { type: 'number' } },
+                                    properties: {
+                                        query: { type: 'string', description: 'Search query or keywords' },
+                                        kind: { type: 'string', enum: ['rule', 'solution', 'skill', 'command'], description: 'Optional: restrict to one kind' },
+                                        limit: { type: 'number', description: 'Optional: max results (default 20)' },
+                                    },
                                     required: ['query'],
                                 },
                             },
                             {
                                 name: 'search-solutions',
-                                description: 'Search BitCompass solutions by query',
+                                description: 'Use when the user asks for problem solutions or how-to guides. Returns a list of solutions with id, title, author, and a short snippet. Prefer this over search-rules when the intent is clearly "solutions" or "problem solutions".',
                                 inputSchema: {
                                     type: 'object',
-                                    properties: { query: { type: 'string' }, limit: { type: 'number' } },
+                                    properties: { query: { type: 'string', description: 'Search query' }, limit: { type: 'number', description: 'Optional: max results' } },
                                     required: ['query'],
                                 },
                             },
                             {
                                 name: 'post-rules',
-                                description: 'Publish a new rule or solution to BitCompass',
+                                description: 'Use when the user wants to publish or share a new rule, solution, skill, or command to BitCompass. Requires kind, title, and body. Returns the created id and title on success. User must be logged in (bitcompass login).',
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
-                                        kind: { type: 'string', enum: ['rule', 'solution', 'skill', 'command'] },
+                                        kind: { type: 'string', enum: ['rule', 'solution', 'skill', 'command'], description: 'Type of entry to publish' },
                                         title: { type: 'string' },
                                         description: { type: 'string' },
                                         body: { type: 'string' },
@@ -92,7 +104,7 @@ function createStdioServer() {
                             },
                             {
                                 name: 'create-activity-log',
-                                description: "Collect a summary of the repository and git activity for the chosen period, then push the log to the user's private activity logs. Requires a git repository; if repo_path is not a git repo, returns an error. Ask the user which time frame they want: day, week, or month.",
+                                description: "Use when the user wants to record their repo activity (commits, files changed) for a time period. Ask for time_frame: day, week, or month. Requires a git repo at repo_path (default: cwd). Returns success and log id, or an error if not a git repo or auth missing.",
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
@@ -104,7 +116,7 @@ function createStdioServer() {
                             },
                             {
                                 name: 'get-rule',
-                                description: 'Get full details of a rule or solution by ID',
+                                description: 'Use when you have a rule/solution ID and need the full content (title, description, body, examples, technologies). Returns the complete rule object or an error if not found. Optional kind filter verifies the entry matches that type.',
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
@@ -116,7 +128,7 @@ function createStdioServer() {
                             },
                             {
                                 name: 'list-rules',
-                                description: 'List all rules and solutions (with optional filtering by kind)',
+                                description: 'Use when the user wants to browse or list all rules and/or solutions without a search query. Optional kind filter (rule or solution) and limit. Returns an array of items with id, title, kind, description, author, snippet, created_at, plus total/returned counts.',
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
@@ -127,7 +139,7 @@ function createStdioServer() {
                             },
                             {
                                 name: 'update-rule',
-                                description: 'Update an existing rule or solution',
+                                description: 'Use when the user wants to edit an existing rule or solution they own. Pass id and any fields to update (title, description, body, context, examples, technologies). Returns updated metadata. Requires authentication.',
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
@@ -144,7 +156,7 @@ function createStdioServer() {
                             },
                             {
                                 name: 'delete-rule',
-                                description: 'Delete a rule or solution by ID',
+                                description: 'Use when the user wants to remove a rule or solution by ID. Returns success or error. Requires authentication; user can only delete their own entries.',
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
@@ -155,7 +167,7 @@ function createStdioServer() {
                             },
                             {
                                 name: 'pull-rule',
-                                description: 'Pull a rule or solution to a file in the project rules directory',
+                                description: 'Use when the user wants to install a rule or solution into their project (e.g. "pull this rule to my project"). Writes the rule to the project rules directory or optional output_path; global installs to ~/.cursor/rules/. Returns the file path written or an error.',
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
@@ -168,7 +180,7 @@ function createStdioServer() {
                             },
                             {
                                 name: 'list-activity-logs',
-                                description: "List user's activity logs",
+                                description: "Use when the user wants to see their past activity logs (e.g. 'show my logs', 'list activity'). Optional limit and time_frame (day, week, month). Returns an array of logs with id, time_frame, period_start, period_end, created_at.",
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
@@ -179,7 +191,7 @@ function createStdioServer() {
                             },
                             {
                                 name: 'get-activity-log',
-                                description: 'Get activity log details by ID',
+                                description: 'Use when the user asks for details of a specific activity log by ID. Returns the full log: time_frame, period_start, period_end, repo_summary, git_analysis, created_at.',
                                 inputSchema: {
                                     type: 'object',
                                     properties: {
@@ -299,7 +311,11 @@ function createStdioServer() {
         const limit = args.limit ?? 20;
         try {
             const list = await searchRules(query, { kind, limit });
-            return { rules: list.map((r) => ({ id: r.id, title: r.title, kind: r.kind, author: r.author_display_name ?? null, snippet: r.body.slice(0, 200) })) };
+            const summary = list.length === 0 ? 'No rules found.' : `Found ${list.length} rule(s).`;
+            return {
+                rules: list.map((r) => ({ id: r.id, title: r.title, kind: r.kind, author: r.author_display_name ?? null, snippet: r.body.slice(0, 200) })),
+                summary,
+            };
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : 'Search failed.';
@@ -311,7 +327,11 @@ function createStdioServer() {
         const limit = args.limit ?? 20;
         try {
             const list = await searchRules(query, { kind: 'solution', limit });
-            return { solutions: list.map((r) => ({ id: r.id, title: r.title, author: r.author_display_name ?? null, snippet: r.body.slice(0, 200) })) };
+            const summary = list.length === 0 ? 'No solutions found.' : `Found ${list.length} solution(s).`;
+            return {
+                solutions: list.map((r) => ({ id: r.id, title: r.title, author: r.author_display_name ?? null, snippet: r.body.slice(0, 200) })),
+                summary,
+            };
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : 'Search failed.';
@@ -395,6 +415,11 @@ function createStdioServer() {
         try {
             const list = await fetchRules(kind);
             const limited = list.slice(0, limit);
+            const summary = list.length === 0
+                ? 'No rules found.'
+                : limited.length < list.length
+                    ? `Listed ${limited.length} of ${list.length} rule(s).`
+                    : `Found ${list.length} rule(s).`;
             return {
                 rules: limited.map((r) => ({
                     id: r.id,
@@ -407,6 +432,7 @@ function createStdioServer() {
                 })),
                 total: list.length,
                 returned: limited.length,
+                summary,
             };
         }
         catch (e) {
@@ -486,6 +512,7 @@ function createStdioServer() {
         const timeFrame = args.time_frame;
         try {
             const logs = await fetchActivityLogs({ limit, time_frame: timeFrame });
+            const summary = logs.length === 0 ? 'No activity logs found.' : `Found ${logs.length} activity log(s).`;
             return {
                 logs: logs.map((log) => ({
                     id: log.id,
@@ -495,6 +522,7 @@ function createStdioServer() {
                     created_at: log.created_at,
                 })),
                 total: logs.length,
+                summary,
             };
         }
         catch (e) {

package/glossary.md

@@ -0,0 +1,19 @@
+# BitCompass terminology
+
+Shared definitions for rules, solutions, skills, and commands.
+
+## Rule
+
+A **rule** is a reusable guideline or standard (e.g. coding style, when to use a tool) that can be pulled into a project. Rules are typically stored in `.cursor/rules/` or similar and guide AI or tooling behavior.
+
+## Solution
+
+A **solution** is a step-by-step or narrative answer to a specific problem (e.g. "How to fix X"). Solutions can be pulled like rules and are often used to document fixes or procedures.
+
+## Skill
+
+A **skill** is an extended capability or workflow for an agent (e.g. "Figma design-to-code"). Skills are installable into an agent environment and extend what the agent can do.
+
+## Command
+
+A **command** is an executable shortcut or script registered in BitCompass. Commands can be discovered and pulled into a project for reuse.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitcompass",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "BitCompass CLI - rules, solutions, and MCP server",
   "type": "module",
   "bin": {
@@ -49,6 +49,7 @@
   },
   "files": [
     "dist",
-    "scripts"
+    "scripts",
+    "glossary.md"
   ]
 }