Quartz 4

SKILL

2 min read

Messaging Vendor KB Refresh

Purpose

Keeps the vendor knowledge-base directories under workspace/knowledge-base/<vendor>/ in sync with each vendor’s published docs. Detects non-trivial changes via git diff and alerts Discord ops so operators review schema drift before it breaks production handlers.

Without this skill, KB docs decay silently as vendors update APIs, and handler bugs surface only at send time.

When to use

  • Automatically via systemd timer messaging-vendor-kb-refresh.timer (weekly, Mon 03:00 America/Los_Angeles)
  • Manually when a vendor announces an API breaking change
  • After Phase 0A initial KB scaffolding to pull real content
  • Before a Phase 1 smoke test to ensure current schema reference

Do NOT use for:

  • First-time onboarding (use download-vendor-kb.sh directly with vendor-specific targets)
  • Pulling docs that require authentication (the wrapper only fetches public URLs)

Inputs

FlagTypeRequiredDescription
--allboolnoRefresh every vendor with an entry in messaging_providers
--vendor=<name>stringnoRefresh only one vendor
--since=<duration>stringno (default 7d)Force refetch of files older than this window
--quietboolnoSuppress per-file stdout; only emit diff summary

Outputs

  • Updated markdown files under workspace/knowledge-base/<vendor>/*.md
  • workspace/knowledge-base/<vendor>/.last_downloaded with ISO timestamp
  • Git commit (if workspace is git-tracked): refresh: vendor KB <date>
  • Discord #ops alert via DISCORD_OPS_WEBHOOK if cumulative git diff is >10 lines across any vendor
  • Stdout summary: per-vendor file-count delta + total lines changed

Acceptance tests

  1. Script completes in under 60 seconds per vendor
  2. If a remote URL returns 404 or timeout, the stale local copy is preserved and a warning is raised (not an error)
  3. Git commit created only when actual content changes exist
  4. Discord alert fires ONLY when diff >10 lines (first-run downloads are not considered “changes”)
  5. Running twice in succession produces no new git commit (idempotent)
  6. .last_downloaded is updated on every successful fetch

Rollback behavior

  • If a refresh introduces malformed docs, revert via git reset --hard HEAD~1 on the workspace
  • If Discord alerting misfires, mute the webhook url temporarily by setting DISCORD_OPS_WEBHOOK= empty in master.env and re-run with --quiet
  • For persistent parser failures against a vendor’s docs, add that vendor’s KB dir to the skip list in tools/messaging-vendor-kb-refresh.js and open an issue to fix the fetcher
  • Plan section: Section G.2 in /home/opsadmin/.claude/plans/put-you-full-last-functional-sparrow.md
  • Implementation: /home/opsadmin/.openclaw/tools/messaging-vendor-kb-refresh.js
  • Wrapped tool: /home/opsadmin/.openclaw/tools/download-vendor-kb.sh
  • Systemd unit: ~/.config/systemd/user/messaging-vendor-kb-refresh.{timer,service}
  • Alert destination: DISCORD_OPS_WEBHOOK (master.env)

Graph View

Backlinks