Cinatra — Application Design — Extensions

In the app each extension surfaces as a ListingCard whose action reflects per-instance state. The install CTA is the four-state machine taken straight from /configuration/marketplace: Install now when it isn't installed, a disabled Installed pill at the current version, Update now when a newer version sits in the catalog, and Restore for one that was removed; a submit in flight reads Installing…. When an extension can't run on this Cinatra instance its install greys out and an Incompatible line replaces the compatible check. The six cards show one of each.

Clicking More details on a ListingCard opens this modal. Its body embeds the extension's listing detail from marketplace.cinatra.ai — the same layout as the marketplace listing detail (§IV of the Marketplace spec), stripped of the site header/footer, the storefront's own Install now, the More Extensions tab, the pagination and the Related extensions rail. The modal's own footer carries the install action with its per-instance state — the six-state CTA of §I.

cinatra run research-assistant --query "Q3 churn drivers"

A dialog on --paper — the same surface as pages — over a dimmed overlay (which stops below the navbar). Its body scrolls top-to-bottom only — everything is sized to fit the width, so nothing ever scrolls sideways — while the header and footer stay fixed. The header carries just a close ✕. The body is the marketplace listing detail lifted whole — the app-logo tile, title and {Type} by {Vendor} line (the vendor links out to its marketplace.cinatra.ai store), the price, the Details / Reviews / Changelog tabs, then either the README beside its specs column (version, last-updated, Compatible up to: Cinatra {version}, installations) or the WooCommerce reviews list beside its rating summary (the average, the star-by-star breakdown and per-level counts — the submission form is dropped in-app), and the share row — but nothing that navigates the storefront (no More Extensions tab, no prev/next pagination, no Related extensions). Because the install action belongs to this instance, it is pulled out of the embedded content and rehomed to the dialog footer, where it carries the same six states as §I — Install now, Installed, Update now, Restore, Installing… and the greyed Incompatible. The specs column ends with the extension’s Dependencies — the other Cinatra extensions it declares in cinatra.dependencies (a read-only list here in the app; on the marketplace page each links to its listing), not its npm packages — and a Changelog tab that renders the extension’s root CHANGELOG file as per-version release notes, or a No changelog available message when the extension ships no CHANGELOG.

When the footer's Update state is chosen, Update now runs the resolver as a dry-run first and shows an Update plan the admin confirms before anything is written. The plan lists every affected member grouped by what happens to it — Update (the extension itself, and any shared dependency upgraded in place when every dependent's range admits it — dedupe-upward), Install (a dependency newly added), Side‑by‑side (a second version kept alongside the current one when the ranges are disjoint), and Rebound (a dependent re-pointed to the upgraded shared dependency). Confirm update applies through the same batch path as install, so the batch progress panel tracks each member live (Updating…). A failure surfaces the category-mapped lifecycle copy — the specific reason stays server-side — and the batch compensates, restoring the prior versions, so a failed update never leaves a half-applied state. This footer is the only place the update runs: on the §III installed card the same availability is surfaced ahead of time by the Update available chip, and that card's actions stay exactly Settings and More details.

Manage installed agents, skills, connectors, and artifacts. Each installed extension is one horizontal card, split three ways: a logo + name panel on the left (the ListingCard mark of §I) — on the extension’s category colour, or fully greyed out when it is archived — with the {Type} by {Vendor} line beneath the name; a white middle carrying the description, then the version with its status beside it — a green check for Active, a green lock for a Locked system extension, a grey cross for Archived, plus an Update available chip when a newer compatible version is published; and a white actions panel on the right (Settings, More details). A status filter — the four status views All · Active · Locked · Archived (§III.1–§III.6 below) — plus Marketplace and Upload sit above the list.

One card per installed extension, divided into three panels. The left panel reuses the ListingCard logo tile + italic white title on the extension's categorical ground — with the type/vendor line beneath the title — so an installed extension reads as the same object it did in the marketplace. The white middle stacks the description and the pinned --font-mono version with its lifecycle status — a green check for Active, a green lock for a Locked system extension (always active — it cannot be archived or uninstalled, so it shares the live-green ink but reads distinctly from a normal active row), a grey cross for Archived, plus an Update available chip when a newer compatible version is published (states below). Archived extensions render entirely in grey (the coloured ground, kind emblem, status and actions all desaturate) so they read as inactive at a glance. The white right panel — set off by a navy hairline — carries the per-instance actions: Settings opens the extension's configuration, More details opens the §II detail modal.

The status filter partitions the installed list into four views. Above the list, a single-select control chooses which installed extensions show — All, Active (the default), Locked or Archived — and drives a shareable ?tab= URL. Active, Locked and Archived are a clean partition of the installed set by the lifecycle status above — a Locked extension lives under Locked, not the default Active view — and All is their union.

1. 3.1 The status filter offers exactly four views, in this order — All · Active · Locked · Archived. It is a single-select control whose trigger shows the current view; these four are the whole filterable status set.
2. 3.2 Each view has a stable URL: the default Active view carries no ?tab= query (its canonical URL), and ?tab=all, ?tab=locked, ?tab=archived each address their view. ?tab=active resolves to Active too, but is non-canonical — the selector never writes it (choosing Active clears the query). The no-query landing view stays Active — adding options must not change what users see today. Any absent, empty, or otherwise invalid / unknown ?tab= value falls back to Active — a defined, tested fallback, never a 404 or a dead / misrendered tab, so a bookmarked or hand-edited URL always resolves.
3. 3.3 Active, Locked and Archived are a clean partition of the installed set: every installed extension falls in exactly one of Active (status: active), Locked (status: locked) or Archived (status: archived). A locked extension appears under Locked (and, as their union, All) and is excluded from the default Active view; no row is dropped or double-counted across views, and every view's count is exact.
4. 3.4 All lists extensions of any status together — the union of Active, Locked and Archived — each with its own per-status treatment from §III: active and locked read live, archived greys out.
5. 3.5 Locked lists only locked extensions — the always-active system / required extensions that cannot be archived or uninstalled (the green-lock status of §III). This is the first dedicated view of that set; before it, locked extensions had no view of their own.
6. 3.6 Every view has its own empty state, consistent with the existing pattern: Active — No active extensions (browse the marketplace to add one); Locked — No locked extensions (required and system extensions that cannot be archived appear here when locked); Archived — No archived extensions (uninstalled extensions appear here; their run history remains intact); All — No extensions installed (nothing installed in any state yet).

Beside the version and its Active/Archived status, the spec-line carries one more optional badge — an Update available chip. It reuses the status-indicator badge treatment (--font-mono, the smallest 2xs step, uppercase, 0.1em tracking, weight 700, a 12px mark) but in the --blue action accent with a circular-arrow glyph, so it reads as timely news, not an action. It appears only when a newer compatible version is published for a registry-comparable source. Four states: Update available — chip present; Up to date; Incompatible — a newer version exists but needs a newer Cinatra, so the row greys out under the §I ABI-compat treatment and shows no chip; and Non-comparable — github refs, 0.0.0-dev.* and local builds have no registry version to compare, so they never show a chip and never fall back to a string-equality guess. The chip is the only update information the card carries: no explanatory update text ever appears in the card. The wordings behind the last two states — Newer version needs a newer Cinatra, No registry version to compare — surface on the §V extension-settings page's Maintenance · Update row instead. The chip is status only: the card's actions stay exactly Settings and More details; the update itself is run from the §II detail-modal footer.

The redesigned card for the /agents "All Agents" tab. Derived from the §III Installed-extensions card — the same coloured logo + name panel (with the {Kind} by {Vendor} byline beneath the name) and description — but without the version and the Active / Archived indicator: an agent you run doesn't need either surfaced here. The right panel's primary action becomes Run, marked with a play icon in place of the settings gear; More details stays. The description is capped at three lines.

Same three-panel anatomy as §III — coloured logo tile, white middle, white right panel set off by a navy hairline — minus the version/status row, so the middle panel carries just the (three-line-clamped) description, with the byline beneath the name in the coloured panel. The right panel drops to a single primary action, Run, plus More details (opens the §II detail modal).

One page for everything you can do to an installed extension. Settings (§III) opens this page — a Narrow column that gathers the extension's actions into grouped sections (Permissions, Marketplace, Maintenance), ending in a red Danger zone. The page header matches the §II detail modal, with nothing in the top-right. Destructive and one-way actions are red and always confirm.

The page holds to the Narrow column: the §II detail header, then the groups — Permissions and Marketplace, then Maintenance, then the red Danger zone. Permissions reuses the install-time access picker (project · team · organization scopes, plus the two always-offered workspace scopes — Whole Workspace and Admins only — which only a platform admin may select; for every other role those two rows render disabled with the reason Requires platform admin., matching the disabled treatment the org/team/project rows already use) for connectors and artifacts — the picker component itself is specified normatively in Application Design — Permissions. The workspace scopes set the post-install audience: a Whole Workspace install is visible to every workspace member, and an Admins only install is visible to admins only. Agents and skills are managed from their own pages, so for those the section links there instead of showing the picker — an agent to the Agents page, a skill to its configuration page. Update carries the extension's update status as the row's description — the §III card states spelled out in words: the available version when a compatible update is ready, Newer version needs a newer Cinatra when the newer version is incompatible, No registry version to compare for github/dev/local sources, and an up to date line otherwise — with the button greyed out whenever there is nothing to run. This row is where that explanation lives: the §III card itself never carries explanatory update text (it shows at most the Update available chip). Archive and Activate are complementary — exactly one is live: Activate greys out until the extension is archived, Archive greys out once it is. Destructive and one-way actions are the destructive red button and always confirm; Force-delete additionally demands a typed reason and warns that it bypasses restore, and publishing to the marketplace is one-way — and gated: on the instance being a registered marketplace vendor (until then the action is muted beside a Register for marketplace link), and on the kind being publishable — a registered vendor viewing a kind that can't be published yet sees the action muted, Marketplace publishing isn't available for this extension yet.

When a freshly-installed extension still needs its connectors set up, it can't run yet — so it reads as inactive until you finish. On the Extensions page (§III) the extension renders in the archived treatment — the greyed ground, desaturated kind emblem, muted name and actions — with a thin status strip attached to the bottom of its card. The strip carries the design system's Needs review status colours (the .pill.hold mustard tint) and lists, centred, each required connector's human name as a link to its setup page. The moment every required connection is configured the card flips back to its normal active colours and the strip disappears. Installing never waits on it — this is a follow-up reminder, not a gate.

The card is the §III installed-extension card, rendered in the archived treatment — greyed ground, desaturated kind emblem, muted name, byline and actions — because at least one required connector is not configured yet, so the extension can't run. A thin status strip is attached seamlessly to the bottom of the card in the design system's Needs review colours (the .pill.hold mustard tint over --mustard-ink, a mustard hairline on top). Its content is centred: a warning glyph, then Set up connections first:, then each required connector's displayName (its manifest.displayName — the same human-readable name the §I ListingCard and the Connectors grid use) as a link to that connector's setup page (§II of the Connectors design). Every connector among the installed extension and its auto-installed dependencies is checked against its own readiness, and only the unconfigured ones are listed; the moment all are configured the card flips to its normal active colours and the strip is absent. Install stays non-blocking — the strip is a follow-up reminder, not a gate.