Skip to main content

Context Hub registry management

Use when maintaining Context Hub (chub) or its registry. Operating and maintaining the chub CLI, its private registry, and the freshness watchdog. Context Hub is a second-tier documentation source: Context7 remains the mandatory primary gate (see context7-mcp).

When to Use​

  • Installing, upgrading, or repairing the chub CLI.
  • Adding or editing docs in the private registry, or after cloning it on a new host.
  • A chub search returns only community results, or a private doc will not fetch.
  • Building or changing the Context Hub freshness watchdog or its schedule.
  • Making Context Hub reachable from worker or cron processes.

Three independent staleness surfaces​

Do not conflate them; each fails differently and each needs its own check.

  1. CLI package — @aisuite/chub in node_modules. Drifts when a new version publishes. Report, never auto-upgrade: the pin is deliberate.
  2. Community source — cached remote registry under ~/.chub/sources/community. Refreshed by chub update. Safe to auto-repair; it is cache-only and mutates no config.
  3. Private source — the internal registry's dist/, which is a gitignored build artifact. It is not restored by git clone or git pull. Rebuild it from content/ whenever content is newer or dist/ is absent.

The third is the one that silently breaks. A clean checkout of the registry repo yields a working tree with no dist/, so chub finds the private source path but serves nothing, and searches quietly return only community results.

Install so it survives​

Install pinned and declared in a real manifest:

npm install --save --save-exact @aisuite/chub@<version>

A bare npm install <pkg> into a directory whose package.json does not declare it leaves the package prunable: the next unrelated npm install removes it and leaves node_modules/.bin/chub as a dangling symlink. The symlink surviving its target is the signature of this failure — ls .bin looks fine while every invocation reports No such file or directory.

Hermes worker processes launch with env -i and a fixed PATH that does not include /root/node_modules/.bin. Symlink into a directory that is on the worker PATH, and treat those links as load-bearing:

ln -sf /root/node_modules/@aisuite/chub/bin/chub     ~/.local/bin/chub
ln -sf /root/node_modules/@aisuite/chub/bin/chub-mcp ~/.local/bin/chub-mcp

Verify under the real worker environment, not your interactive shell:

env -i HOME=/root PATH=<exact worker PATH> bash -lc 'chub search "<topic>"'

An interactive-shell success proves nothing about worker reachability.

CLI usage notes​

  • --lang is required for docs. Without it, chub get <id> errors with "Multiple languages available" even when only one language exists.
  • chub sources is not a command; use chub cache status.
  • chub --version is not supported; chub --help prints the version banner.
  • Source of each hit is shown in parentheses; source: prefix disambiguates colliding ids (chub get xcentric:openai/chat).

Privacy is a standing precondition​

~/.chub/config.yaml must keep telemetry: false and feedback: false. Never run chub feedback (transmits upstream) or chub annotate when feedback is disabled. Assert both keys in the watchdog — a config rewrite that drops them is silent.

Private registry repo shape​

  • content/<author>/docs|skills/<name>/[lang/]DOC.md — source of truth, committed
  • dist/ — built by chub build content --output dist, gitignored
  • scripts/validate.mjs — pre-build gate
  • npm run check = validate + build

The validator should enforce required frontmatter, ROLES-ONLY (no hardcoded model ids), no credential-shaped strings, and directory layout. Counter-examples that teach a rule need an exemption marker so // WRONG snippets do not trip the model-id guard.

Watchdog pattern​

~/.hermes/scripts/check-chub.py, scheduled --no-agent so empty stdout is silent. Classify every finding into one of three buckets and keep them distinct in the output:

  • FAILED — broken, needs a human. Exit 1.
  • ACTION AVAILABLE — e.g. a newer CLI published. Exit 0; never auto-apply.
  • REPAIRED — what it fixed itself (cache refresh, dist/ rebuild). Exit 0.

Auto-repair only cache and build artifacts. Git state is read-only: report HEAD/origin divergence and uncommitted content, never pull or push. A watchdog that pushes turns a stale-doc warning into an unreviewed commit.

Include a canary retrieval of a known private doc. Path existence and a non-empty dist/ both pass while the registry serves nothing; only an actual chub get returning expected content proves the source works.

Verify a watchdog by breaking things​

A watchdog that has only ever returned green is untested. Before scheduling, induce each failure mode and confirm detection, then confirm it returns silent:

  • delete dist/ → expect REPAIRED rebuild
  • flip telemetry: true → expect FAILED
  • dirty a content file → expect FAILED uncommitted report
  • downgrade the installed version in its package.json → expect ACTION AVAILABLE
  • move the ~/.local/bin symlink aside → expect FAILED worker-reachability

Restore state after each and re-run to confirm exit 0 and empty stdout.

Pitfalls​

  • Gitignored dist/: cloning the registry on a new host gives a private source that resolves but serves nothing. Always npm run check after clone.
  • Prunable install: undeclared packages vanish on the next npm install.
  • Interactive-PATH illusion: chub on your PATH says nothing about workers.
  • Silent language error: a missing --lang looks like a missing doc.
  • Feedback leak: chub feedback is a network write, not a local rating.
  • MCP server: register chub-mcp disabled by default so Context7 stays the primary gate; verify it with a stdio initialize handshake before enabling.

Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/context-hub-registry-management/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Agent · license MIT.

Published by Muse · 2026-10-04.