docs(plugins): trim publishing guidance to author tasks

public-docs/cli.md

@@ -228,11 +228,12 @@ The output includes each script's lifecycle and supervised terminal ID. Services
 Create and manage trusted plugins on a daemon:
 
 ```bash
-paseo plugin init /absolute/path/to/plugin
-paseo plugin install /absolute/path/to/plugin
-paseo plugin add owner/repository
+paseo plugin init ./plugin
+paseo plugin install ./plugin
+paseo plugin add owner/slug
+paseo plugin add git:owner/repository
 paseo plugin add https://gitlab.com/group/repository.git --ref main
-paseo plugin add owner/monorepo:plugins/review
+paseo plugin add git:owner/monorepo:plugins/review
 paseo plugin ls [id]
 paseo plugin update my-plugin
 paseo plugin update --all
@@ -243,8 +244,10 @@ paseo plugin enable my-plugin
 paseo plugin remove my-plugin
 ```
 
-GitHub shorthand checks an existing host directory first. Append `:<directory>` for a plugin in a
-monorepo. `paseo plugin ls [id]` does not contact the remote. `paseo plugin logs <id>` returns the
+Bare `owner/slug` installs a reviewed registry listing. Use `git:owner/repository` for GitHub
+source, or `./plugin` for a local directory. Append `:<directory>` for a plugin in a monorepo.
+
+`paseo plugin ls [id]` does not contact the remote. `paseo plugin logs <id>` returns the
 plugin's recent daemon-side stdout and stderr. Add `--json` for structured entries, or run
 `paseo --host <target> plugin logs <id>` for another daemon. See the
 [Plugin reference](/docs/plugins/reference) for installation, trust, lifecycle, and log-retention

public-docs/community.md

@@ -10,12 +10,11 @@ category: Getting started
 
 These projects are related to Paseo and built by the community.
 
-## Plugin directory
+## Plugins
 
-[paseo.cafe](https://paseo.cafe) is a community-run directory of Paseo plugins. Listings are generated
-from each plugin's public repository, so it is the fastest way to see what people are building and to
-publish your own. It is independent of the Paseo project and nothing on it is reviewed or endorsed by
-us, so read a plugin's source before installing it.
+Browse the [plugin registry](/plugins) for reviewed community plugins. To share your own, follow
+[Publish a plugin](/docs/plugins/publishing) for package preparation and submission.
+Plugins run unsandboxed; read their listing and source before installing.
 
 ## Tools and integrations
 

public-docs/plugins/publishing.md

@@ -1,6 +1,6 @@
 ---
 title: Publish a plugin
-description: Share a Paseo plugin on npm, through a private registry, or from a Git repository.
+description: Prepare, publish and submit a Paseo plugin to the reviewed registry.
 nav: Publishing
 order: 45
 category: Plugins
@@ -8,111 +8,241 @@ category: Plugins
 
 # Publish a plugin
 
-Publish your plugin so other people can install and use it in Paseo. Start with a working
-[plugin project](/docs/plugins), then choose where to share it:
+Start with a working [plugin project](/docs/plugins). Prepare its listing, publish it on npm
+or push it to GitHub, then submit it to the registry. After approval, users install the reviewed
+version with `paseo plugin add owner/slug`.
 
-- [Plugin registry](#plugin-registry): share a reviewed artifact users install by `owner/slug`.
-- [npm](#publish-on-npm): publish a package on the public npm registry.
-- [GitHub or Git](#share-through-github-or-git): let users install from a repository.
+1. Prepare your [listing page](#your-listing-page) and, for a visual plugin, an
+   [interface image](#icons-and-screenshots).
+2. [Publish on npm](#publish-on-npm) or [share through Git](#share-through-github-or-git).
+3. [Submit to the plugin registry](#plugin-registry).
+
+For a private plugin, use [direct Git installation](#share-through-github-or-git) or
+[private npm packages](#private-npm-packages).
+
+## Your listing page
+
+You can submit without `OVERVIEW.md`; the reviewer creates a listing page from your README and
+verified behavior. To maintain the page yourself, put `OVERVIEW.md` beside `paseo-plugin.json`
+and include it in the published package. The scaffold already includes it in `files`.
+Your shipped overview replaces the reviewer-written page.
+
+Explain these points in order, using headings only when they help:
+
+1. What the plugin does.
+2. How it works, when that is not obvious.
+3. Setup: settings, accounts, tokens, external tools, supported operating systems and Paseo versions.
+4. Useful capabilities, settings, data access, permissions and limitations.
+
+Describe where data goes, including prompts and tool results sent to agent providers. Local storage
+does not mean data stays on the host. If the plugin downloads or installs software while running,
+explain what it installs and its source, and require explicit user confirmation before the download.
+This applies to activation and connection tests too; declining must leave the software uninstalled.
+
+Use plain factual language and sentence case. Omit marketing, unsupported claims, badges,
+changelogs, contributing and license sections, and implementation details that do not help someone
+choose the plugin. The listing already provides plugin installation instructions.
+
+The publication validator rejects `paseo plugin add`, `npm install` and `npm i` anywhere in an
+overview, including development or setup examples. Link to your README for those commands.
+
+Also supply a one-sentence description: use `package.json`'s `description` for npm or the manifest's
+`description` for Git. The reviewer can fill in a missing description in the registry.
+
+## Icons and screenshots
+
+Themes, panels and other visual plugin interfaces need at least one image showing the current
+interface. Use sample data and hide private details. An icon alone does not meet this requirement;
+plugins without their own visual interface do not need screenshots.
+
+Declare local images in `paseo-plugin.json` before publishing:
+
+```json
+{
+  "id": "review-tools",
+  "name": "Review tools",
+  "description": "Reviews changes before merge",
+  "icon": "assets/icon.png",
+  "media": ["assets/screenshot.png"],
+  "requirements": { "paseo": ">=0.11.0" }
+}
+```
+
+Create the referenced files and include `assets/` in `package.json`'s `files` list for npm.
+Paths are relative to the manifest, use forward slashes and stay inside the plugin directory.
+These metadata fields require Paseo 0.11.0 or later.
+
+| Field   | Listing behavior                                                                                                                                                    |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`  | Optional display name; defaults to a humanized plugin ID.                                                                                                           |
+| `icon`  | Optional package-relative PNG. Provider registration icons have a separate [SVG contract](/docs/plugins/reference#providers).                                       |
+| `media` | Package-relative paths or public HTTPS URLs. Images: PNG, JPG, JPEG, WebP or GIF. Videos: MP4 or WebM. The first image is the card thumbnail; videos supplement it. |
+
+Public media URLs need a supported file extension, matched case-insensitively, and must return
+HTTP 200 with the corresponding image or video content type. SVG and extensionless attachment
+URLs are not accepted as registry media.
+
+Instead of declaring `media`, you can supply suitable public image URLs in the submission or
+review PR. The reviewer can add them to the listing without a new plugin release.
+
+## Publish on npm
+
+### 1. Set package identity
+
+Use an npm scope you can publish to and authenticate with `npm login`. From your plugin directory,
+replace `@acme` and the repository below with your own values:
+
+```bash
+npm pkg set name=@acme/paseo-review version=1.0.0
+npm pkg delete private
+npm pkg set repository.type=git repository.url=git+https://github.com/acme/paseo-review.git
+```
+
+The current registry tooling requires a GitHub repository for npm listing ownership, supplied
+through `package.json` or npm provenance. Set `repository` to your public source repository so
+pinning can determine the listing owner. Provenance itself is optional; if present, its repository
+must match the package's repository. A matching source checkout is not required for artifact review.
+
+### 2. Lock installed dependencies
+
+Keep Paseo's host libraries and type-only dependencies in `devDependencies`. Add other runtime
+libraries to `dependencies`. For registry submission, every installed dependency tree needs a lock
+with exact versions, resolved sources and integrity, including transitive dependencies.
+
+For an npm package with installed runtime dependencies, update its lock without running lifecycle
+scripts, then create the publishable lock:
+
+```bash
+npm install --package-lock-only --ignore-scripts
+npm shrinkwrap
+```
+
+`npm shrinkwrap` converts `package-lock.json` into `npm-shrinkwrap.json`. npm publishes the shrinkwrap
+at the package root; it does not publish `package-lock.json`. A repository-only lock or exact direct
+version does not lock the dependency tree installed by your users.
+
+Plugins using only host libraries and development dependencies need no runtime lock unless a
+preparation command installs those dependencies. You can also bundle a library and remove the
+runtime dependency declaration. See [preparation and additional setup](#plugins-with-a-build-step)
+if your plugin installs a separate tree.
+
+### 3. Check the package and publish
+
+Generate any required files before checking the package; the dry run skips packing scripts.
+
+```bash
+npm run typecheck
+npm pack --dry-run --ignore-scripts
+```
+
+Check the file list contains `paseo-plugin.json`, at least one runtime entry, every imported local
+module, any overview and assets you declared, and the shrinkwrap when required. Repository-only import aliases
+and files outside the package do not reach users. The scaffold includes the entries and `client/`,
+`server/` and `shared/`; add other asset directories to `files`.
+
+Confirm any declared preparation command succeeds with the Node/npm versions you support;
+an out-of-sync or incompatible lockfile still blocks installation.
+
+Publish the checked version:
+
+```bash
+npm publish --access public
+```
+
+On a test daemon, install that exact published version and exercise its contributions:
+
+```bash
+paseo plugin install npm:@acme/paseo-review@1.0.0
+paseo plugin ls
+```
+
+Require `running` with no error, then [submit the package](#plugin-registry).
+
+## Share through GitHub or Git
+
+For the public registry, push your plugin to a public GitHub repository. Include its manifest,
+runtime entries, imported files and listing assets. Git tags and commits are optional at submission;
+provide one to select a revision, or the reviewer resolves `main`.
+
+If preparation installs runtime npm dependencies, commit a synchronized `package-lock.json` and
+add this command to `paseo-plugin.json`:
+
+```json
+{
+  "build": [["npm", "ci", "--omit=dev", "--ignore-scripts"]]
+}
+```
+
+`npm ci` consumes the committed lock and fails if it disagrees with `package.json`. `--omit=dev`
+excludes development tools and `--ignore-scripts` suppresses dependency lifecycle scripts.
+The daemon needs npm on its command path. Plugins using only host libraries need no preparation
+command. See [preparation](#plugins-with-a-build-step) for generated files or explicit scripts.
+
+Users can install directly from Git without a registry listing:
+
+```bash
+paseo plugin add git:acme/paseo-review
+paseo plugin add git:acme/monorepo:plugins/review
+```
+
+Use `--ref` to select a branch, tag or commit for the initial installation. Direct installation
+also supports private repositories and other Git hosts when the daemon has access; see
+[plugin sources](/docs/plugins/reference#plugin-sources). Registry submission accepts public
+GitHub sources and public npm packages.
 
 ## Plugin registry
 
-Browse published plugins at [paseo.sh/plugins](https://paseo.sh/plugins).
-Users install the reviewed artifact with:
+Open the [submission form](https://github.com/getpaseo/plugins/issues/new?template=submit-plugin.yml).
+Use the form so the issue receives the submission label that starts intake.
+
+1. Use your plugin's name as the title.
+2. In **Source**, enter the public npm package name or page, or the GitHub repository/folder URL.
+   Include the version or Git reference if you want a specific release reviewed. npm defaults to
+   `latest`. Registry IDs and local directories are not submission sources.
+3. Select the categories that fit. Include any interface-image URLs in the issue description.
+
+The bot opens a review PR. The reviewer inspects the artifact and dependencies without running
+plugin code, completes the listing and records the exact approved version or commit. Publication
+requires the [review policy](https://github.com/getpaseo/plugins/blob/main/REVIEW.md), including
+locked installation inputs and appropriate data access, even when automated validation passes.
+
+If a change is requested, reply on the review PR with the corrected version/revision or requested
+image URL. The reviewer updates the pin and listing. Intake service errors retry automatically;
+missing images or an overview do not prevent opening the review PR.
+
+After approval and publication, users install your listing with:
 
 ```bash
 paseo plugin add owner/slug
 ```
 
-Publish your artifact through npm or Git, then follow the
-[registry submission guide](https://github.com/getpaseo/plugins) to submit it for review.
-Registry installations and updates use the approved revision and plugin path.
-Direct Git installs use explicit `git:owner/repository` shorthand or a full Git URL.
+npm releases receive automatic update PRs. Submit Git updates manually with the desired revision.
+Existing registry installations use approved pins; direct npm/Git installs follow their own update
+rules in the [source reference](/docs/plugins/reference#plugin-sources).
 
-## Publish on npm
+## Plugins with a build step
 
-The scaffold prepares the package files and development dependencies. You choose the package name
-and release version.
+Paseo compiles TypeScript, so an ordinary plugin needs no separate publication build.
+Keep generated modules in their runtime directory and host-provided modules external.
 
-### 1. Set your package name and version
+Paseo suppresses npm lifecycle scripts during package acquisition. Commands explicitly declared in
+manifest `build` still run, including scripts they invoke. Explain the purpose of those commands
+and keep their inputs locked and inspectable. Remove Git-only dependency-install commands from
+npm manifests when npm already installs the production dependencies.
 
-From the plugin directory, set your package details and allow publication. Replace `@acme` with your npm scope:
+Later setup that installs another dependency tree needs its own complete lock, even if your plugin
+has a development lockfile. For npm setup, ship the runtime manifest and lock together and use
+`npm ci`. For Python setup, ship a requirements file containing exact versions and SHA-256 hashes
+for all transitive packages, then install it with:
 
 ```bash
-npm pkg set name=@acme/paseo-review version=1.0.0
-npm pkg delete private
+python -m pip install --require-hashes -r requirements-documents.txt
 ```
 
-### 2. Check and publish
+This command rejects unpinned or unhashed dependencies. Runtime installation also needs the
+[confirmation and disclosure](#your-listing-page) described above.
 
-```bash
-npm run typecheck
-npm pack --dry-run
-npm publish --access public
-```
-
-Check the pack output includes any assets you added to the project.
-
-### 3. Test the published plugin
-
-On a daemon host with npm available:
-
-```bash
-paseo plugin install npm:@acme/paseo-review@1.0.0
-```
-
-Users can also paste `npm:@acme/paseo-review` into **Settings → Plugins → Plugin source**.
-
-:::example[Package configuration]
-
-The scaffold includes this `files` list in `package.json`:
-
-```json
-{
-  "files": [
-    "paseo-plugin.json",
-    "OVERVIEW.md",
-    "index.client.ts",
-    "index.client.tsx",
-    "index.server.ts",
-    "index.server.tsx",
-    "client/",
-    "server/",
-    "shared/"
-  ]
-}
-```
-
-- Add any assets stored outside these directories to `files`.
-- Keep the scaffold's SDK and host libraries in `devDependencies`.
-- Add other runtime libraries with `npm install <package>`. Paseo installs their dependencies too.
-- The npm package name identifies the source. The manifest's `id` identifies the installed plugin.
-
-See the [project reference](/docs/plugins/reference#project-files) for entry points and runtime boundaries.
-
-:::
-
-### Plugins with a build step
-
-Paseo compiles TypeScript. An ordinary plugin needs no separate build before publication.
-If your plugin generates files, include the generated output in the package.
-
-**Installation scripts do not run automatically.** If a dependency needs host-specific setup,
-declare a [preparation command](/docs/plugins/reference#cli-reference).
-
-:::example[Generated files and dependencies]
-
-- Generate code and assets before running `npm publish`.
-- Keep generated JavaScript in its runtime directory and import it from the TypeScript entry.
-- Include generated assets in `files`.
-- Keep host-provided modules external when producing your own bundle.
-- Remove Git-only dependency-install commands from the published manifest; npm installation already
-  installs production dependencies.
-
-Paseo skips npm lifecycle scripts during installation, including dependency scripts. For example,
-a native dependency that needs rebuilding requires an explicit preparation command.
-
-:::
+## Private npm packages
 
 :::example[Publish a private package with GitHub Packages]
 
@@ -151,104 +281,3 @@ Paseo uses the host's npm registry settings and credentials for installation and
 In the app, enter only the source identifier.
 
 :::
-
-## Icons and screenshots
-
-Declare your display name, icon, screenshots, and demo videos in `paseo-plugin.json`:
-
-```json
-{
-  "id": "review-tools",
-  "name": "Review tools",
-  "description": "Reviews changes before merge",
-  "icon": "assets/icon.png",
-  "media": ["assets/screenshot.png", "https://example.com/review-demo.mp4"],
-  "requirements": { "paseo": ">=0.11.0" }
-}
-```
-
-All three fields are optional. `name` gives the registry and website a display name without
-changing the installation ID. When omitted, the registry falls back to a humanized ID.
-Registry and website display requires the registry builder to read these fields from the pinned
-manifest. That update is a separate follow-up; until it lands, these fields are exposed only
-through the daemon's installed-plugin list.
-`icon` must point to a PNG inside the plugin package. `media` accepts paths to images and videos
-inside the package or HTTPS URLs, in display order. Paths are relative to the manifest; use
-forward slashes and keep them inside the package. See the [manifest reference](/docs/plugins/reference#project-files)
-for validation rules.
-
-Commit local assets alongside the manifest at the pinned revision. For npm, add their directory
-(for example, `assets/`) to `package.json`'s `files` list and verify it with `npm pack --dry-run`.
-The scaffold documents these fields in its manifest's `$comment`; add your display name and
-assets before publishing.
-
-Manifests using these fields fail to install on daemons before 0.11.0. Set
-`requirements.paseo` to `>=0.11.0` or a narrower supported range.
-
-## Your listing page
-
-Write `OVERVIEW.md` beside `paseo-plugin.json` for the plugin page inside Paseo.
-It helps someone decide whether to install your plugin; the install command is already at
-the top of that page. A README assumes a GitHub audience and carries installation
-instructions, technical details, and badges. Long, AI-generated READMEs make people read
-past that material to understand what a plugin does.
-
-`OVERVIEW.md` is required to list your plugin in the registry. Commit it beside
-`paseo-plugin.json` in the source repository at the pinned commit. The registry resolves it
-relative to the manifest, under `pluginPath` for monorepos. Include it in the published npm
-package too; the scaffold's `files` list includes it. Replace the scaffold's guidance comment
-with useful facts before publishing.
-
-The repository overview takes precedence over a registry import stopgap. Online validation
-fails when the pinned commit has no `OVERVIEW.md`, except for unchanged imported records
-that already carry `plugins/<owner>/<slug>.md` in the registry repository. Every version bump
-requires a repository overview and removes the stopgap in the same PR. A bump without the
-repository overview fails validation. README files do not supply the overview.
-
-Author overviews and registry stopgaps follow the same content contract, in this order.
-Choose headings only when they help; length follows complexity. A theme needs one paragraph.
-
-1. Explain what the plugin is and does in plain terms first.
-2. Explain how it works only when that is not obvious.
-3. Explain setup when needed: settings, accounts, tokens, providers, external tools, or other
-   plugins. Include applicable daemon version and operating system requirements. Setup
-   guidance is allowed; installation instructions are not.
-4. Explain capabilities and settings worth understanding, what each option does, what the
-   plugin reads or sends and where, permissions, and known limits.
-
-Use sentence case and plain factual language, with no em dashes. Omit installation commands,
-badges, changelog, contributing or license sections, marketing, and unsupported claims.
-Avoid implementation filler such as empty cleanup functions, catalogs of theme-token fields,
-or lists of absent features. Keep only what helps someone choose the plugin.
-
-If your plugin is an unchanged imported record, you can propose an author-written overview
-to replace the registry stopgap. Do not add import credit to your own `OVERVIEW.md`.
-
-## Share through GitHub or Git
-
-Push the plugin project to a repository. Users can install it with:
-
-```bash
-paseo plugin add git:acme/paseo-review
-```
-
-For another Git host:
-
-```bash
-paseo plugin install git:https://git.example.com/acme/paseo-review.git
-```
-
-If your plugin has runtime npm dependencies, commit `package-lock.json` and add a preparation
-command to `paseo-plugin.json`:
-
-```json
-{
-  "build": [["npm", "ci", "--omit=dev"]]
-}
-```
-
-- `npm ci` installs the versions in the committed lockfile.
-- `--omit=dev` excludes development tools.
-- npm must be available on the daemon host.
-
-Plugins that only use Paseo's host libraries need no preparation command.

public-docs/plugins/reference.md

@@ -63,7 +63,9 @@ The required root manifest is `paseo-plugin.json`:
 | `build`        | No       | Preparation commands, described in the CLI reference.                                     |
 
 Paths are relative to `paseo-plugin.json`, use forward slashes, and cannot contain `..`
-segments. See [icons and screenshots](/docs/plugins/publishing#icons-and-screenshots) for an example.
+segments. Registry listings for visual plugins require an interface image even though `media` is
+optional in the runtime manifest. See [icons and screenshots](/docs/plugins/publishing#icons-and-screenshots)
+for accepted formats and listing requirements.
 Paseo validates the references without opening local assets or fetching URLs.
 
 Unknown top-level fields are ignored. Known fields still validate, and unknown keys inside
@@ -2137,7 +2139,7 @@ export default function contribute(server: PluginServerContext) {
 
 Inputs and outputs are validated on both sides. RPC names start with a lowercase letter and contain lowercase letters, numbers, dots, hyphens, or underscores. `useRpc()` returns a typed async function. Use TanStack Query for request state, caching, and mutations.
 
-Backend handlers receive the same `PaseoApi` as `{ paseo }`. Their connection belongs to the subprocess and closes when the plugin stops. It does not subscribe to timelines or catalog events until plugin code subscribes. Follow the [SDK event contract](../../sdk/events.md) for cleanup and timeline replacements. Backend code can use Node APIs and dependencies installed in the plugin directory.
+Backend handlers receive the same `PaseoApi` as `{ paseo }`. Their connection belongs to the subprocess and closes when the plugin stops. It does not subscribe to timelines or catalog events until plugin code subscribes. Follow the [SDK event contract](/docs/sdk/events) for cleanup and timeline replacements. Backend code can use Node APIs and dependencies installed in the plugin directory.
 
 ## Debug backend output
 
@@ -2351,8 +2353,9 @@ keeps the complete dependency tree and `package-lock.json` when activating it. T
 package and lockfile provide its current version and artifact integrity. A version, tag, or range
 chooses content for this installation only.
 
-For package contents, dependencies, preparation, and private registries, see
-[Publish a plugin](/docs/plugins/publishing).
+The installed lockfile records what this installation resolved. Authors submitting npm plugins
+with runtime dependencies must also ship the [publication lock](/docs/plugins/publishing#2-lock-installed-dependencies).
+For package contents, preparation and submission, see [Publish a plugin](/docs/plugins/publishing).
 
 A failed download, dependency installation, manifest check, preparation command, compilation, or
 activation discards the candidate. Other installed plugins keep running. Removing an npm plugin