Push, don't pull

• You push suggestions into the coordinator as context changes.
• The host picks one per cadence tick, scoring by urgency minus plugin/category cooldowns, filtering anything recently shown.
• High urgency preempts. A suggestion with urgency ≥ 80 fires immediately, bypassing the tick.
• Expired suggestions self-prune. Default TTL is 5 minutes, configurable per suggestion.
• Stable ids replace in place. Re-submitting with an existing id overwrites the prior entry — the natural way to keep state-tracked quips in sync.

Declare the quips capability (informational only) and call suggest() from wherever your context updates.

function onLoad() {
  petty.schedule.interval("hydrate-push", 300000, pushHydrate);
  pushHydrate();
}

function pushHydrate() {
  petty.quips.suggest("Did you remember to hydrate?", {
    category: "wellness:hydrate",
    urgency: 5,
    expiresIn: 1800
  });
}

When your plugin's state changes, re-submit with the same id and the coordinator replaces the previous entry. When the state goes away, retract() the id.

function poll() {
  var dirty = checkGitDirty();
  if (dirty > 0) {
    petty.quips.suggest("You have " + dirty + " uncommitted files.", {
      id: "git-dirty",
      urgency: 15,
      category: "git:dirty",
      expiresIn: 600
    });
  } else {
    petty.quips.retract("git-dirty");
  }
}

When you pull a fresh batch from the network, clear() the previous batch and push the new one. Per-plugin scope means you only affect your own suggestions.

function onQuotesFetched(quotes) {
  petty.quips.clear();
  for (var i = 0; i < quotes.length; i++) {
    petty.quips.suggest(quotes[i], {
      id: "quote-" + i,
      category: "flavor:quote",
      urgency: 5
    });
  }
}