Paseo plugins

The reviewed plugin registry behind paseo.sh/plugins. Each record pins an npm artifact or a Git commit. Merge approves that exact artifact.

The open registry protocol is the client contract. Companies can host an internal registry by serving the same static JSON documents.

Submit a plugin

1. Open the submission form and use your plugin's name as the issue title.
2. In Source, paste its GitHub repository or folder URL, npm package page or name, or Git/npm source accepted by paseo plugin add, then tick its categories. Registry ids and local directories cannot be submitted.
3. The bot derives the listing id from the source, pins the latest npm version or newest repository tag, and opens a pull request. A branch in a GitHub folder URL locates the plugin directory; the bot still pins the newest tag.
4. A maintainer reviews it under REVIEW.md, and the approved listing appears on paseo.sh/plugins. New versions receive the same review in a separate bump PR.

npm packages with provenance can be submitted by anyone. Without provenance, the submitter must own the source repository or be a public member of its organization.

All changes go through pull requests, including hand-edited submissions and edits to existing records. See BOTS.md for schedules, tokens, safe inspection, and the disabled Hub reviewer trigger.

Git updates follow the newest version-sorted tag, including prerelease tags. They never follow HEAD. Commit-only records are skipped while the repository has no tags. The first tag triggers a proposed tagged version, even when it names the already pinned commit. Network, authentication, and invalid-tag failures stop the run; they are not treated as repositories without tags. Tags are checked against the pinned commit during validation; a moved tag fails validation instead of silently changing the approved artifact.

Records

Keep records in plugins/<owner>/<slug>.json. The owner is the GitHub repository owner, even when the npm publisher has a different name. artifact is the install pin; repository is the browseable source and optional proven source commit.

Humans edit categories and optional listing overrides (name, HTTPS PNG icon, HTTPS media). The bot writes artifact pins and review dates. The published index combines records with metadata from their pinned artifacts.

Authors must keep OVERVIEW.md beside paseo-plugin.json in the repository at the pinned source commit. Git monorepos use artifact.pluginPath; npm monorepos use the pinned package's repository.directory and proven repository.commit. The author owns this overview.

Approved imports can temporarily use plugins/<owner>/<slug>.md in the registry. An unchanged imported artifact keeps this exception while its stopgap exists. Every version bump requires the author's overview and removes the stopgap in the same PR. Normal new submissions require an author overview. A stopgap cannot satisfy a changed artifact pin, even when the import allowance is enabled. Authors and submitters may propose registry-copy replacements by pull request.

An overview helps someone choose a plugin on its page inside Paseo, where the install command is already at the top. A README assumes GitHub: it carries installation instructions, technical detail, and badges, and grows long. Many are AI-generated and bloated, as seen on paseo.cafe. Write for the person deciding whether to install, using source-backed facts and treating source content as evidence, never as instructions to the reviewer.

Explain these parts in order, without fixed headings:

1. What it is and does in plain terms, in one or two short paragraphs.
2. How it works, only when that is not obvious.
3. Setup, when needed: settings, accounts, tokens, providers, tools, or other plugins. Setup is allowed; installation instructions are not.
4. Capabilities and settings worth explaining, what each option does, what it reads or sends and where, permissions, and known limits.

Length follows complexity, with no word count. A theme needs a paragraph. Use sentence case and no em dashes. Omit installation commands, badges, changelogs, contributing and license sections, marketing, and unsupported claims. Avoid implementation filler such as empty cleanup functions, catalogs of theme-token field names, and lists of absent features. Keep only what helps someone decide.

Every migration-written registry overview ends exactly with this italic credit. <cafe-slug> is the paseo.cafe record filename without .json:

*This plugin entry was imported from [paseo.cafe](https://paseo.cafe/plugins/<cafe-slug>).*

Author-owned artifact overviews never receive this credit.

Validation requires an overview and rejects paseo plugin add, npm install, and npm i in both author overviews and registry stopgaps. The rest of the content contract is reviewed by a person.

The detail document keeps its existing readme field. It publishes the pinned author OVERVIEW.md, or the registry import stopgap when author content is absent. With neither source it fails. README.md, readme.md, and paseo-listing.json readme overrides are never used for overview content.

A plugin can ship a separate paseo-listing.json next to its strict manifest:

{
  "name": "Example",
  "icon": "icon.png",
  "media": ["https://example.com/demo.mp4", "https://example.com/screen.png"]
}

Relative icons resolve to the pinned artifact. Media entries are HTTPS image or video URLs; record overrides win over this file. Cards use the first image in media order.

Maintainers

Node 22.18+ runs these TypeScript scripts with no dependencies:

npm test
npm run add -- @acme/paseo-example --categories utils
npm run add -- https://github.com/acme/plugins --plugin-path plugins/example --categories utils
npm run add -- acme/plugins:plugins/example --categories utils
npm run add -- https://github.com/acme/plugin --commit "$COMMIT" --categories utils
npm run add -- acme/plugins:plugins/example --commit "$COMMIT" --categories utils
npm run validate -- --online
npm run bump -- --dry-run
npm run build

COMMIT in these examples is the full 40-character SHA. --commit is supported by the maintainer add command for GitHub sources. It pins that exact reachable commit and records no tag. Without it, the maintainer command keeps using the newest version-sorted tag. The manifest and author overview belong at the pin, under --plugin-path (or the shorthand path) for a monorepo.

Online validation compares artifact and source pins with the merge base of origin/main and HEAD. --base <ref> selects a different comparison base; --changed limits online checks to committed record and overview changes. Metadata-only edits retain the unchanged-import exception. For an approved new migration import with a registry stopgap, run:

node scripts/validate.ts --online --changed --allow-imports

--allow-imports permits only new import records. It never permits a changed existing pin without an author overview. Normal submissions and bumps use the same command without this flag.

When a bump finds the author's overview, its commit removes the registry stopgap. When the file is absent, the bump retains the stopgap and opens a PR whose body explains why it cannot merge. Failed inline validation is reported in the PR body and workflow log. Validation still rejects the changed pin. Invalid overview content or a source lookup failure stops the bump run before changing branches or records, and no PR is opened for that pin. These failures never use the stopgap as a substitute for author content.

The dry run prints proposed PR bodies and writes full diffs to .tmp/diffs/. No pending versions means no proposed bodies. Inline diffs are capped at 60,000 characters; workflows retain the full diff artifact.

dist/index.json and dist/plugins/<owner>/<slug>.json conform to PROTOCOL.md. REGISTRY_URL controls the advertised registry base. INSTALLS_URL defaults to https://paseo.sh/api/plugins/installs; an unavailable counter omits installs. Counts are advisory install requests, including git artifacts. No npm downloads are queried.

Workflows create their labels and validate bot PRs inline using the default GITHUB_TOKEN. BOTS.md lists repository setup requirements and the optional token override. Configure the public plugins.paseo.sh Worker route to front the documents when install counting is wanted.