Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 72 additions & 5 deletions docs/docs/features/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,10 @@ npm package of a local MCP server, which goes through the same package cache and
integrity check as the [extension library's local package servers](./agent-extensions.md#local-package-servers).

:::note Work in progress
This page describes the plugin **manifest**, the official plugin registry and
how an administrator **installs** a plugin through the API. The Plugins page,
applying contributions to runs, OAuth connections, handlers, webhooks and
commands are added by later releases; until then an installed plugin's state
is stored and served but has no effect on runs.
This page describes the plugin **manifest**, the official plugin registry, the
[Plugins page](#the-plugins-page) and the installation API. A plugin's
generated settings form, handlers, webhooks and commands are added by later
releases.
:::

## Where plugins live
Expand Down Expand Up @@ -168,6 +167,74 @@ npm run plugins:check -- --online [--registry https://registry.npmjs.org]
also asks the npm registry for each package server's version and compares the
recorded `integrity` value. It needs network access and is not run in CI.

## The Plugins page

**Plugins** (`/plugins`) is where an administrator installs a plugin and makes
it work without knowing what it contributes internally. It is in the sidebar
(on mobile, under **More**) and linked from **Settings → Agent Extensions &
Packages → Skills & MCP servers**, and only durable administrators with
`instance.manage_settings` see it. Everything on the page is drawn by ProPR
from the manifest: manifest text is shown as plain text, links appear only for
`https` URLs, and no code, image or markup supplied by the plugin runs in the
browser.

### Catalog

The catalog shows one card per plugin: an icon for its category, its name,
one-line description, category and a state badge. Filter by **Category** or
type in **Search by name**.

| Badge | Meaning |
| --- | --- |
| Not installed | Available in this ProPR, not installed. |
| Off | Installed, every connection set, not enabled. |
| Needs connection | Installed and not enabled, with a connection still to set or sign in. |
| Enabled | Enabled, every connection set. |
| Needs approval | An upgrade asks for permissions or a secret acknowledgement not yet approved. |
| Degraded | Enabled while a connection is missing or needs a new sign-in, or no longer in this ProPR's registry. |

### Walkthrough

Open a card to see the plugin's steps, always in this order, each marked
**Done** or **To do**:

1. **Install.** The step says what the plugin adds in plain words, for example
"Adds 1 MCP server the agent can read from", "Runs 1 local server inside
the task container" or "Adds the /deploy command", and lists the
permissions it asks for, each with a one-line explanation. When a local
package server receives secret variables, the step shows the package, its
exact version and the variable names, with a required checkbox confirming
that those secrets are readable inside the task container. **Install**
stays unavailable until it is ticked. After an upgrade that needs approval,
the step lists what is new and offers **Approve**.
2. **Connect.** One row per connection with its state, the manifest's help text
and a **How to get it** link. An OAuth connection has **Connect**,
**Reconnect** and **Disconnect**, the same controls as an OAuth server in
Skills & MCP servers; sign-in opens in a new tab and the page refreshes when
you come back. A `token` or `signing_secret` connection has a write-only
field: once saved, the page only says who stored it and when, and offers
**Replace** and **Clear**. A required connection cannot be cleared while
the plugin is enabled.
3. **Configure.** **Limit to repositories** picks the repositories the plugin
applies in; leave every box unchecked for all repositories. The form for
the plugin's own settings is added by a later release.
4. **Enable.** A single **Enabled** checkbox. While a required connection,
required setting or secret acknowledgement is missing it cannot be ticked,
and the step lists what is missing, for example "Connection Example API
token (example-token) is not set". Untick it to disable the plugin; its
settings and connections are kept.

Below the steps, **What it added** lists the plugin's managed MCP servers and
skills, with a link to Skills & MCP servers where they are listed, and its
automation templates, each with whether it applies now.

**Uninstall** is a separate action. Its confirmation lists what is removed:
the settings and repository limit, each connection and stored credential, the
managed library items and the templates. The audit trail is kept. When an
automation still adds one of the plugin's managed items, the API refuses the
uninstall and the page shows its message, which names the automation; remove
the item from that automation and try again.

## Installing a plugin

A plugin is **available** when it is in this ProPR's registry, **installed**
Expand Down
13 changes: 12 additions & 1 deletion docs/docs/features/web-ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The ProPR Web UI configures repositories and agents, launches work, and shows pr

## Navigation And Chrome

The sidebar's work area contains **Dashboard**, **Inbox**, **Tasks**, **Goals**, **Automations** and **Plans**. The system area contains **Repositories**, **Coding Agents** (administrators), **Analytics**, the collapsible **Logs** group, **Settings** and **Access** (administrators). Count badges show current work and unread Inbox items. Agent Tank usage appears below navigation when enabled.
The sidebar's work area contains **Dashboard**, **Inbox**, **Tasks**, **Goals**, **Automations** and **Plans**. The system area contains **Repositories**, **Coding Agents** (administrators), **Analytics**, the collapsible **Logs** group, **Settings**, **Plugins** and **Access** (administrators). Count badges show current work and unread Inbox items. Agent Tank usage appears below navigation when enabled.

The header includes search (`Cmd/Ctrl+K`), activity/review controls, quick add to-do (`Alt+T`) and system health. Search opens a command palette that groups matching repositories, plans and tasks, with a preview of the highlighted item beside the list on wider screens. Tab and Shift+Tab switch between the **All**, **Repos**, **Plans** and **Tasks** tabs, Enter opens the highlighted item, Cmd/Ctrl+Enter opens it on GitHub, and **Search all tasks** runs the term as a full Tasks search. **New Task** is the default creation action. It becomes **New Plan** in Plans/Planner Studio, **New Goal** in Goals and **New Automation** in Automations; the adjacent menu offers the other actions. See [Launching work](./launching-work.md) to choose between them. After quick add confirms **To-Do added**, choose **Add another** to enter the next item without closing the popover. Desktop puts application information in **About ProPR** rather than the sidebar footer.

Expand Down Expand Up @@ -122,6 +122,17 @@ for the operator walkthrough and the log's filters.

![Settings AI and Models tab showing implementation and planning model controls in a single column](/img/screenshots/0.9.0/settings.png)

## Plugins

**Plugins** (`/plugins`) installs and manages [plugins](./plugins.md#the-plugins-page). It appears in the sidebar (on mobile, under **More**) and as an **Open Plugins** link above **Skills & MCP servers** in Settings, only for durable administrators with `instance.manage_settings`; anyone else who opens the address sees *Administrator access required*.

1. The catalog shows a card per plugin with its name, description, category and a state badge (**Not installed**, **Enabled**, **Off**, **Needs connection**, **Needs approval** or **Degraded**). Filter by category or search by name, then open a card.
2. **Install** lists what the plugin adds and the permissions it asks for. If a local package server receives secret variables, tick the acknowledgement that names its package, version and variables, then choose **Install**.
3. **Connect** has one row per connection: **Connect** for an OAuth sign-in (it opens in a new tab), or a write-only field for an API token or signing secret.
4. **Configure** offers **Limit to repositories**; leave it empty to apply everywhere.
5. Tick **Enabled**. While something is missing, the checkbox is unavailable and the step lists what to do first. Untick it to disable the plugin and keep its settings.
6. **What it added** links the plugin's managed items in Skills & MCP servers. **Uninstall…** lists what will be removed before you confirm, and shows the API's message if an automation still uses one of the plugin's items.

## Access

**Access** (`/admin/members`) is available to administrators. It creates durable `admin` and `member` role assignments using stable GitHub user IDs, shows environment administrators configured through `PROPR_ADMIN_USERS`, surfaces recent role-audit events, and prevents removal or demotion of the last durable administrator. On a new installation, sign in as a configured environment administrator and use **Store my administrator role** before removing that username from `PROPR_ADMIN_USERS`.
Expand Down
Loading
Loading