---
title: Foundry is marketplace-only + how plugins update
---

# Foundry is marketplace-only + how plugins update

## What it is

**Foundry** is Omniscio's PRD-authoring plugin — the tool you use to draft and refine
product requirement documents inside the app. It used to be baked into Omniscio itself
(a "built-in" plugin that shipped with every copy of the app). It no longer is. Foundry
is now a **pure Marketplace plugin**: you get it by installing it from Omniscio's plugin
Marketplace, exactly like any third-party plugin.

Two things follow from that change:

1. **A fresh install always gets the latest published Foundry.** Because Foundry comes
   from the Marketplace instead of being frozen into the app build, a new install
   downloads whatever the current published version is at install time, rather than
   whatever version happened to be inside the app you downloaded.

2. **Existing built-in users are migrated once, automatically** (details below) — so you
   don't have to reinstall anything.

## Where to find it

Foundry comes from Omniscio's plugin **Marketplace**, like any third-party plugin — there is no built-in copy to switch on any more. Updates are offered there too, and you decide when to take them.

## How it behaves

### How plugin updates work — you're asked whenever it matters

Omniscio **never widens a plugin's access behind your back.** An update that asks for
nothing new is installed in the background; one that wants access you have not approved
stops and waits for you, with the permission list shown. This is the same flow for every
Marketplace plugin, Foundry included:

- Omniscio checks on launch, every 6 hours, and when you refocus the window.
- An update requesting nothing new is applied by itself at that point.
- When an update IS waiting for you, you get a count badge, a dismissible banner, and an inbox
  card that names what is pending — never a popup over your work.
- Clicking **Review updates** opens the Updates window, which shows each plugin's version bump, a
  short changelog, and — importantly — **any new permissions** the update requests. You
  apply per-plugin or all at once. **These never install themselves.**

Full detail of the check + apply flow lives in [Plugin Marketplace](plugin-marketplace.md)
(section "Auto-update"). You can turn the whole thing off at **Settings → Plugins → Check
for plugin updates**.

### Existing Foundry users are migrated automatically

If you were already using the old built-in Foundry, you don't have to reinstall anything.
The **first time you launch the new version of Omniscio** (the one that stopped shipping
Foundry as a built-in), Omniscio performs a **one-time migration**: it installs the
Marketplace copy of Foundry for you in the background and marks the migration done so it
never repeats. This is a continuity step for a plugin you already had enabled — not a
version update you need to approve.

Crucially, **your in-progress PRDs are safe**. Foundry stores your documents in your
app-data folder (`%APPDATA%` on Windows) separately from the plugin's code, so swapping
the built-in plugin for the Marketplace copy does not touch your work. You reopen Foundry
after the migration and everything is exactly where you left it.

The same one-time migration applies to two other former built-ins — **RepoGuard** and
**Decks** — each with its own migration flag.

### Test and throwaway copies skip it

Automated test runs, the sandbox, and the fresh-profile copies developers open to try things
out all start from an empty profile every time. They skip this one-time install entirely, so
they never download Foundry and never add to its public download count on the Marketplace.
Real installs, and each developer's own main copy, get Foundry exactly as described above.

### Fail-safe by design

- **Nothing blocks app startup.** If the migration runs while you're offline, or the
  plugin registry can't be reached, or a download or checksum fails, Omniscio just skips
  it and moves on. The app starts and runs normally regardless.
- **A working copy is never removed.** If installing the Marketplace copy fails, Omniscio
  keeps whatever you already had — it never leaves you with a broken or missing plugin
  because a step hiccupped.
- **A failed migration simply retries.** If the one-time migration can't complete (say,
  you were offline on that first boot), it does **not** mark itself done — it quietly
  tries again on the next launch. Your PRD data is never stranded in the meantime.

### Prerequisite / rollout note

For the automatic migration to succeed, **Foundry must stay published on the Marketplace
(version 1.2.1 or later)** — and RepoGuard (v1.2.0+) and Decks likewise.
Removing the built-in only takes effect once you run the Omniscio version that drops it,
and on that first launch the migration installs the Marketplace copy — which requires the
plugin to be available there to download. (If it weren't published, the migration safely
defers and retries rather than failing, but you'd have no copy until it's re-published.)

## For agents

### Under the hood (for agents with repo access)

- **Loader exclusion**: `BUILTIN_EXCLUDE = new Set(['prdstack', 'reading-queue', 'repoguard', 'writer'])`
  in [src/main/services/plugin/plugin-loader.ts](/src/main/services/plugin/plugin-loader.ts)
  makes a built-in `prdstack` / `repoguard` skipped in `scanDirectory`; a
  Marketplace copy always wins over a built-in of the same id. No packaging change was
  needed — built-ins aren't staged into the packaged app anyway.
- **Builtin-migration engine**:
  [src/main/services/marketplace/plugin-update-service.ts](/src/main/services/marketplace/plugin-update-service.ts)
  exports `migrateFoundryBuiltin` / `migrateRepoguardBuiltin` / `migrateDecksBuiltin`,
  the mutex-guarded `runBuiltinMigrations`, and `startPluginUpdateService`, plus the named
  constants `FOUNDRY_PLUGIN_ID = 'prdstack'` etc. It runs as the `'Plugin auto-update
  service'` StartupTask (`defer: 'setImmediate'`) **once at boot** — there is no update
  pass and no recurring backend timer. Installed plugins are updated only via the manual
  Plugin Updates modal (the renderer check in [App.tsx](/src/renderer/src/App.tsx)).
- **Throwaway profiles skip the pass**: `startPluginUpdateService` returns before
  `runBuiltinMigrations` when `runsOnThrowawayProfile(process.env)` is true — the same
  `instanceMustIsolateData` allowlist the data-dir guard uses (every named instance such as
  `e2e`, `claude-sandbox` or `dev2`, except the developer's own `dev` copy). Without it every
  E2E launch downloaded Foundry and counted as a public install. Contract invariant
  `throwaway-instance-skips-boot-migrations`.
- **Migration flags**: `foundryBuiltinMigrated` / `repoguardBuiltinMigrated` /
  `decksBuiltinMigrated` (default `false`) — internal state, no Settings UI; each set
  once after its Marketplace copy is installed.
- **Contract with test-locked invariants**:
  [.claude/memory/contracts/plugin-builtin-marketplace-precedence-contract.md](/.claude/memory/contracts/plugin-builtin-marketplace-precedence-contract.md)
  — in particular `no-silent-update` (the backend never installs a version update) and
  `migration-mutex-boot-once` (runs once at boot, no timer).

## Related

Plugins in general — installing one, switching it on, and what the sidebar does with it — are covered by the plugin documentation in this library.