* docs: document the plugin marketplace Add a public Plugin Marketplace page covering both audiences: operators using the in-app catalog (Browse/Installed tabs, one-click install, Update to vX, the Sources dialog for team/corporate registries, plugin icons, feature-flag gating, sideloading still works) and plugin authors publishing into it (one-repo-per-plugin GitHub Release assets, the optional manifest icon field, submitting a plugins.yaml PR to the official catalog, GitHub-stars-only ranking, and hosting your own index.json source). Also cross-link the new page from plugins.md (replacing the now-false "No plugin marketplace" security note), plugins-authoring.md, and plugins-manifest.md (new icon field row); register it in meta.json and coverage.json. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: correct plugin-registry CI validation claims The registry index-build workflow does not validate plugins.yaml against schema.json, nor does build-index.mjs compare the entry id to the manifest id — bad entries are skipped-and-logged, and CI only fails when a non-empty list resolves to zero built entries. Reword the submission steps (in both the marketplace docs page and plugin-registry/README.md) to describe what the workflow actually does: it resolves each entry against the GitHub API and requires a correctly named <id>-<version>.tar.gz release asset, with maintainer approval as the real gate. Also clarify that plugins.yaml `categories` are free-form curation tags, not the manifest's category enum. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * ci: split plugin-registry Pages deploy into its own job The single build-and-deploy job bound the `github-pages` environment at the job level, so GitHub evaluated that environment's protection rules on every PR run — failing the check even though the deploy steps were gated to non-PR events. This broke every PR touching plugin-registry/**, which is exactly what a plugin-submission PR does. Split into a PR-safe `build` job (no environment) and a non-PR-gated `deploy` job that owns the `github-pages` environment and runs only `deploy-pages`. Behavior on push/schedule/workflow_call is unchanged; PRs now run build+tests without tripping the environment gate. The star refresh calls this workflow by file path, so the job rename is safe. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: describe index-build asset resolution accurately build-index.mjs picks the <id>-<version>.tar.gz release asset when present but falls back to the release's first .tar.gz otherwise, and only errors when a release has no .tar.gz at all — it does not hard-fail a misnamed asset. Reword the submission steps to present the exact asset name as an authoring instruction (so the index resolves the right asset) rather than a builder-enforced gate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Revert "ci: split plugin-registry Pages deploy into its own job" This reverts commit2c5f649146. * Reapply "ci: split plugin-registry Pages deploy into its own job" This reverts commit3795cdb98a. --------- Co-authored-by: Kandev Agent <agent@kandev.dev> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
9.0 KiB
title, description, status
| title | description | status |
|---|---|---|
| Plugin Marketplace | Discover and install kandev plugins from the in-app catalog, keep them updated, add a team or corporate source, and publish your own plugin to the official catalog. | experimental |
Plugin Marketplace
The marketplace is a discoverable, curated catalog of kandev plugins you can browse and install from inside the app — no tarball URL required. It is assembled from one or more sources: kandev ships with the official source enabled by default, and you can add team or corporate sources alongside it.
This page covers using the marketplace (browse, install, update, add sources) and publishing a plugin into it. For what plugins are and how the install pipeline, enable/disable, and security posture work, see Plugins. For building one, see Authoring a plugin.
Like the rest of plugins, the marketplace is gated behind the plugins feature
flag (Settings > System > Feature Toggles) — off by default in production,
on by default in dev/e2e builds. Enabling it requires a backend restart and
surfaces Settings > Plugins in the sidebar.
Sideloading still works. The marketplace only adds discovery. Installing a plugin by URL or by uploading a
.tar.gzis unchanged and always available, even with every source disabled or offline — see Plugins → Installing a plugin.
Using the marketplace
Settings > Plugins has two tabs:
- Installed — the plugins on this instance, with Enable / Disable / Uninstall and an Update button when a newer version is available.
- Browse — the merged catalog across all enabled sources.
Browse and install
Open Settings > Plugins > Browse. Each plugin shows as a card with its name, description, author, categories, source repository link, latest version, and GitHub star count. To narrow the list:
- Search — type in the search box to match plugin name or description.
- Category — filter to a single category with the category dropdown.
- Sort — Most stars (default), Recently updated (by latest release / repo activity), or Name.
Stars are a sort hint, not a quality score. kandev collects no download or usage telemetry, so there is no "most installed" metric — ranking is GitHub stars only, and "Recently updated" surfaces new or actively maintained plugins that high-star incumbents would otherwise bury.
Click Install on a card to install it. This resolves the entry to its
latest release tarball and runs the same verified install pipeline as
install-by-URL (POST /api/plugins/install) — see Plugins → Installing a
plugin for the exact steps and integrity
checks. A card for a plugin you already have at the latest version shows
Installed instead of an install button.
Plugin-provided icons render on the cards. A plugin that ships an icon (via the
manifest's icon field) shows it; otherwise the card falls back to a neutral
letter tile.
Keep plugins updated
When the marketplace advertises a newer version than the one you have
installed, the Installed tab shows an Update to v<version> button on
that plugin's row. Clicking it reinstalls the newer tarball through the normal
pipeline; Enable, Disable, and Uninstall are unchanged.
Updates are never automatic — kandev surfaces the newer version and waits for an explicit click. There are no update channels and no background auto-update.
Add a team or corporate source
The Sources button on the Browse tab opens the Marketplace sources dialog. The official kandev source is present by default, badged Official, and cannot be removed. To add another:
- Click Sources.
- Enter a name (e.g.
Acme Internal) and the URL of anindex.jsondocument (see Host your own source below). - Click Add.
Its plugins are then merged into the Browse tab alongside the official ones.
You can enable/disable a source without deleting it, and remove any non-official
source. Adding a source is an explicit act of trust in its maintainer, much
like brew tap-ing a third-party tap.
Notes:
- When the same plugin
idappears in more than one source, the first configured source wins (the official source is always first); later duplicates are hidden. - A source that is unreachable or serves malformed JSON is reported as degraded — its entries are omitted, but the healthy sources still load.
- Configured sources persist across restarts; the fetched catalog itself is a short-lived cache and is re-fetched on demand.
Publishing a plugin
Getting a plugin into the catalog follows a one-repo-per-plugin model, mirroring Obsidian's community-plugin registry: each plugin lives in its own public GitHub repository and publishes its package as a GitHub Release asset; the official catalog is a curated pointer list that names which repos are included. The descriptive metadata (name, description, version, tarball URL, stars) is always read from your latest release, so a listing can never drift from what actually ships.
1. Publish the plugin package as a release
Package your plugin as usual (see Authoring a plugin → Packaging) and cut a GitHub Release whose assets include both:
<id>-<version>.tar.gz— the plugin package, andchecksums.txt— the integrity manifest the install pipeline verifies.
The release must pass the standard package integrity gate. The
kdlbs/kandev-plugin-template starter repo is the recommended way to bootstrap
a repo with the right layout and a release workflow.
2. Add an icon (optional)
Add an icon: field to your manifest.yaml — a package-relative path to an
image your package ships (for example icon.svg). The catalog resolves it to
your icon and renders it on the plugin card; without it, the card shows a letter
tile. See the Plugin manifest reference.
3. Submit to the official catalog
The official source is curated: a plugin appears only after a maintainer merges a PR that lists it.
-
Fork
kdlbs/kandevand add one entry toplugin-registry/plugins.yamlpointing at your public repo:plugins: - id: my-plugin # MUST equal the `id` in your plugin manifest repo: your-org/your-plugin-repo # owner/name categories: [productivity] # optionalKeep
idequal to your manifestidand unique in the file, and name your release package<id>-<version>.tar.gzto match, so the index resolves the right asset.categorieshere are free-form curation tags for catalog filtering (not the manifest's category enum).featuredis a maintainer-only pin — leave it out of submissions. The pointer-list shape is defined byplugin-registry/schema.json. -
Open a pull request. The registry index-build workflow runs on your PR (build + tests, no Pages deploy), resolving your entry against the GitHub API — your repo must have a latest release that publishes a
.tar.gzpackage and itschecksums.txt. An entry whose repo has no release or no package asset is skipped. -
A maintainer reviews and merges — maintainer approval is what gates the official catalog. The index-build workflow then picks up your entry and your plugin appears in the in-app catalog on the next build.
Ranking in the catalog is GitHub stars only — there is no download or usage
telemetry to game. Full submission details are in
plugin-registry/README.md.
Host your own source
You do not have to PR into the official registry to share plugins internally.
Any URL that serves an index.json document of the catalog shape can be added
as a marketplace source (see Add a team or corporate
source), and its plugins merge into the Browse
tab alongside the official ones. This is the recommended path for a team or
corporate registry — no PR to the main repo.
The index.json document is the fetch contract between a source and kandev. The
simplest way to produce one is to copy the official registry's
plugin-registry/ directory into your own repo — its plugins.yaml +
build-index.mjs
build script (zero-dependency Node) + GitHub Action resolve each listed repo's
latest release into a full catalog record and publish the generated
index.json to GitHub Pages. Point kandev at that Pages URL. The document
shape, the build pipeline, and the source data model are specified in the
plugin marketplace spec.
Related: Plugins, Authoring a plugin, Plugin manifest reference.