@prodero/curator 0.0.0-stage → 0.1.0

package/docs/hosts.md

@@ -0,0 +1,134 @@
+# Machine host integration
+
+Install the public package (or a generated preview tarball), then run `prodero install`. No elevated privileges are needed for normal per-user host settings. Close the host while changing its settings, then restart it. Development checkout runtimes are deliberately rejected by the installer.
+
+## Commands and status
+
+- `prodero install`: open the interactive installation wizard. It lists every agent and its saved configuration state, then offers numbered install/update actions only for agents that need them. Select an agent, confirm with `y`, and review the result. Repeat for another agent or choose Finish. Enter at the selection prompt finishes; Enter at confirmation cancels that action. Ctrl+C or EOF exits without starting another operation.
+- Installation takes no host arguments and has no `--all` flag. Choose agents inside the wizard. Non-interactive invocation prints readable status and terminal instructions, exits nonzero, and makes no changes.
+- `prodero uninstall [codex|claude]` / `prodero uninstall --all`: remove owned integration, including when the executable has since disappeared. The default visits all adapters.
+- `prodero status`: read-only JSON containing Prodero `version`, `scope: machine`, and each host's detection, support, MCP, launcher and aggregate state. It does not discover or access a project.
+- `prodero status --root PATH`: the separate, existing project status operation.
+
+States are `not-detected`, `not-configured`, `installed`, `outdated`, `conflicted`, `unsupported-configuration`, `recovery-required`, `externally-configured`, `external-incomplete`, or `unsupported` (detection-only adapter). On inspection failure, MCP and launcher fields are `null` (unknown), not proof of absence. Detection means an executable on PATH or the native configuration file exists; it does not prove login, an operational server or UI compatibility. Support labels describe verification separately from installation state. The wizard displays conflicts without hiding other agents; those agents cannot be selected for installation. An installation failure exits nonzero.
+
+An unchanged install writes nothing, including receipts and backups. An intact older managed launcher or changed installed executable location is updated. Edited managed content is a conflict. Re-running install after an npm/Node installation moves refreshes its absolute paths. This command does not update npm packages.
+
+`HOME`, `CODEX_HOME`, `CLAUDE_CONFIG_DIR` and `XDG_STATE_HOME` must use absolute paths when set (empty optional overrides use their defaults). Relative overrides are rejected before any writes, so changing the current repository cannot redirect machine settings into it. Configuration and state must remain inside the user home. Codex installation also checks its inactive global instruction file: an existing Prodero block there is a conflict, rather than permission to install a second launcher. Uninstall can still remove the receipt-owned launcher while preserving an unrelated block in the other file.
+
+## Runtime switching
+
+Keep one managed server named `prodero` and select where it runs. This is separate from the initial `prodero install` wizard:
+
+```sh
+prodero runtime dev --host codex --checkout /absolute/prodero-checkout --dry-run
+prodero runtime dev --host codex --checkout /absolute/prodero-checkout
+prodero runtime package --host codex
+```
+
+Use `--host claude` in Claude Code. A host is always required; the command never guesses the current agent or switches all agents. Callers must select the intended host explicitly. `--workspace PATH` checks that workspace for overrides; otherwise the current directory is checked. Workspace Prodero overrides are reported for review, never rewritten silently.
+
+The installed package must include the public MCP entrypoint and runtime switching support, even before enabling dev mode. Upgrade the package first if it predates this feature. For an existing managed installation, the package target is read from its receipt. Use `--package-root /absolute/installed/@prodero/curator` if the installed package or Node location changed, or when migrating manual dev from a source-checkout CLI. Dev mode requires a Prodero checkout, its development dependencies and an npm JavaScript executable resolvable on the managed launch PATH. Registration invokes the verified absolute public package executable `bin/prodero` with `mcp --dev`. This executable captures host launch context before loading development code or running builds. The checkout loader receives that context in process; builds use checkout-scoped child processes. Paths containing spaces are supported; shell expressions are never evaluated.
+
+For a manual `prodero-dev` setup, first run the desired command with `--dry-run` and review the migration. Apply with `--adopt-dev` to replace only that host's old registration with managed `prodero`. The command preserves private originals and the global launcher. Codex migration accepts a standalone `[mcp_servers.prodero-dev]` table with an optional adjacent `[mcp_servers.prodero-dev.env]` child table. Original settings, including the old environment, remain in private restoration backups. Unusual TOML forms require manual review. Claude migration removes the exact JSON `mcpServers.prodero-dev` entry. Existing canonical `prodero` ownership conflicts are never adopted or overridden by this flag.
+
+Receipts created by switching use format 2 and retain the selected mode, package entry, dev checkout/entry and original uninstall provenance. Format 1 receipts remain readable and upgrade on the first switch. Status exposes `runtimeMode`; the wizard shows `Installed · dev`. Reinstalling preserves intentional dev mode. A repeat switch to the same configuration writes nothing. The transaction verifies saved bytes and rolls back its own changes on write failure; concurrent edits still require recovery rather than an unsafe overwrite.
+
+`runtime dev` stores the canonical Curator checkout as `runtime.devRoot` in the selected host’s private `receipt.json`. It describes runtime code, never a workspace permission. `mcp --dev` reads managed receipts for this installed executable and selects the unique saved checkout associated with an ordinary `mcp --dev` entry. Receipts using explicit checkout arguments do not compete with that default. Missing, malformed, pending, symlinked or ambiguous state fails closed; no cwd/Git/project discovery is used to find Curator code. A saved canonical checkout replaced by a symlink is rejected.
+
+If hosts select different checkouts, switching the second host writes the advanced `mcp --dev --checkout /absolute/curator-checkout` form without changing the first host. The checkout flag selects trusted runtime code only. Package mode never reads development receipts. The `dev → package → dev` cycle retains the saved checkout. The public executable loads the internal `scripts/mcp-dev-launcher.mjs` module; it is no longer a standalone registered server.
+
+Node is required (see `package.json` for the supported version). Ordinary production execution needs neither npm nor development dependencies once the package and runtime dependencies are installed. npm is used for current development builds and npm-based installation/upgrades; it is not a production MCP launcher. Git is optional for session branch/commit metadata. Start MCP directly through `prodero`, not an outer npm script that changes its launch directory.
+
+Project `AGENTS.md` delegates runtime guidance to `prodero_instructions_read`.
+The connected server reads `instructions/AGENTS.md` relative to its own installation,
+so these switches also select the matching instructions. No separate instructions
+path in MCP settings or project edits are needed after the one-time project migration.
+
+Restart or reconnect only the selected host after applying. The command changes saved settings, not the running MCP process. Avoid running an older Prodero installer against a format 2 receipt. On uninstall, otherwise unchanged files restore their exact pre-install/pre-migration bytes, including any original manual dev registration. If other settings were edited later, uninstall removes only the managed blocks; migration originals remain in private backups for manual recovery.
+
+## Native files and ownership
+
+| Adapter | Detection | MCP settings | Minimal global instruction |
+| --- | --- | --- | --- |
+| Codex CLI (verified on macOS) | `codex` on PATH or config file | `$CODEX_HOME/config.toml`, default `~/.codex/config.toml`; only bounded `[mcp_servers.prodero]` stanza | Active nonempty `AGENTS.override.md`, otherwise `AGENTS.md`, in the same Codex home |
+| Claude Code (experimental) | `claude` on PATH or config file | `~/.claude.json`; with `CLAUDE_CONFIG_DIR`, `$CLAUDE_CONFIG_DIR/.claude.json`; only `mcpServers.prodero` | `~/.claude/CLAUDE.md`, or `$CLAUDE_CONFIG_DIR/CLAUDE.md` |
+| Cursor (unimplemented) | `cursor` on PATH or `~/.cursor` | No changes | No changes |
+
+Native configuration overrides are honored only inside the current HOME. Symlinked paths, hardlinked files, malformed/duplicate configuration keys and ambiguous managed boundaries are rejected. Relocating a previously managed configuration requires reviewing/removing its original integration first. A new Codex global override that shadows an installed launcher requires uninstall/reinstall; the new custom override is preserved.
+
+The MCP command is the verified absolute installed public `bin/prodero` executable (also exported as `prodero` by the package manager). Package mode uses `args = ["mcp"]`; development uses `args = ["mcp", "--dev"]`. Managed `env.PATH` starts with the verified Node directory so the executable’s shebang works in GUI hosts without shell profiles. No project cwd is configured. One global registration serves all projects. No fixed repository root is registered. The host supplies workspace authority before `.prodero` exists, so opening Prodero in a new workspace offers initialization through MCP. No CLI initialization, trust command or project allowlist is needed. Global instructions contain no prepare/record/close or other project lifecycle policy.
+
+Claude Code uses negotiated roots, with its matching `CLAUDE_PROJECT_DIR` as the primary workspace; without roots, its captured host project environment can supply the boundary. Empty, unavailable or invalid negotiated roots fail closed. Codex local stdio uses its captured host-selected launch directory. The server recognizes supported host identities on the trusted local connection; client names do not authenticate an arbitrary hostile peer. Unknown contexts fail closed. A child process is bound to its workspace; switching projects uses the host's separate/reconnected sessions.
+
+`projectRoot` is only an exact canonical selector among authorized roots. `PWD`, `INIT_CWD`, model-provided metadata, Git discovery and existing `.prodero` data never grant authority. Core, text, App callbacks and plugins share one operation context; the next call refreshes negotiated roots.
+
+Old receipt-owned registrations using Node with an internal dev script or `npm --prefix` are upgraded on reinstall or runtime switching, preserving backups and uninstall provenance. Manually owned dev registrations need the existing one-time `runtime dev --adopt-dev` migration. Reconnect after that global integration update; no per-project setup follows. Legacy npm-launched Codex connections without roots fail closed instead of treating the installation directory as a workspace.
+
+Text instructions use `<!-- prodero:global-start -->` / `<!-- prodero:global-end -->`. Codex TOML uses `# prodero:mcp-start` / `# prodero:mcp-end`. Private ownership receipts live in `${XDG_STATE_HOME:-$HOME/.local/state}/prodero/host-integrations/<host>/`. Unrelated settings and instructions are preserved, including changes made after installation. Uninstall restores exact original bytes when the files are otherwise unchanged; otherwise it removes only the owned entry/block. It never uninstalls the npm package or removes project knowledge, `.prodero`, project `AGENTS.md`, or project lifecycle instructions. Empty configuration directories and private recovery backups can remain.
+
+## Conflicts and recovery
+
+An active Codex `prodero-dev` connection with a bounded global launcher is recognized as externally configured. It is displayed as already configured manually, without creating a receipt or adding another server. A missing launcher is shown as an incomplete manual setup. Active `prodero-dev` alongside a managed `prodero` integration blocks installation until the duplicate is reconciled; a disabled `prodero-dev` connection is preserved and does not block installation. These are configuration checks, not connectivity tests.
+
+The installer never adopts an existing unowned `prodero` entry or launcher. For an older manual setup, back up settings, review and remove only that old entry/block yourself, then run install. For a modified owned block, preserve your edits and reconcile it with the private receipt before retrying. There is no force-overwrite flag. An intact owned older launcher can update automatically.
+
+Configuration is parsed before writes. Changes use temporary files and rename, a per-host installer lock, a pending journal and private recovery snapshots. Failed writes roll back when safe; externally changed files are never overwritten during rollback. Interrupted operations block further changes rather than guessing. Close installers/hosts, inspect the private journal and backup, restore a consistent pre-operation configuration and receipt, then remove the pending journal/lock before retrying. These protections do not guarantee power-loss durability or exclude writes by a native host between checks and rename.
+
+Recovery snapshots can contain **the entire previous host configuration, including credentials**. They are local files with mode 0600 in private state directories; do not attach them to bug reports. Errors/status do not include configuration content. Backups are retained for recovery after uninstall; remove them yourself when no longer needed. The installer does not transmit configuration or validate host authentication.
+
+## Experimental Claude limitations
+
+Claude Code 2.1.52 recognized the generated user-scope MCP server and connected to stdio in isolation. The real `prodero` model invocation could not run without login, so the adapter remains experimental. It is included in default detection/installation but is not a supported-host certification. No Claude Desktop adapter is provided.
+
+Claude Code reads global `CLAUDE.md`, but does not automatically consume project `AGENTS.md`. Prodero project initialization is unchanged. For experimental lifecycle use, review the host's native project `CLAUDE.md` import of `@AGENTS.md` yourself; installation never writes that project file. Apps rendering depends on the host; text responses remain available.
+
+## Advanced manual registration
+
+Use this only when troubleshooting or deliberately managing MCP yourself. Do not combine a manual entry named `prodero` with the managed installer. A fixed root ties the server to that project even after switching workspaces:
+
+```sh
+codex mcp add prodero -- prodero mcp --root /absolute/path/to/project
+```
+
+Hosts using JSON stdio settings can use their documented location:
+
+```json
+{
+  "mcpServers": {
+    "prodero": {
+      "command": "prodero",
+      "args": ["mcp", "--root", "/absolute/path/to/project"]
+    }
+  }
+}
+```
+
+Use the absolute installed executable if the host cannot find `prodero` on PATH. Manual MCP registration alone does not install the global launcher. A fixed server root is the security boundary: `projectRoot` may identify the same canonical directory, but cannot override it. Without a fixed root, `projectRoot` selects an exact member of the host-authorized roots; omission selects the host primary workspace or the sole root. Roots are compared using real paths, so aliases of the same project work. Absent roots capability uses only a supported local host launch context. Empty, unavailable or invalid negotiated roots fail closed. Multiple roots without a host primary require explicit selection, and authorizing a parent does not authorize independent nested projects. No arbitrary working-directory fallback or ancestor discovery is used; local Codex launch context is captured and pinned at the entrypoint. Explicit nested roots never silently select their parent Git repository: an uninitialized nested directory is rejected; an already initialized nested Prodero project retains its boundary.
+
+Native references: [Codex MCP](https://developers.openai.com/codex/mcp), [Codex global instructions](https://developers.openai.com/codex/guides/agents-md), [Claude MCP scopes](https://code.claude.com/docs/en/mcp), [Claude instructions](https://code.claude.com/docs/en/memory).
+
+## Updates and advanced project commands
+
+Everyday work happens through the connected agent. These commands are for maintenance, recovery or deliberate terminal use. See also [project recovery](RECOVERY.md).
+
+```sh
+prodero --help
+prodero status
+prodero status --root /absolute/path/to/project
+prodero check-update
+prodero update
+npm install --global @prodero/curator@latest
+prodero install
+```
+
+`check-update` reports the installed version, public npm latest version when reachable, update availability and the exact manual command. An unpublished or unreachable registry is reported as unavailable, not current. `update` only returns instructions: it does not install, stage or alter project integration. Run the npm command yourself, rerun `prodero install` to refresh any changed executable location, then restart the MCP host. Packages are installed separately from project knowledge; project access checks compatibility and presents required migrations for review; CLI `migrate` explicitly applies an update. Back up the whole `.prodero` directory before upgrading previews. Do not downgrade a project to a runtime that cannot read its schema.
+
+Use `PRODERO_RELEASE_SOURCE=none` to disable network version checks. Version checks send a request for this public package, not project content. Local manifest/check-out staging is a development-only test adapter requiring `PRODERO_DEV_UPDATE=1` and an explicit source; it is not production self-update.
+
+`status` without `--root` inspects machine integrations only. `status --root PATH` retains the explicit project status view. `init`, `sync`, `context [query]` and `prepare [task]` accept `--root PATH` or `--root=PATH`. Without it they require a Git or initialized Prodero ancestor. Unknown commands/flags and invalid roots exit non-zero. `prepare` starts a session; use the MCP lifecycle to record and close it. `sync` starts or resumes the Sync Memory options workflow and can recover pending observations, including active-session observations. Use the connected agent/App to continue its review steps. `sync-sessions` is the low-level deterministic recovery command that processes only closed sessions and leaves active sessions untouched. Normal session close/prepare learning does not require starting Sync Memory.
+
+
+For project-history questions without starting a session, use `prodero recall "why was this designed this way?" --root /absolute/project`, or ask the connected agent.
+
+The npm package is now `@prodero/curator`; the command remains `prodero`. Existing project data and host receipts keep their paths and formats. Legacy `@prodero/cli` package/checkouts remain recognized when selecting an existing runtime. If the installed package path changes, explicitly select the new installation with `--package-root` as described above; no host setting or project data is silently migrated.

package/docs/plugins.md

@@ -0,0 +1,83 @@
+# Optional installation plugins
+
+> v0.1 contract: Local/Versioned describe Git storage and sharing, not a security boundary against the connected agent. Review and approval are workflow safeguards, not authenticated human consent. The agent may create, promote and maintain Versioned files. Curator does not commit or push; users review repository changes before doing so. See [Privacy](PRIVACY.md).
+
+Dependency direction: concrete plugin → public `PluginContext` → Core services.
+Core does not import a concrete plugin or interpret its source system. LLMs and
+plugins propose semantic changes; Core alone validates and mutates durable state.
+
+The runtime scans only the installation's `plugins/` immediate child directories.
+Each has a versioned `plugin.json` and one CommonJS `.cjs` entrypoint exporting
+`{ actions: { actionName: { title, description, readOnly, run(context, input) } } }`.
+Entrypoints are trusted local code; this is not a sandbox or a package installer.
+No activation hook, project discovery write, model call or remote lookup occurs.
+Restart the server after adding/removing a directory. Registry state is derived.
+
+Minimal manifest:
+
+```json
+{"manifest_version":1,"api_version":1,"id":"hello","name":"Hello",
+ "version":"1.0.0","description":"Example optional capability",
+ "capabilities":["example"],"entrypoint":"index.cjs"}
+```
+
+```js
+exports.actions = { hello: {
+  title: "Hello", description: "Return a greeting", readOnly: true,
+  async run(context) { return { greeting: "Hello", root: context.projectRoot }; }
+} };
+```
+
+Optional `ui: { resource: "ui/dist/index.html", action: "hello" }` registers a
+self-contained MCP App resource and a generated tool. UI implementations use the
+existing MCP Apps SDK. Generic status lists contributions from the registry;
+it contains no concrete plugin menu entries. A UI build script discovers plugin
+`ui/index.html` inputs. Plugins without UI need no build step.
+
+Malformed manifests, unsupported versions, entrypoint exceptions, missing UI and
+action exceptions are isolated with plugin-specific diagnostics. Absent roots are
+normal. Removing the directory removes its actions and UI after restart; existing
+canonical knowledge remains readable without the plugin.
+
+The public API is `src/plugins/api.ts`. It exposes bounded read-only source access,
+plugin instruction assets, optional structured LLM calls, canonical state reads
+and controlled import/verification services. No arbitrary write-path API exists.
+Core uses existing knowledge/skill schemas, provenance and checkpoint transactions.
+Plans/reports are portable returned JSON, never silently written into memory.
+`context.screening.assertSafe(value)` and `context.screening.hasSecret(text)` expose
+Core's existing best-effort credential policy. The bundled importer screens full
+inputs, packets, plans, model output and responses, including excluded metadata,
+and screens plans before caching and again on replay. Sensitive source paths
+remain excluded by the existing file service; evidence validation and hashes are
+unchanged. These services do not sandbox trusted installed plugins.
+
+Distribution, registries, dependency resolution, sandboxing, hot reload and a
+generic migration UI framework are deliberately outside API v1.
+
+## Validation of the first implementation
+
+Run `npm test` and [the release gate](RELEASING.md) for the current candidate. The package ships executable JavaScript, bundled Apps, instruction assets and public documentation; TypeScript declarations are not included.
+
+Synthetic fixtures prove addability, removability, malformed/version/entrypoint/UI
+failure isolation, tool-name collision rejection, and absence of concrete plugin
+references across `src/`. Migration checks cover read-only audit, secret exclusion,
+plan integrity, stale/contradicted/uncertain classifications, Core preflight,
+source immutability, approval, deduplication, candidate/default skill behavior,
+checkpoint replay/recovery, later lifecycle ordering and cache rebuilds.
+
+The production UI handlers are exercised automatically, and a temporary browser
+fixture exercised audit → exclude → review → apply → verify through real MCP
+handlers with deterministic sampling responses. At 390px the layout had no
+horizontal overflow. This does not establish semantic quality with a live model
+or validate any company's real historical knowledge.
+
+Known v1 limits: trusted installation code is not sandboxed; audits have explicit
+coverage/size bounds; secret detection is conservative; exact same-boundary
+content deduplicates deterministically while semantic duplicates depend on the
+instruction-guided review. Both external source and repository integrity passes use the bounded exclusions below.
+Plans are portable artifacts and must be retained for replay. The UI requires an
+MCP Apps-capable host; unsupported hosts can use the same structured actions.
+
+### Bounded file integrity services
+
+`files.digest` returns `sha256-tree-v2`; `files.snapshot` uses the same bounded streaming traversal and external scope. Both exclude common sensitive paths, private Curator runtime state and Git-ignored files (including tracked matches via `check-ignore --no-index`). Limits are 20,000 files, 100MB, depth 32, 40,000 entries and 30 seconds per pass. Errors never return complete-looking partial results. Tool arguments cannot raise these ceilings. Core's separate canonical import-state snapshot deliberately includes required Local/session/checkpoint data for conflict and receipt checks. See [the importer integrity contract](../plugins/migrate_ai_studio/README.md#integrity-scope-and-limits-plugin-170) for exact scopes, Git/non-Git behavior, exceptions and compatibility.

package/docs/ui-themes.md

@@ -0,0 +1,43 @@
+# Built-in UI themes (v0.1)
+
+Appearance is a canonical project preference (`presentation.theme` in `.prodero/config.json`). The compact **Appearance** disclosure above the main App contains seven native radio choices with palette swatches. It remains mounted outside `#app`, so changing appearance neither rerenders a screen nor discards form drafts. Keyboard users can tab to the picker and use arrow keys within its radio group.
+
+- **Current / Prodero** is the default, with the original green-black gradients, lime identity, surface colors and typography.
+- **Dark Neon** is the darkest variant: almost-black foundations, graphite-black elevated surfaces and restrained ice-blue edge light.
+- **Pink Neon** uses black/plum foundations, deep wine surfaces, hot pink/magenta accents and a faint warm gradient.
+- **Blue Neon** uses midnight navy-black foundations, deep blue surfaces, electric blue/cyan accents and cold ambient light.
+- **Purple Neon** uses violet-black foundations, aubergine surfaces, violet/ultraviolet accents and a restrained purple gradient.
+- **Light** uses pale neutral surfaces, dark text and a deep green accent.
+- **System** resolves to Light or Dark Neon, preferring the MCP host's light/dark context over the browser media query. Without either signal it resolves to Prodero.
+
+## Structure
+
+`src/settings-definition.ts` holds the shared theme catalogue and validation. `src/ui/themes.ts` holds the browser controller and picker. `src/ui/themes.css` defines exact legacy semantic shade values, shared variant roles and built-in overrides. `src/ui/style.css` consumes those variables without theme branches. Numbered shades preserve the original subtle color differences; new palettes map them to a small set of primary/secondary/muted text, surfaces, borders, accent, on-accent, info, success, warning and error roles. Focus, hover, selected state, glow, graph/relationship decoration and Local/Versioned labels all use tokens. Long-form text has no added glow. New variants need a catalogue entry and token overrides, not component changes.
+
+The four neon palettes separately define page, primary, elevated and tinted surfaces; subtle and control borders; primary/secondary accents; selection, hover, focus, glow and shell gradients. Solid reading surfaces remain unlit. Semantic success/warning/error colors retain their meaning within each atmosphere. The picker swatches reflect each foundation. Neon-only selectors leave Prodero and Light unchanged.
+
+The original theme's low-emphasis text colors are deliberately unchanged. New themes use higher-contrast muted text and separate semantic colors; layer labels retain their textual names so color is not the only distinction.
+
+## Persistence and host boundaries
+
+The selected ID is saved for the current project through `prodero_config_set`, using the same canonical validation and atomic storage as chat updates. The old global browser storage key is ignored because it cannot be attributed to a project. Missing project preferences use Current / Prodero. Failed saves retain the last applied theme and explain the failure. Separate projects can display different themes simultaneously; late saves cannot recolor another project.
+
+Browser preference changes are observed using `matchMedia`; host preferences use `getHostContext()` and `onhostcontextchanged`. Partial host notifications do not clear a known preference. Explicit themes ignore both signals. A host that reports no system preference falls back to browser detection. Separate plugin-owned MCP Apps have independent styles and are outside the main App's document; this feature does not impose styles on third-party plugin documents.
+
+## Verification
+
+Run `npm run build`, `npm test`, and the explicit UI typecheck:
+
+```sh
+npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --lib ES2022,DOM,DOM.Iterable --strict --skipLibCheck src/ui/main.ts
+```
+
+Focused controller/default-style tests are included in `npm test`. Browser checks use Playwright with Chromium available in the development environment:
+
+```sh
+node --test test/themes.browser.mjs
+```
+
+If Playwright is provided by the host runtime instead of local dependencies, set `PRODERO_PLAYWRIGHT_MODULE` to its importable module path. Optional `PRODERO_THEME_SCREENSHOTS` names an existing output directory. The browser test uses the production UI modules with only the MCP bridge stubbed, exercises all themes on status, knowledge, lifecycle, promotion and skills, tests keyboard selection and live System changes, checks text/semantic contrast and narrow layouts, compares default screenshots against the pre-theme stylesheet, and uses an initialized Git fixture to check that theme saves change canonical configuration without changing knowledge or other canonical artifacts. Browser storage is no longer used. The optional browser suite is separate from the full Node test suite.
+
+The browser suite also verifies distinct actual page, panel, card, border and gradient colors for all four neon themes with no active controls, surface elevation, contrast across all surface levels, hover/focus tokens and absence of content glow. Screenshot output includes `all-themes.png` and `neon-comparison.png` for side-by-side reading-surface review.

package/instructions/AGENTS.md

@@ -0,0 +1,33 @@
+## Prodero Project Intelligence
+
+Apply these instructions to the current user workspace. The directory containing this document is the Prodero installation, not the project root.
+
+This project uses Prodero for persistent project knowledge, session memory, and reusable project skills.
+
+## Prodero UI
+
+When the user says `prodero` (ignoring surrounding whitespace and case), `open prodero`, or `show prodero`, immediately call prodero_config_get for the current workspace. If presentation.mode is text, call prodero_text with tool=prodero_open; otherwise call prodero_open. Pass the same projectRoot to config_get and the selected operation (inside arguments for prodero_text). Do not ask what the user wants to do with Prodero. The selected operation opens Project Intelligence and loads Bootstrap Context.
+
+`open prodero` and `show prodero` have the same meaning. Use `prodero_status` only for a lightweight read-only status check. Do not inspect repository files first, open README.md, explain Prodero, or search documentation as a substitute for opening the interface.
+
+For requests to show Prodero settings, project settings, or Prodero config, call prodero_config_get and show its friendly settings view. For project preference changes use prodero_config_set: text-only/text mode → presentation.mode=text; switch back to UI → presentation.mode=ui; automatic presentation → presentation.mode=auto; blue/purple neon → presentation.theme=blue-neon/purple-neon; context budget 8000 → context.max_tokens=8000. These are canonical project settings, never knowledge entries. Resolve the current project on each call. Read effective settings when choosing the text gateway; do not rely on a previous project or conversational preference.
+
+For knowledge-list requests in Claude Code, prefer prodero_text with tool=prodero_knowledge unless the user explicitly requests a graphical view. This is a one-off display choice, not a project setting change. When showing knowledge lists in chat, prefer the supplied fenced ASCII table with +, - and | borders; preserve its columns and page-local numeric row keys when translating. Knowledge rows use 1 through N, and action commands below the table continue at N+1. Resolve a standalone number through the exact numberedActions binding from the latest displayed table/menu. knowledgeRows also binds row numbers to exact record IDs; never infer IDs or reuse an older page. Show complete record text when an individual record is requested. In knowledge-detail replies, keep the original, any translation and record metadata together, then preserve a separate ------------- line before service hints about editing, history, approval and available actions. Service hints are not part of the knowledge or its translation. When suggesting next actions in chat, show a numbered Markdown list starting at 1 (or N+1 after a knowledge table with N rows), with one command per line and a blank line before the list. Tell the user they can reply with a number or the command name. Preserve the displayed order and exact numberedActions bindings when translating. A standalone positive integer selects only that item from the latest action menu actually shown in this conversation for this project; never use array positions in availableActions, an older menu or another conversation. If the number is out of range, the menu is missing, or a pending question expects a numeric value rather than a menu choice, clarify instead of guessing. Keep menu bindings only in conversation context, never project settings or knowledge. Route selected covered tools through prodero_text with the exact bound arguments; call other bound tools directly. A numeric selection is navigation or an action request, never explicit approval: for an approval-marked action show the exact proposal and request explicit confirmation before mutation or publication. In ordinary Open and lifecycle replies, omit display mode, theme and tool-routing commentary. Saved presentation settings, resolved mode and App metadata are not evidence that the user saw a graphical interface; do not claim a UI was displayed from those fields. Discuss mode or theme only when the user asks about settings or presentation troubleshooting. Use prodero_config_get for the current project before choosing a presentation route. For a project in text mode, call prodero_text (default tool prodero_open); pass original arguments in arguments. Apply this routing to every covered lifecycle and review operation, including prodero_prepare and prodero_session_close, and to available actions. Do not call the App-attached original with presentation=text: it can leave an empty host container. The gateway has no App attachment. Show human-readable content and actions in chat. Natural requests to change display mode update presentation.mode through prodero_config_set; do not retain a sticky conversation-only preference or record settings as knowledge. A one-off request to show a response as text may use prodero_text without changing config. Standard MCP Apps capabilities inform auto mode only; never infer a device from client metadata. Original tools retain static App descriptors even if they return text. For UI calls, generate one opaque presentationGroup per conversation (or use a supported host-provided conversation ID) and reuse it across Prodero UI tools, including open, prepare and session_close, so older cards can collapse. Never use a project path or a shared MCP connection ID as the group; never reuse it in another conversation. Keep it ephemeral, not in project settings or knowledge. Keep the existing review and approval workflow before mutations or promotion. v0.1 trust model: Local Knowledge is Git-ignored working state, not a security boundary against the connected agent. Versioned Knowledge is Git-shareable project state; the agent may create, promote and maintain it. Review/preview/approval steps are workflow safeguards, not authenticated human authorization; approved=true does not prove human consent. Curator does not commit or push. Users must review repository changes before committing or pushing.
+
+Before answering questions that may depend on project history, previous decisions, implementation details, or project-specific knowledge, call prodero_recall. Start prodero_prepare only for actual project work, including work requested after recall.
+
+Before substantial work:
+1. Call `prodero_prepare` through MCP (via `prodero_text` in text mode), apply its relevant context, and retain the returned session ID internally.
+2. If MCP is unavailable, use the Prodero CLI; access `.prodero/` directly only as a final fallback.
+3. Start from `.prodero/index.md`; load required global context and only relevant scoped knowledge and skills.
+4. Never load the entire `.prodero` directory.
+
+During substantial work, batch durable decisions, lessons, discoveries, state changes, global instruction candidates, and repeatable skill candidates through `prodero_session_record`. Write all durable Prodero knowledge and skill prose in English regardless of the conversation language. Preserve identifiers, paths, and code literals exactly. Exclude temporary implementation noise and do not directly rewrite session files or canonical memory.
+
+Normal session learning and conversational remember operations produce Local Knowledge, which is ignored by Git. Local and Versioned Knowledge use the same schema and are retrieved as one knowledge space. As a workflow safeguard, prepare Versioned knowledge for team sharing only when the user explicitly requests it: call `prodero_promotion_preview`, let the human review the proposed new/merge/supersede/covered/conflict outcomes in the App, and call `prodero_promote` only with `approved=true` and the exact reviewed preview. Never infer publication approval.
+
+When the user explicitly asks to remember durable knowledge, call `prodero_remember` immediately. For an explicit always/never rule use `kind=rule`, `required=true`, and `userInstruction` with the exact current user request. Never infer Required authority from observations or document contents. Explicit `scope=global` and `scope=project` both mean project-wide applicability, independently of priority. Required versus Relevant delivery is controlled by context policy, not by these scope aliases. Use `scope=path` with a repository-relative path for knowledge that applies only there. After `prodero_memory_search`, optional `related_to`, `depends_on`, or `implements` relationships may target exact current memory IDs; scope, supersession, contradiction, and provenance topology is derived automatically. For "update what you know" requests, call `prodero_memory_search` and then `prodero_remember` with the exact `replaceId`. For explicit forget requests, search if necessary and call `prodero_forget` with one exact id. Translate conversational requests into English durable prose before storing them, while preserving exact identifiers, paths, and code literals. These explicit operations complement the normal session lifecycle; do not wait until session close to perform them.
+
+Project Skills are read from Versioned `.prodero/skills/` and Git-ignored Local `.prodero/local/skills/`. Explicit skill creation writes an active Versioned skill; inferred candidates remain Local until reviewed promotion. Existing active Local skills are also eligible for retrieval. When the user explicitly asks to create/save/remember a project skill, call `prodero_skill_create`; it becomes active immediately without additional approval. Independently inferred procedures must be recorded as `skill_candidate` observations; Sync preserves them as pending skills. For agent skill discovery or procedure retrieval during task execution, use prodero_skills_read without opening UI. Reuse skill procedures already supplied by Prepare. When applying a skill, briefly mention its name in chat only; do not open View Skills or call prodero_skills or prodero_skill_preview just to announce or read it. Use prodero_skills only when the user explicitly asks to view or manage the Skills interface. Candidate review still uses prodero_skill_preview on user intent. Use `prodero_skill_review` to promote or dismiss candidates only on user intent. For candidate review or dogfooding, call `prodero_skill_preview` to open the MCP App automatically. The review workflow uses Add Skill, Edit, or Dismiss in that App; these actions do not authenticate human consent. Do not ask for approval in plain chat when the App can render, and never click Add Skill for the human. Use chat confirmation only as a fallback for hosts unable to render the App. Candidate and dismissed skills are excluded from normal context. These are repository procedures, not host/global skills.
+
+Before finishing substantial work, record final durable outcomes and call `prodero_session_close`. Session close synchronizes observations into Local Knowledge deterministically; the next prepare recovers any pending synchronization. Sync Memory is a separate user-initiated workflow for transforming and sharing memory. Use prodero_sync to analyze, then prodero_memory_sync to select and process one bundle at a time. Never initiate it from session close. No additional work session is needed for this workflow. Clean selected Local transformations may apply. Keep the exact-preview review step for Versioned changes, promotion and semantic limitations. This is a workflow safeguard, not an authenticated authorization boundary.

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "@prodero/curator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Local-first project intelligence and memory for coding agents.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "prodero": "./bin/prodero"
+  },
+  "files": [
+    "bin/prodero",
+    "dist/**/*.js",
+    "dist-ui/index.html",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "ARCHITECTURE.md",
+    "prodero.release.json",
+    "instructions/AGENTS.md",
+    "docs/PRIVACY.md",
+    "docs/RECOVERY.md",
+    "docs/MIGRATIONS.md",
+    "docs/KNOWLEDGE-SCHEMA-V2.md",
+    "docs/KNOWLEDGE-AUTHORITY.md",
+    "docs/APPLICABILITY.md",
+    "docs/IMPORTER-CURATION.md",
+    "docs/CURATION-APP-REVIEW.md",
+    "docs/CURATION-CLAUSE-REFINEMENT.md",
+    "docs/COMPATIBILITY.md",
+    "docs/CONTEXT-SELECTION-V2.md",
+    "docs/RELEASING.md",
+    "docs/hosts.md",
+    "docs/plugins.md",
+    "docs/ui-themes.md",
+    "plugins/*/*.cjs",
+    "plugins/*/plugin.json",
+    "plugins/*/README.md",
+    "plugins/*/instructions/*.md",
+    "plugins/*/ui/dist/index.html"
+  ],
+  "scripts": {
+    "build": "npm run build:server && npm run ui:build",
+    "build:server": "node scripts/clean-server.mjs && tsc -p tsconfig.json && npm run build:instructions",
+    "ui:build": "vite build && node scripts/build-plugin-ui.mjs",
+    "mcp:build": "npm run build",
+    "mcp:dev": "./bin/prodero mcp --dev",
+    "dev": "npm run --silent mcp:dev",
+    "playground": "node --import tsx scripts/playground.ts",
+    "benchmark:memory": "node --import tsx scripts/memory-benchmark.ts",
+    "test": "node --test --test-concurrency=1 test/*.test.mjs",
+    "prepack": "npm test",
+    "pretest": "npm run build",
+    "release:gate": "node scripts/release-gate.mjs",
+    "build:instructions": "node --import tsx scripts/build-agent-instructions.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "jsonc-parser": "^3.3.1",
+    "smol-toml": "^1.9.0",
+    "zod": "^3.25.0",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.0",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  },
+  "engines": {
+    "node": ">=22.14.0 <23"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prodero/curator.git"
+  },
+  "keywords": [
+    "mcp",
+    "agents",
+    "project-intelligence",
+    "memory",
+    "codex",
+    "claude-code",
+    "developer-tools",
+    "prodero"
+  ]
+}

package/plugins/migrate_ai_studio/README.md

@@ -0,0 +1,101 @@
+# AI Studio → Prodero
+
+> v0.1: `reviewed`, `approvedPlanId` and skill activation selections are caller-supplied workflow safeguards, not proof of human consent. Import writes Git-shareable knowledge/skills, including candidate skills. Curator does not commit or push; review the repository diff before doing so.
+
+This optional plugin distills durable engineering knowledge; it never copies a
+legacy tree or modifies `.ai-studio/`. Remove this directory and restart to remove
+its capabilities. Core has no special interpretation of the source system.
+
+Open **Plugins → AI Studio Migration** in Prodero or call the generated
+`prodero_plugin_migrate_ai_studio` tool. All stages are also available through
+`prodero_plugin_action` with `pluginId: "migrate_ai_studio"`.
+
+1. `detect`: cheap bounded metadata inventory, no model calls or writes.
+2. `estimate`: the App's default opening action. It reads and hashes locally,
+   reports the structured memory files selected for extraction, and makes no model
+   call or filesystem write.
+3. `audit`: locally parses structured `Decision`, `Reason`, `Impact`, `Constraint`,
+   `Correction`, `Guard pattern`, `Workflow note`, and `Test-quality note` blocks
+   from `.ai-studio/runtime/memory/`. Handoffs, epic runs, sessions, logs,
+   transcripts, indexes, and unstructured execution history are excluded. The
+   result opens directly as a reviewable plan without a model request or chat
+   prompt. No filesystem writes.
+   Optional `sourcePaths` (max 36) / `repositoryPaths` (max 16) narrow or deepen
+   evidence. Defaults prioritize source areas, never semantic destinations.
+4. `plan`: retained for optional advanced semantic integrations that explicitly
+   request `audit` with `{semantic:true}` and have negotiated server-side MCP
+   sampling. It is not used by the default App workflow.
+5. `review`: submit `{plan, decisions:[{id,include,activateSkill}]}` with one
+   decision per item. Conflicted/stale/uncertain/duplicate entries stay excluded.
+   Skills default to candidates; only explicit human selection activates them.
+6. `apply`: submit `{plan, approvedPlanId:plan.planId}` for the reviewed plan.
+   Never approve skill activation on the user's behalf. Apply consumes the exact
+   sealed content, performs no model call and rejects changed evidence/state.
+7. `verify`: submit `{plan, receipt, semantic:true}`. Mechanical checks compare
+   source/repository hashes, included item hashes, excluded IDs and unrelated
+   canonical state. Optional LLM verification checks semantic quality again.
+
+Plans and reports are portable versioned JSON returned by tools and exportable in
+the App. Keep the reviewed plan to replay it. They are not hidden canonical memory
+or required caches. Apply stores a receipt in the existing immutable checkpoint;
+Semantic imports retain source file/line/hash provenance. Default local imports
+use the source references only for preflight validation and persist only
+plugin/version/plan provenance, so removing `.ai-studio/` later does not leave
+dead source links in canonical knowledge. Local extraction also removes direct
+`TASK-*` and `EPIC-*` identifiers and replaces `.ai-studio/...` paths with a
+portable description before Review.
+
+The App keeps the validated plan inside the MCP process. Review, Import, and
+Verify submit only `planId` plus their small action-specific fields instead of
+round-tripping the complete structured plan through the App bridge. Restarting
+MCP deliberately expires an open Review and requires a fresh Audit.
+The MCP App resource URI includes the plugin version so Codex cannot reuse a
+stale cached migration interface after an upgrade.
+Reapplying a committed plan returns the existing receipt. Same-boundary normalized
+content is deduplicated, without overwriting existing knowledge. Existing dismissed
+or candidate skills are never silently activated during deduplication. Knowledge
+rules use Prodero's `instruction` category; AGENTS.md is never rewritten.
+
+Apply uses Core's existing writer lock and recoverable checkpoint-last journal.
+On interrupted application, retry after resolving any reported concurrent change;
+the journal supports recovery. A changed project requires a new audit/review.
+Verification reports later edits as changes rather than attributing causation.
+
+Local extraction is bounded to 80KB of structured memory and 60 review items.
+Large histories are skipped and never sent to a model. Streaming scoped digests cover eligible
+source/repository files without retaining source contents in the plan. Sensitive paths, private
+Curator runtime stores and Git-ignored files are outside external integrity scope; verification
+does not claim that these excluded files are unchanged. See the integrity contract below.
+The default audit reports zero model tokens. Optional semantic mode retains local
+`ceil(UTF-8 bytes / 4)` estimates; monetary cost depends on the host model.
+Uninspected/omitted coverage is explicit.
+Symlinks and special files are rejected. Sensitive filenames, private keys, common
+credential patterns and binary data are excluded before model calls. This is a
+conservative secret detector, not proof that arbitrary text contains no secrets;
+review remains necessary. Semantic validity also depends on the model and evidence.
+
+Instructions live in `instructions/{audit,classify,migrate,verify}.md` because
+judging durable truth, stale claims and reusable procedures is semantic work.
+Code owns schemas, bounded reads, hashing, review consistency, destination validation and
+writes. Default local extraction uses conservative label/text heuristics for category
+and applicability. The optional semantic path uses the instruction contracts above;
+neither path treats imperative wording as user authority.
+
+No source deletion, remote distribution, marketplace, generic migration DSL or
+migration of other agent systems is implemented.
+
+## Integrity scope and limits (plugin 1.7.0)
+
+Semantic ingestion and integrity hashing have different scopes. Semantic ingestion keeps its existing bounded source selection, text/binary/credential screening and exact evidence hashes. An explicitly imported legacy workspace may be Git-ignored; selected safe evidence from it can still be ingested and is independently revalidated on review/apply and verification.
+
+External integrity digests cover the eligible `.ai-studio` tree and the remaining repository separately. They exclude the common Curator sensitive-path policy, private `.prodero` stores, Git metadata, dependencies/build/cache trees and explicit exclusions. Repository-root hashing excludes `.prodero` and `.ai-studio` (each has its own purpose-specific check). Git's `check-ignore --no-index` supplies repository, nested, info/exclude and global ignore semantics; matching files are excluded even if force-tracked. Ignored directories are pruned before traversal. No valid Git repository means there is no Git ignore scope; fixed and sensitive-path exclusions still apply. Git must be available; Git inspection errors fail closed rather than silently disabling ignore rules.
+
+Core separately snapshots an allowlist of canonical Curator stores to detect concurrent changes and verify receipts: config/index, Versioned and Local memory/skills/archive, sessions and checkpoints. This bounded internal snapshot intentionally reads Git-ignored Local state; it does not hash reviews/reasoning, cache, transactions, backups, migration history or arbitrary additional stores or atomic `*.tmp-*` leftovers. It is not exposed as an external `files.snapshot` override.
+
+Each digest/snapshot pass has hard ceilings: **20,000 files, 100,000,000 total bytes, depth 32** (root is depth 0), **40,000 examined directory entries**, and a **30-second deadline**. The count/byte limits reuse the former snapshot ceilings; depth/entry/time limits bound directory-heavy or slow work. Hashing streams in 64KiB chunks and checks stat identity/size/mtime/ctime before and after reads, plus directory metadata before/after traversal. Git input/output is bounded to 4MB/8MB per batch. Exceeding a limit, cancellation, unsupported entries or detected changes returns an error, never a successful partial digest. Narrow the actual tree or Git-ignore unnecessary generated artifacts, then rerun Audit; changing semantic selection alone does not increase integrity limits.
+
+Limits apply to each pass, not to an entire multi-step workflow. A gather performs two external digests and one canonical snapshot, so at most 60,000 file hashes / 300MB are admitted across those passes; review/verify repeat their own bounded checks. Deadlines cancel Git subprocesses and file streams and are checked during traversal; a blocked OS metadata syscall cannot be forcibly interrupted. Filesystem checks detect observed drift, not an atomic snapshot of a concurrently edited whole repository.
+
+Ordinary non-sensitive, non-ignored files outside the selected semantic evidence (including binary files and unselected legacy history) are intentionally hashed to detect unrelated edits; they are not sent to the model. Content-only credentials in otherwise ordinary filenames may be read for hashing: path screening is best-effort, and detecting arbitrary secrets would itself require reading the file. Git also consults its configuration/ignore metadata. Excluded files are not covered by integrity claims.
+
+Digest format is `sha256-tree-v2`. Plans from plugin 1.6.0 or earlier require a new Audit/review; old whole-tree hashes are not compared as if they used this scope. Existing data/receipts are retained; older receipt verification may report scope differences. No source or user file is deleted or untracked.