The manifest, plugin.json

plugin.json is the first thing a reviewer reads and the only thing the Server trusts: your fetcher cannot reach a host you did not declare, nor write a series you did not name. Add "$schema": "https://kanboombo.com/developers/plugins/plugin.schema.json" and your editor completes and checks it as you type. Unknown keys are refused at every level, except $schema: a misspelt fieldnames fails with PLG-MANIFEST-UNKNOWN-KEY instead of being quietly dropped.

Decide it in this order

Who it is. id is 2 to 48 lowercase letters, digits and hyphens, starting with a letter: your folder's name, part of lasting addresses (kanboombo://plugins/<id>), never reused, so make it plain and lasting. name is per language; version is major.minor.patch.

When it runs. timezone, a named IANA zone, never an offset (Dates); schedule, a five-field cron in it, at most 24 runs a day; backfill, how far back the first run fills: all, or a span such as 90d.

Who may read it. audience is public, private or local: Audiences.

What it downloads. At most 16 sources, each a lowercase name used once and an https url with a lowercase host. Set maxBytes, at most 20 MB, close to what you see: a far larger file is more likely an error page than news.

What it writes. 1 to 64 series, each one kind of record:

cadence tells readers what to expect and schedules nothing. links.hosts lists hosts items may link to besides your sources'; limits may lower seconds and megabytes, never raise them. licence says whose data it is: Data rights.

Mistakes the check catches

check reports the first problem of each part, with its code, so most are fixed in one pass. An offset is not a time zone:

An http source fails with PLG-MANIFEST-SOURCE-URL; an id with capitals or an underscore with PLG-MANIFEST-ID.

Every field

PluginManifest

plugin.json: what your plug-in downloads, what it writes, when it runs and who may read it. Unknown keys are refused.

PluginSource

One file Kanboombo downloads before each run and hands to your fetcher. https only; the host refuses private addresses and redirects to hosts no source names. {today}, {year} and {month} are filled in the manifest's time zone.

PluginSeries

One kind of record your plug-in writes, and how readers see it.

PluginSnapshot

Each run's batch is the whole truth for this window. A stored record inside it that is missing from three runs in a row is withdrawn.

PluginLinks

The hosts an item record may link to, besides every source's host.

PluginLimits

Lower limits than the defaults, if your fetcher needs less. They can never be raised.

PluginLicence

Who holds the data and what you may do with it. Readers see the attribution beside every record.

PluginId

A plug-in's id: lowercase letters, digits and hyphens, starting with a letter, 2 to 48 characters. It is also its folder's name, and it is never reused.

• •
  Type: string
• •
  Pattern: ^[a-z][a-z0-9-]{1,47}$
• •
  Example: dop-economy

PluginKey

A key for a source, a series or a field: lowercase letters, digits, hyphens and underscores, starting with a letter.

• •
  Type: string
• •
  Pattern: ^[a-z][a-z0-9_-]{0,47}$
• •
  Example: usd-dop, compra

PluginNames

A name in each language the plug-in speaks, keyed by language code. A reader sees their own language, then en, then the first listed.

• •
  Type: object of string

PluginAudience

public: anyone signed in, and a Mac's proxy. private: the readers set at host.kanboombo.com (people and organizations). local: runs on your Mac only; refused by the Server until its slice ships.

• •
  Type: "public", "private", "local"

PluginCadence

How often the series has a new record. It tells readers what to expect; it does not schedule anything.

• •
  Type: "business-day", "daily", "weekly", "monthly", "quarterly", "irregular"

PluginRecordKind

value: numbers on a date. event: something scheduled, happened or cancelled. item: a dated link with a title.

• •
  Type: "value", "event", "item"

PluginDates

observation: a record's date is the day it describes. publication: the day it was published, with period naming what it describes.

• •
  Type: "observation", "publication"

PluginWindow

A span relative to the run's today: a number and a unit, d for days or y for years.

• •
  Type: string
• •
  Pattern: ^[0-9]{1,4}[dy]$
• •
  Example: 60d, 400d, 5y

Limits

The checker's numbers, the same in check and on the Server:

What the Server holds a run to

Contract 1 and its changes

Contract 1 only grows: a field, a stated limit or a check with its own code may be added, and nothing a plug-in relies on is taken away or changes meaning. A change that would break a working plug-in is contract 2, run beside contract 1. A check code is never renamed or reused; a retired one stays in Submission errors.

October 2026. Contract 1, with DOP Economy on readers' days. Added the same week, changing nothing DOP Economy writes nor its digest: $schema (plugin.schema.json); links.hosts; backfillFrom in the run context; fixtures/context.json and fixtures/runs/<case>/; the digest leaving out listing.json, listing/, review.json, .git/, .DS_Store, AGENTS.md and CLAUDE.md; and a code from one catalog, with its fix and page, on every problem. The tool's versions are in the CLI.