chub-dev 0.2.0-beta.4 → 0.3.0

package/src/lib/config.js

@@ -5,14 +5,19 @@ import { parse as parseYaml } from 'yaml';
 
 const DEFAULT_CDN_URL = 'https://cdn.aichub.org/v1';
 const DEFAULT_TELEMETRY_URL = 'https://api.aichub.org/v1';
+const DEFAULT_HELP_URL = 'https://cdn.aichub.org/v1/help.json';
+const DEFAULT_HELP_TIMEOUT_MS = 2000;
 
 const DEFAULTS = {
   output_dir: '.context',
-  refresh_interval: 86400,
+  refresh_interval: 21600,
   output_format: 'human',
   source: 'official,maintainer,community',
   telemetry: true,
+  feedback: true,
   telemetry_url: DEFAULT_TELEMETRY_URL,
+  help_url: DEFAULT_HELP_URL,
+  help_timeout_ms: DEFAULT_HELP_TIMEOUT_MS,
 };
 
 let _config = null;
@@ -50,7 +55,15 @@ export function loadConfig() {
     output_format: fileConfig.output_format || DEFAULTS.output_format,
     source: fileConfig.source || DEFAULTS.source,
     telemetry: fileConfig.telemetry !== undefined ? fileConfig.telemetry : DEFAULTS.telemetry,
+    feedback: fileConfig.feedback !== undefined ? fileConfig.feedback : DEFAULTS.feedback,
     telemetry_url: fileConfig.telemetry_url || DEFAULTS.telemetry_url,
+    help_url: process.env.CHUB_HELP_URL
+      ?? (fileConfig.help_url !== undefined ? fileConfig.help_url : DEFAULTS.help_url),
+    help_timeout_ms: Number.parseInt(
+      process.env.CHUB_HELP_TIMEOUT_MS
+      ?? (fileConfig.help_timeout_ms ?? DEFAULTS.help_timeout_ms),
+      10
+    ) || DEFAULTS.help_timeout_ms,
   };
 
   return _config;

package/src/lib/help.js

@@ -0,0 +1,158 @@
+import { loadConfig } from './config.js';
+
+function normalizeHelpUrl(value) {
+  if (value === false || value === null) return null;
+  if (typeof value !== 'string') return value || null;
+
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+
+  const normalized = trimmed.toLowerCase();
+  if (['0', 'false', 'off', 'disabled', 'none', 'local'].includes(normalized)) {
+    return null;
+  }
+
+  return trimmed;
+}
+
+function buildRemoteHelpUrl(helpUrl, cliVersion) {
+  try {
+    const url = new URL(helpUrl);
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      return helpUrl;
+    }
+    url.searchParams.set('cli_version', cliVersion);
+    return url.toString();
+  } catch {
+    return helpUrl;
+  }
+}
+
+function parseRemoteHelpPayload(raw, contentType = '') {
+  const trimmed = raw.trim();
+  const looksLikeJson = contentType.includes('json') || (trimmed.startsWith('{') && trimmed.endsWith('}'));
+
+  if (!looksLikeJson) {
+    return { content: raw };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { content: raw };
+  }
+
+  if (typeof parsed === 'string') {
+    return { content: parsed };
+  }
+
+  if (!parsed || typeof parsed.content !== 'string') {
+    throw new Error('Invalid remote help payload');
+  }
+
+  const result = { content: parsed.content };
+  if (typeof parsed.updatedAt === 'string') result.updatedAt = parsed.updatedAt;
+  if (typeof parsed.version === 'string') result.version = parsed.version;
+  if (typeof parsed.minimumCliVersion === 'string') {
+    result.minimumCliVersion = parsed.minimumCliVersion;
+  }
+
+  return result;
+}
+
+export function getLocalHelpText(cliVersion) {
+  return [
+    `chub — Context Hub CLI v${cliVersion}`,
+    'Search and retrieve LLM-optimized docs and skills.',
+    '',
+    'Bootstrap workflow for coding agents',
+    '',
+    '  1. Start with chub before writing code against an external API, SDK, or library.',
+    '  2. Find the best entry with `chub search`.',
+    '  3. Fetch the exact doc or skill with `chub get`.',
+    '  4. Use that content instead of guessing from training data.',
+    '  5. If you discover a gap, save it with `chub annotate`.',
+    '  6. Always leave feedback after using a doc or skill.',
+    '',
+    'Quick start',
+    '',
+    '  $ chub search "openai" --json',
+    '  $ chub get openai/chat --lang py',
+    '  $ chub feedback openai/chat up --label accurate "Current and clear"',
+    '',
+    'Distribution surfaces',
+    '',
+    '  $ npx skills add chub-dev',
+    '  Copy `skills/get-api-docs/SKILL.md` into your agent\'s skill or rule directory when manual install is needed.',
+    '  Use `chub-mcp` for MCP-compatible agents that prefer tools over local skill files.',
+    '',
+    'If chub is not installed yet',
+    '',
+    '  $ npm install -g chub-dev',
+    '',
+    'Core commands',
+    '',
+    '  search [query]              Search docs and skills (no query = list all)',
+    '  get <ids...>                Fetch docs or skills by ID',
+    '  annotate [id] [note]        Save a note that appears on future fetches',
+    '  feedback <id> <up|down>     Rate a doc or skill after using it',
+    '  update                      Refresh the cached registry',
+    '  cache status|clear          Manage the local cache',
+    '',
+    'Feedback loop',
+    '',
+    '  After using a doc or skill, always run one of these:',
+    '  $ chub feedback <id> up --label accurate "What was useful"',
+    '  $ chub feedback <id> down --label outdated "What needs to be fixed"',
+    '',
+    '  Valid labels: accurate, well-structured, helpful, good-examples, outdated, inaccurate, incomplete, wrong-examples, wrong-version, poorly-structured',
+  ].join('\n');
+}
+
+export async function loadHelpContent(cliVersion, { fetchImpl = globalThis.fetch } = {}) {
+  const config = loadConfig();
+  const helpUrl = normalizeHelpUrl(config.help_url);
+
+  if (!helpUrl || typeof fetchImpl !== 'function') {
+    return {
+      source: 'local',
+      content: getLocalHelpText(cliVersion),
+      url: helpUrl || null,
+    };
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.help_timeout_ms || 2000);
+
+  try {
+    const response = await fetchImpl(buildRemoteHelpUrl(helpUrl, cliVersion), {
+      signal: controller.signal,
+      headers: {
+        accept: 'application/json, text/plain;q=0.9, text/markdown;q=0.8',
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`${response.status} ${response.statusText}`);
+    }
+
+    const contentType = response.headers?.get?.('content-type') || '';
+    const payload = parseRemoteHelpPayload(await response.text(), contentType);
+
+    return {
+      source: 'remote',
+      url: helpUrl,
+      ...payload,
+    };
+  } catch (err) {
+    return {
+      source: 'local',
+      content: getLocalHelpText(cliVersion),
+      url: helpUrl,
+      fallbackReason: err?.name === 'AbortError' ? 'timeout' : (err?.message || 'remote_help_unavailable'),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/lib/identity.js

@@ -63,7 +63,7 @@ export async function getOrCreateClientId() {
     // File doesn't exist or is unreadable
   }
 
-  // Generate from machine UUID
+  // Generate from machine UUID — this is a first-time user
   const uuid = getMachineUUID();
   const hash = createHash('sha256').update(uuid).digest('hex');
 
@@ -74,9 +74,20 @@ export async function getOrCreateClientId() {
 
   writeFileSync(idPath, hash, 'utf8');
   _cachedClientId = hash;
+  _isFirstRun = true;
   return hash;
 }
 
+let _isFirstRun = false;
+
+/**
+ * Returns true if this is the first time the CLI has run on this machine.
+ * Only valid after getOrCreateClientId() has been called.
+ */
+export function isFirstRun() {
+  return _isFirstRun;
+}
+
 /**
  * Auto-detect the AI coding tool from environment variables.
  */

package/src/lib/registry.js

@@ -1,11 +1,192 @@
 import { loadSourceRegistry, loadSearchIndex } from './cache.js';
 import { loadConfig } from './config.js';
 import { normalizeLanguage } from './normalize.js';
-import { search as bm25Search } from './bm25.js';
+import { buildIndexFromDocuments, compactIdentifier, search as bm25Search, tokenize } from './bm25.js';
 
 let _merged = null;
 let _searchIndex = null;
 
+function getSearchLookupId(sourceName, entryId) {
+  return `${sourceName}:${entryId}`;
+}
+
+function normalizeQuery(query) {
+  return String(query || '')
+    .trim()
+    .replace(/\s+/g, ' ');
+}
+
+function splitCompactSegments(text) {
+  return [...new Set([
+    ...String(text || '').split('/').map((segment) => compactIdentifier(segment)),
+    ...String(text || '').split(/[\/_.\s-]+/).map((segment) => compactIdentifier(segment)),
+  ])].filter(Boolean);
+}
+
+function levenshteinDistance(a, b, maxDistance = Infinity) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  if (Math.abs(a.length - b.length) > maxDistance) return maxDistance + 1;
+
+  let previous = Array.from({ length: b.length + 1 }, (_, idx) => idx);
+  let current = new Array(b.length + 1);
+
+  for (let i = 1; i <= a.length; i++) {
+    current[0] = i;
+    let rowMin = current[0];
+
+    for (let j = 1; j <= b.length; j++) {
+      const substitutionCost = a[i - 1] === b[j - 1] ? 0 : 1;
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + substitutionCost,
+      );
+      rowMin = Math.min(rowMin, current[j]);
+    }
+
+    if (rowMin > maxDistance) return maxDistance + 1;
+    [previous, current] = [current, previous];
+  }
+
+  return previous[b.length];
+}
+
+function scoreCompactCandidate(queryCompact, candidateCompact, weights) {
+  if (!queryCompact || !candidateCompact) return 0;
+  if (candidateCompact === queryCompact) return weights.exact;
+  if (queryCompact.length < 3) return 0;
+
+  const lengthPenalty = Math.abs(candidateCompact.length - queryCompact.length);
+  const lengthRatio = Math.min(candidateCompact.length, queryCompact.length)
+    / Math.max(candidateCompact.length, queryCompact.length);
+
+  if ((candidateCompact.startsWith(queryCompact) || queryCompact.startsWith(candidateCompact)) && lengthRatio >= 0.6) {
+    return Math.max(weights.prefix - lengthPenalty, 0);
+  }
+
+  if ((candidateCompact.includes(queryCompact) || queryCompact.includes(candidateCompact)) && lengthRatio >= 0.75) {
+    return Math.max(weights.contains - lengthPenalty, 0);
+  }
+
+  if (queryCompact.length < 5) return 0;
+
+  const maxDistance = queryCompact.length <= 5 ? 1 : queryCompact.length <= 8 ? 2 : 3;
+  const distance = levenshteinDistance(queryCompact, candidateCompact, maxDistance);
+  if (distance > maxDistance) return 0;
+
+  return Math.max(weights.fuzzy - (distance * 20) - lengthPenalty, 0);
+}
+
+function scoreEntryLexicalVariant(entry, queryCompact) {
+  if (queryCompact.length < 2) return 0;
+
+  const nameCompact = compactIdentifier(entry.name);
+  const idCompact = compactIdentifier(entry.id);
+  const idSegments = splitCompactSegments(entry.id);
+  const nameSegments = splitCompactSegments(entry.name);
+
+  let best = 0;
+
+  best = Math.max(best, scoreCompactCandidate(queryCompact, nameCompact, {
+    exact: 620,
+    prefix: 560,
+    contains: 520,
+    fuzzy: 500,
+  }));
+
+  best = Math.max(best, scoreCompactCandidate(queryCompact, idCompact, {
+    exact: 600,
+    prefix: 540,
+    contains: 500,
+    fuzzy: 470,
+  }));
+
+  for (let idx = 0; idx < idSegments.length; idx++) {
+    const segment = idSegments[idx];
+    const segmentScore = scoreCompactCandidate(queryCompact, segment, {
+      exact: 580,
+      prefix: 530,
+      contains: 490,
+      fuzzy: 460,
+    });
+    if (segmentScore === 0) continue;
+
+    let bonus = 0;
+    const isFirst = idx === 0;
+    const isLast = idx === idSegments.length - 1;
+    if (isFirst) bonus += 10;
+    if (isLast) bonus += 10;
+    if (queryCompact === idSegments[0]) bonus += 60;
+    if (queryCompact === idSegments[idSegments.length - 1]) bonus += 25;
+    if (idSegments.length > 1 && queryCompact === idSegments[0] && queryCompact === idSegments[idSegments.length - 1]) {
+      bonus += 40;
+    }
+
+    best = Math.max(best, segmentScore + bonus);
+  }
+
+  for (const segment of nameSegments) {
+    best = Math.max(best, scoreCompactCandidate(queryCompact, segment, {
+      exact: 560,
+      prefix: 520,
+      contains: 480,
+      fuzzy: 450,
+    }));
+  }
+
+  return best;
+}
+
+function scoreEntryLexicalBoost(entry, normalizedQuery, rescueTerms = []) {
+  const queryCompacts = [...new Set([
+    compactIdentifier(normalizedQuery),
+    ...rescueTerms.map((term) => compactIdentifier(term)),
+  ])].filter((queryCompact) => queryCompact.length >= 2);
+
+  let best = 0;
+  for (const queryCompact of queryCompacts) {
+    best = Math.max(best, scoreEntryLexicalVariant(entry, queryCompact));
+  }
+  return best;
+}
+
+function getMissingQueryTerms(normalizedQuery) {
+  if (!_searchIndex?.invertedIndex) {
+    return [];
+  }
+
+  return tokenize(normalizedQuery).filter((term) => !_searchIndex.invertedIndex[term]?.length);
+}
+
+function shouldRunGlobalLexicalScan(normalizedQuery, resultByKey) {
+  if (!_searchIndex || resultByKey.size === 0) {
+    return true;
+  }
+
+  if (!_searchIndex.invertedIndex) {
+    return false;
+  }
+
+  const queryTerms = tokenize(normalizedQuery);
+  if (queryTerms.length < 2) {
+    return false;
+  }
+
+  return getMissingQueryTerms(normalizedQuery).length > 0;
+}
+
+function namespaceSearchIndex(index, sourceName) {
+  return {
+    ...index,
+    documents: (index.documents || []).map((doc) => ({
+      ...doc,
+      id: getSearchLookupId(sourceName, doc.id),
+    })),
+  };
+}
+
 /**
  * Load and merge entries from all configured sources.
  * Returns { docs: [...], skills: [...] } with each entry tagged with _source/_sourceObj.
@@ -24,7 +205,7 @@ function getMerged() {
 
     // Load BM25 search index if available
     const idx = loadSearchIndex(source);
-    if (idx) searchIndexes.push(idx);
+    if (idx) searchIndexes.push(namespaceSearchIndex(idx, source.name));
 
     // Support both new format (docs/skills) and old format (entries)
     if (registry.docs) {
@@ -56,47 +237,13 @@ function getMerged() {
   // Merge search indexes (combine documents and recompute IDF)
   if (searchIndexes.length > 0) {
     if (searchIndexes.length === 1) {
-      _searchIndex = searchIndexes[0];
+      const [singleIndex] = searchIndexes;
+      _searchIndex = singleIndex.invertedIndex
+        ? singleIndex
+        : buildIndexFromDocuments(singleIndex.documents, singleIndex.params);
     } else {
-      // Merge multiple indexes: combine documents, recompute global IDF
       const allDocuments = searchIndexes.flatMap((idx) => idx.documents);
-      const N = allDocuments.length;
-      const dfMap = {};
-      const fieldLengths = { name: [], description: [], tags: [] };
-
-      for (const doc of allDocuments) {
-        const allTerms = new Set([
-          ...(doc.tokens.name || []),
-          ...(doc.tokens.description || []),
-          ...(doc.tokens.tags || []),
-        ]);
-        for (const term of allTerms) {
-          dfMap[term] = (dfMap[term] || 0) + 1;
-        }
-        fieldLengths.name.push((doc.tokens.name || []).length);
-        fieldLengths.description.push((doc.tokens.description || []).length);
-        fieldLengths.tags.push((doc.tokens.tags || []).length);
-      }
-
-      const idf = {};
-      for (const [term, df] of Object.entries(dfMap)) {
-        idf[term] = Math.log((N - df + 0.5) / (df + 0.5) + 1);
-      }
-
-      const avg = (arr) => arr.length === 0 ? 0 : arr.reduce((a, b) => a + b, 0) / arr.length;
-      _searchIndex = {
-        version: '1.0.0',
-        algorithm: 'bm25',
-        params: searchIndexes[0].params,
-        totalDocs: N,
-        avgFieldLengths: {
-          name: avg(fieldLengths.name),
-          description: avg(fieldLengths.description),
-          tags: avg(fieldLengths.tags),
-        },
-        idf,
-        documents: allDocuments,
-      };
+      _searchIndex = buildIndexFromDocuments(allDocuments, searchIndexes[0].params);
     }
   }
 
@@ -178,6 +325,7 @@ export function getDisplayId(entry) {
  * Uses BM25 when a search index is available, falls back to keyword matching.
  */
 export function searchEntries(query, filters = {}) {
+  const normalizedQuery = normalizeQuery(query);
   const entries = applySourceFilter(getAllEntries());
 
   // Deduplicate: same id+source appearing as both doc and skill → show once
@@ -194,26 +342,29 @@ export function searchEntries(query, filters = {}) {
   // Build entry lookup by id
   const entryById = new Map();
   for (const entry of deduped) {
-    entryById.set(entry.id, entry);
+    entryById.set(getSearchLookupId(entry._source, entry.id), entry);
+  }
+
+  if (!normalizedQuery) {
+    return applyFilters(deduped, filters).map((entry) => ({ ...entry, _score: 0 }));
   }
 
-  let results;
+  const resultByKey = new Map();
 
   if (_searchIndex) {
     // BM25 search
-    const bm25Results = bm25Search(query, _searchIndex);
-    results = bm25Results
-      .map((r) => {
-        const entry = entryById.get(r.id);
-        return entry ? { entry, score: r.score } : null;
-      })
-      .filter(Boolean);
+    for (const match of bm25Search(normalizedQuery, _searchIndex)) {
+      const entry = entryById.get(match.id);
+      if (!entry) continue;
+      const key = getSearchLookupId(entry._source, entry.id);
+      resultByKey.set(key, { entry, score: match.score });
+    }
   } else {
     // Fallback: keyword matching
-    const q = query.toLowerCase();
+    const q = normalizedQuery.toLowerCase();
     const words = q.split(/\s+/);
 
-    results = deduped.map((entry) => {
+    for (const entry of deduped) {
       let score = 0;
 
       if (entry.id === q) score += 100;
@@ -230,12 +381,35 @@ export function searchEntries(query, filters = {}) {
         if (entry.tags?.some((t) => t.toLowerCase().includes(word))) score += 15;
       }
 
-      return { entry, score };
-    });
+      if (score > 0) {
+        const key = getSearchLookupId(entry._source, entry.id);
+        resultByKey.set(key, { entry, score });
+      }
+    }
+  }
 
-    results = results.filter((r) => r.score > 0);
+  const lexicalCandidates = !shouldRunGlobalLexicalScan(normalizedQuery, resultByKey)
+    ? [...new Set([...resultByKey.values()].map(({ entry }) => entry))]
+    : deduped;
+  const rescueTerms = resultByKey.size > 0
+    ? getMissingQueryTerms(normalizedQuery).filter((term) => term.length >= 5)
+    : [];
+
+  for (const entry of lexicalCandidates) {
+    const boost = scoreEntryLexicalBoost(entry, normalizedQuery, rescueTerms);
+    if (boost === 0) continue;
+
+    const key = getSearchLookupId(entry._source, entry.id);
+    const current = resultByKey.get(key);
+    if (current) {
+      current.score += boost;
+    } else {
+      resultByKey.set(key, { entry, score: boost });
+    }
   }
 
+  let results = [...resultByKey.values()];
+
   const filtered = applyFilters(results.map((r) => r.entry), filters);
   const filteredSet = new Set(filtered);
   results = results.filter((r) => filteredSet.has(r.entry));
@@ -249,6 +423,7 @@ export function searchEntries(query, filters = {}) {
  * type: "doc" or "skill". If null, searches both.
  */
 export function getEntry(idOrNamespacedId, type = null) {
+  const normalizedId = normalizeQuery(idOrNamespacedId);
   const { docs, skills } = getMerged();
   let pool;
   if (type === 'doc') pool = applySourceFilter(docs);
@@ -256,16 +431,16 @@ export function getEntry(idOrNamespacedId, type = null) {
   else pool = applySourceFilter([...docs, ...skills]);
 
   // Check for source:id format (colon separates source from id)
-  if (idOrNamespacedId.includes(':')) {
-    const colonIdx = idOrNamespacedId.indexOf(':');
-    const sourceName = idOrNamespacedId.slice(0, colonIdx);
-    const id = idOrNamespacedId.slice(colonIdx + 1);
+  if (normalizedId.includes(':')) {
+    const colonIdx = normalizedId.indexOf(':');
+    const sourceName = normalizedId.slice(0, colonIdx);
+    const id = normalizedId.slice(colonIdx + 1);
     const entry = pool.find((e) => e._source === sourceName && e.id === id);
     return entry ? { entry, ambiguous: false } : { entry: null, ambiguous: false };
   }
 
   // Bare id (may contain slashes like author/name)
-  const matches = pool.filter((e) => e.id === idOrNamespacedId);
+  const matches = pool.filter((e) => e.id === normalizedId);
   if (matches.length === 0) return { entry: null, ambiguous: false };
   if (matches.length === 1) return { entry: matches[0], ambiguous: false };
 
@@ -317,9 +492,7 @@ export function resolveDocPath(entry, language, version) {
   let langObj = null;
   if (lang) {
     langObj = entry.languages.find((l) => l.language === lang);
-  } else if (entry.languages.length === 1) {
-    langObj = entry.languages[0];
-  } else if (entry.languages.length > 1) {
+  } else {
     return {
       needsLanguage: true,
       available: entry.languages.map((l) => l.language),

package/src/lib/telemetry.js

@@ -8,6 +8,12 @@ export function isTelemetryEnabled() {
   return config.telemetry !== false;
 }
 
+export function isFeedbackEnabled() {
+  if (process.env.CHUB_FEEDBACK === '0' || process.env.CHUB_FEEDBACK === 'false') return false;
+  const config = loadConfig();
+  return config.feedback !== false;
+}
+
 export function getTelemetryUrl() {
   const url = process.env.CHUB_TELEMETRY_URL;
   if (url) return url;
@@ -33,7 +39,7 @@ export function getTelemetryUrl() {
  * @param {string} [opts.source] - Registry source name
  */
 export async function sendFeedback(entryId, entryType, rating, opts = {}) {
-  if (!isTelemetryEnabled()) return { status: 'skipped', reason: 'telemetry_disabled' };
+  if (!isFeedbackEnabled()) return { status: 'skipped', reason: 'feedback_disabled' };
 
   const { getOrCreateClientId, detectAgent, detectAgentVersion } = await import('./identity.js');
   const clientId = await getOrCreateClientId();

package/src/lib/welcome.js

@@ -0,0 +1,42 @@
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getChubDir } from './config.js';
+
+const WELCOME_MARKER = '.welcome_shown';
+
+/**
+ * Show the first-run welcome notice if it hasn't been shown yet.
+ * Creates a marker file so it only displays once.
+ */
+export function showWelcomeIfNeeded(opts = {}) {
+  if (opts.json) return;
+  if (!process.stdout.isTTY || !process.stderr.isTTY) return;
+
+  const chubDir = getChubDir();
+  const markerPath = join(chubDir, WELCOME_MARKER);
+  const configPath = join(chubDir, 'config.yaml');
+
+  if (existsSync(markerPath)) return;
+
+  // Print to stderr so it doesn't interfere with JSON/piped output
+  console.error(`
+${chalk.bold('Welcome to Context Hub (chub)!')} Chub helps your AI coding agents make API calls correctly, by providing \
+the latest documentation.
+
+By using chub, you agree to the Terms of Service at ${chalk.underline('https://www.aichub.org/tos.html')}
+
+Chub asks agents to provide feedback on documentation, and this feedback is used to improve docs for the developer \
+community. If you wish to disable this feedback, add ${chalk.bold('"feedback: false"')} to ${chalk.bold(configPath)}. See \
+${chalk.underline('https://github.com/andrewyng/context-hub')} for details.
+`);
+
+  try {
+    if (!existsSync(chubDir)) {
+      mkdirSync(chubDir, { recursive: true });
+    }
+    writeFileSync(markerPath, new Date().toISOString(), 'utf8');
+  } catch {
+    // Best-effort — don't block CLI if marker can't be written
+  }
+}