@prodero/curator 0.0.0-stage → 0.2.0

package/docs/RECOVERY.md

@@ -0,0 +1,58 @@
+# Storage recovery
+
+Canonical knowledge, sessions, skills and checkpoints are durable project data. Normal learning and inferred proposals remain in ignored storage; the promotion review workflow writes Git-shareable Versioned Knowledge. Review/approval is a workflow safeguard, not human authentication; Curator does not commit or push. See [Privacy](PRIVACY.md).
+
+| Location | Role | Safe to delete as cache? |
+| --- | --- | --- |
+| `.prodero/memory/`, `local/memory/`, `sessions/`, `skills/`, `local/skills/`, `checkpoints/`, `config.json` | Canonical data | No |
+| `.prodero/.cache/` | Rebuildable memory/session indexes and graph | Yes, after old-runtime migration backups have been relocated as described below |
+| `.prodero/index.md`, `local/index.md` | Generated routers | Rebuildable; root router may include Local skill metadata. This repository ignores it; inspect other projects before sharing |
+| `.prodero/.transactions/` | Writer lock, pending Sync/migration journal | No |
+| `.prodero/.backups/` | Migration recovery snapshots, excluded by root rules and its own `.gitignore` | No |
+| `.prodero/.migrations/` | Migration history, excluded by root rules and its own `.gitignore` | No |
+
+A clone or worktree normally has no ignored `local/` or `.cache/`. Prodero recreates missing runtime directories without rewriting tracked placeholders. It does not reconstruct lost Local Knowledge: deleting `local/` from an existing working tree deletes canonical local data, not a cache.
+
+Runtime setup also upgrades missing Git-ignore rules in existing projects before new runtime writes. Sessions/checkpoints are excluded by directory contents, not filename extensions, while their root `.gitkeep` placeholders remain trackable. Atomic and interrupted-write remnants stay ignored, including `*.tmp-*` beside Versioned files. This does not delete recovery artifacts, change atomic-write/recovery behavior, or untrack existing user files.
+
+## Invalid canonical files
+
+LF and CRLF are supported. Modern knowledge, session and skill metadata is validated, including IDs, lifecycle state and timestamps. Unknown statuses, stripped modern metadata, invalid configuration and malformed checkpoints produce file-oriented diagnostics instead of active defaults. Deliberately supported legacy Markdown remains readable; old date-ID `checkpoint-ready` sessions are recognized explicitly. Files are not silently repaired or rewritten merely because they were read.
+
+Correct a damaged canonical file from Git or a known backup after stopping writers. Do not remove it as a cache fix. Prodero rejects symlinks in its storage paths and IDs that could escape their directory; replace unintended links with the intended ordinary directories only after inspecting them.
+
+## Interrupted Sync
+
+Both deterministic and assisted Sync validate a complete write plan, persist `.transactions/pending.json`, then apply atomic file replacements with the immutable checkpoint last. The next Sync recovers that journal before processing more evidence. `prepare` runs this recovery through automatic Sync. A crash after the checkpoint but before journal cleanup is also recoverable and does not process the same snapshot twice.
+
+To recover, keep `.transactions/` and canonical files intact, stop competing writers, and run `prodero sync-sessions --root=/absolute/project` or ask the agent to prepare the project. Missing or structurally invalid cache entries rebuild from canonical data. Deleting `.cache/` does not delete the Sync journal.
+
+If a canonical file was independently edited after the journal was prepared, recovery stops with the affected path and preserves the journal. Inspect the file and its journal before/after hashes; restore the intended preimage or already-applied result before retrying. Never discard the journal merely to clear an error.
+
+## Interrupted migration
+
+Migrations use the same per-worktree writer exclusion as Sync and session writes. All supported migration steps and canonical input are checked before applying a migration; each attempt has a complete recovery snapshot. The schema is written only after the steps, post-validation and cache invalidation succeed.
+
+Backups now live under `.prodero/.backups/schema-<version>-<id>/`. Existing `.cache/migration-backups/` from older runtimes are relocated into `.backups/legacy-cache-<id>/` when initialization/preparation/migration next accesses the project. Run one of those operations with the hardened runtime before deleting an old runtime's cache if it contains recovery backups.
+
+A failed migration restores its snapshot and reports its backup path. A process interruption retains `.transactions/migration.json`. Open and Prepare present a recovery action before normal work. Approving recovery restores the snapshot; the next plan offers the update again. Explicit CLI initialization retains its legacy recovery behavior. This also handles a rollback interrupted while restoring `config.json`. New session writes fail explicitly while a migration recovery journal remains, so a later rollback cannot erase an acknowledged observation.
+
+If automatic restoration fails, stop all Prodero writers and retain both the journal and its referenced backup. Restore the snapshot's `config.json`, `index.md`, `memory/`, `local/`, `sessions/`, `skills/`, `archive/` and `checkpoints/` together, preserving their original presence/absence. Do not mix snapshots. Verify the result before clearing the migration marker and retrying. Never copy an uninspected or symlinked backup over project data.
+
+## Concurrency and limits
+
+Session creation, record and close share a filesystem lock across processes. Session mutations wait up to five seconds for a writer; a timeout reports failure, never success. Acknowledged observations remain in the file, and a closed session cannot be reopened by a late record. An empty repeated close remains successful; repeated close with nonempty final entries is explicitly rejected, so callers should inspect the session after an uncertain response rather than replay that final batch blindly.
+
+A dead PID owner can be reclaimed. Acquisition, owner publication, stale-owner inspection/removal and release share the short-lived `.transactions/lock-recovery` transition guard; the canonical operation runs outside that guard while retaining its writer lock. Release waits independently for up to five seconds for the guard and reports failure if cleanup cannot complete, rather than acknowledging success with an uncertain release.
+
+An ownerless/invalid lock or interrupted lock-recovery guard fails conservatively: after stopping all writers, inspect `.transactions/lock` and `.transactions/lock-recovery` before removing stale lock directories. PID reuse is intentionally handled conservatively rather than risking deletion of a live owner's lock. Do not remove the guard while a writer or recovery contender remains active.
+
+These guarantees are verified with local filesystem process-crash, injected I/O-error and multiprocess tests. They do not provide a multi-file snapshot to unrelated readers while a journal is being applied, nor protection against hostile processes replacing the directory topology during filesystem operations. Network filesystems and sudden hardware/power loss have not been certified. Do not edit storage concurrently with migration/recovery.
+
+Migration Foundation adds independent knowledge compatibility, staged transforms, backup integrity, diagnostic history and resumable Open/Prepare actions. See [Migration Foundation](MIGRATIONS.md).
+
+### Private recovery permissions
+
+On POSIX platforms, new migration backups, staging trees, history, transaction journals and locks use owner-only directories (`0700`) and files (`0600`), including interrupted-write artifacts. Runtime setup tightens existing private store roots without recursively chmod-ing their children; existing files are tightened when checked/accessed or replaced. Do not interpret this as a historical cleanup or ACL audit. Symlinks, multiply linked files and another owner's data are not permission-repair targets.
+
+Migration backups preserve shared-file mode metadata separately from their private content copies. Successful commits preserve existing shared target modes; rollback restores saved shared modes (older backups use their original source modes). Versioned stores are not made private merely because they passed through staging. Curation simulations live beneath the private, ignored `.cache` tree and are removed by the normal simulation cleanup. Windows uses native ACL behavior rather than POSIX chmod.

package/docs/RELEASING.md

@@ -0,0 +1,98 @@
+# Release candidate gate
+
+From a clean checkout on Node 22.14+ (22.x):
+
+```sh
+npm run release:gate
+```
+
+## CI tiers and local commands
+
+| Trigger / command | Tests | Pack and doc links | Installed-artifact checks |
+| --- | --- | --- | --- |
+| Branch push or pull request | Ordinary suite, Ubuntu / Node 22.14.0 | Always | Required except for explicitly documentation-only changes |
+| Any tag push or `workflow_dispatch` | Full suite, Ubuntu/macOS × minimum/latest Node 22 | Always | Always |
+| `npm run ci:fast` | Ordinary suite | Always | Omitted |
+| `npm run ci:fast -- --integration` | Ordinary suite | Always | Included |
+| `npm run release:gate` | Full suite | Always | Included |
+| `npm test` | Full suite after build | Not a package gate | Not a package gate |
+| `npm run test:fast` | Ordinary suite after build | Not a package gate | Not a package gate |
+
+Before creating a release, manually dispatch **Release gate** on the intended
+commit and verify all four jobs against that exact SHA. A tag push also runs the
+full matrix; neither check publishes a package or creates a GitHub release.
+A successful fast run alone does not certify a release.
+
+`test/scale/` explicitly owns the seven large-fixture tests (10,000-memory
+intelligence, context/status/discovery scales, 20,100-file importer boundary and
+retention histories). Their assertions and fixture sizes are unchanged. The
+recursive runner includes every `*.test.mjs` below `test/` in full mode; every
+suite outside `test/scale/` defaults to ordinary, including newly added suites.
+Optional `*.browser.mjs` checks remain separate, as before. Fast mode runs at most
+two test files concurrently; full mode retains one. Both fail on any selected
+test failure. Partition and workflow-policy regression tests run in both modes.
+
+Path classification is conservative: only the named top-level Markdown files,
+LICENSE, `docs/*.md` and `docs/images/*.png` may omit installed-artifact checks.
+Any other path (including core, installer, MCP, UI, plugins, managed instructions,
+package manifests, workflow, runner or tests), mixed changes, missing/zero base,
+or diff failure requires them. Both sides of renames are classified. PRs compare
+the base SHA with the checked-out merge result; pushes compare the previous SHA
+with HEAD. All branch/PR changes still run ordinary tests and package validation.
+
+Superseded runs are cancelled only within the same branch or PR group. PR groups
+use PR numbers to avoid collisions between fork branch names. Manual and tag
+runs use unique run IDs and cannot cancel, or be cancelled by, branch/PR runs.
+
+The gate copies tracked working files plus non-ignored new files into a clean
+temporary checkout (never node_modules/dist), runs `npm ci`, builds **once**, then
+packs and validates package resources, secret/path screening and documentation
+links **before** running tests. It skips npm pack lifecycle scripts only because
+the gate explicitly controls build/tests; successful completion requires both.
+Ordinary `npm pack` still runs the full tests through prepack.
+
+When integration is required, the gate installs that same tarball into a separate
+prefix with production dependencies only, takes the build checkout offline and
+runs the existing standalone smoke runner against the installation. CLI, stdio
+MCP, bundled resources, the knowledge lifecycle, Git boundaries, restart and
+synthetic manual upgrade preservation remain checked. The smoke runner's
+synthetic patch version is only an isolated test fixture, never a publication.
+
+`result.json` records mode, whether integration ran, total elapsed time, each
+child-command duration, artifact path and SHA-256. CI uploads these results and
+logs with the tarball. Measure fast and full runs separately; runner performance
+and the filesystem-heavy fixtures make local and remote times different.
+
+For host-integration verification, use a fresh temporary directory outside the real user home, an isolated HOME and Codex/Claude/XDG configuration, and no inherited host registrations. Keep custom `PRODERO_GATE_OUTPUT` paths outside real-home ancestry: normal workspace checks inspect ancestors and can correctly report `HOST_SCOPE_CONFLICT`. Never disable those checks or alter real settings to make a smoke test pass.
+
+CI allows 30 minutes for the fast job and 45 minutes per full matrix job. Child-command output is streamed to the console and written continuously to evidence logs, so cancellation retains partial test diagnostics. The limit remains finite; a timeout is not a passing check.
+
+Gate outputs and the tarball remain in the printed temporary directory for inspection. Nothing is published. Full CI repeats the gate on macOS/Ubuntu and the declared minimum/latest Node 22. Remote CI results must actually pass before those targets are certified.
+
+A protocol runner is not a real host. Independently connect a primary host to the **installed artifact** in a synthetic Git project, run open/init/prepare/record/close/next prepare/remember/search/edit/restart, inspect tool results and Git status, and record host/runtime/artifact versions. Review promotion outcomes and approve only the intended synthetic fixture publication. Apps rendering needs its own host check.
+
+## Install the artifact for review
+
+For an unpublished candidate, install the reviewed tarball into an isolated prefix rather than requesting its version from the registry. The current candidate version is 0.2.0; this command is an example for a separately authorized isolated environment, not a request to replace the working installation:
+
+```sh
+npm install --global --prefix /absolute/isolated/prefix --omit=dev --ignore-scripts /absolute/path/prodero-curator-0.2.0.tgz
+```
+
+Use the isolated host environment described above for automated verification. For a deliberate real-host check, review the installer’s configuration changes and restart the selected coding agent. Open a synthetic project and type `prodero`. The tarball includes the compiled server, Apps and plugin resources; no source checkout or development dependencies are needed.
+
+## Final human publication checklist
+
+1. Finalize version, changelog/date and README in the intended release tree before freezing the candidate. Independently audit it, review diffs, run the full gate on the exact committed tree and obtain green declared CI matrix runs. Record artifact SHA-256 and primary-host evidence. Any packaged-content edit afterwards requires a new tarball and matching checks.
+2. Review the intended public Git tree **and history** for private content. Ignoring runtime files today does not remove old commits. Decide explicitly what history to publish; never rewrite it automatically.
+3. Confirm ownership of npm scope `@prodero`, package/repository identity `@prodero/curator` / `prodero/curator`, and permission to release. A registry 404 does not establish scope ownership.
+4. Create/configure the intended public repository only with explicit approval. Enable Issues and private vulnerability reporting; verify the links and update any identity/channel changes in docs and package metadata.
+5. Confirm candidate version `0.2.0`, MIT license, final changelog date, preview limitations, README registry example and exact artifact contents. If any edit is still needed, return to step 1 and certify the new artifact. Obtain explicit approval for publication.
+6. Authenticate npm with the account's required 2FA/provenance policy. Publish the **reviewed tarball**, not an unreviewed rebuild: `npm publish /absolute/path/prodero-curator-0.2.0.tgz --access public`.
+7. Verify external `npm install --global @prodero/curator@0.2.0`, `prodero --version` and `prodero check-update`. Only with separate approval create/push the `v0.2.0` tag and release notes or announcements.
+
+The automated gate does not publish or push and does not change the source repository history. It creates an isolated disposable test commit in its temporary checkout. Package upgrades do not move project knowledge. Back up the full `.prodero` directory before preview upgrades; `.cache` is disposable, migration recovery backups are not.
+
+## Terminal updater acceptance
+
+Test the installed `prodero update VERSION` in an isolated prefix after explicit terminal acknowledgment, including non-TTY refusal/`--yes`, actual npm failures and fresh CLI/MCP verification. Record artifact/hash/version, scripts policy and unchanged synthetic project/host state. Published-release upgrade, fixture-modified candidate→published transition and same-version behavior are distinct claims. A direct npm install or the existing synthetic patch smoke does not alone exercise the updater. Never use the 0.0.0 placeholder as a functional baseline or update the maintainer’s working npm installation during automated checks. Chat/MCP checks must assert instruction-only behavior even with development release sources.

package/docs/hosts.md

@@ -0,0 +1,152 @@
+# 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`: readable machine integration status, including the installed version and each host's detection, MCP, launcher and configuration state. It does not discover or access a project, even when run inside one.
+- `prodero status --root PATH`: readable status for that existing project: initialization, knowledge, sessions, skills, checkpoints, attention counts and the bounded update check. It does not initialize, migrate, synchronize or repair the project.
+- Add `--json` to either status command for scripts. The format is explicit and does not depend on whether stdout is a terminal or a pipe.
+
+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
+
+Historical Claude Code 2.1.52 checks verified generated user-scope registration and an isolated stdio connection but stopped at login. On 2026-10-23, native Claude Code 2.1.302 passed the installed 0.2.0 candidate's text lifecycle, persistent retrieval, Local editing and promotion preview in a disposable project using existing client authentication and invocation-only MCP configuration. That run did not recertify global installer registration, Claude Desktop or graphical Apps. The adapter remains experimental; see the exact candidate and evidence boundaries in [Compatibility](COMPATIBILITY.md). 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 status --json
+prodero status --root /absolute/path/to/project --json
+prodero check-update
+prodero update
+prodero update 0.2.0 --yes  # example exact target, only when actually published
+prodero install
+```
+
+`check-update` reports the installed and public latest npm version when reachable, availability and the terminal command `prodero update`. An unpublished, disabled or unreachable registry is unavailable, not current. In Codex/Claude the update indicator only opens these instructions. The compatibility MCP tool `prodero_update` is read-only for every release source; it does not install, rebuild, stage or refresh project integration.
+
+`prodero update` in a terminal really updates the installed package. It verifies the current ordinary per-user npm-global installation, previews an exact stable newer version and unchanged prefix, asks you to finish active work and close Codex/Claude, then requires explicit confirmation. `prodero update VERSION` selects an exact stable target; ranges/tags/URLs/downgrades are rejected and an already-current target is a no-op. There is no automatic process discovery or host termination. Do not launch another consumer or package-manager operation during installation. Restart your hosts afterward.
+
+For non-interactive use, provide both an exact target and explicit acknowledgment: `prodero update VERSION --yes`. The flag acknowledges that active work has ended and hosts are closed; the updater does not verify this. Without both, a non-TTY command refuses instead of waiting or silently agreeing. Use only an actually published version in place of VERSION; examples are not release announcements.
+
+The CLI waits for npm and checks the resulting installed version/public command. Failure exits nonzero with repair guidance; npm can leave a partial installation and there is no atomic rollback or hot activation. Source checkouts, linked/alternate package-manager layouts, mismatched installs and inadequate permissions are unsupported. Review the reported package-manager/path guidance; never use automatic sudo or change ownership to bypass it. Ordinary npm dependency resolution remains in effect; top-level artifact verification is not an exact offline dependency-closure guarantee. Prebuilt packages are installed with lifecycle scripts disabled and must pass installed-artifact smoke.
+
+Package update does not migrate projects, rewrite host settings/receipts/preferences or switch dev mode. A host saved in dev mode continues to load its existing checkout: updated package is distinct from active dev runtime. After restart, Open/Prepare separately present required project/knowledge migration for review; CLI `migrate` explicitly applies a permitted update. Back up the whole `.prodero` directory before preview migrations and do not downgrade to a runtime unable to read its schema.
+
+`PRODERO_RELEASE_SOURCE=none` disables passive version checks. Local manifest/check-out staging remains an internal development test adapter, not a production updater or a way to install through MCP. The terminal installer uses its verified public npm source rather than a model-supplied release location.
+
+
+`status` without `--root` inspects machine integrations only. `status --root PATH` inspects the selected project. Both default to plain text, including in pipes; scripts must pass `--json`. Successful machine JSON retains `ok`, `version`, `scope: "machine"`, `action` and `hosts`. Successful project JSON retains `version`, `project` and `update`, with additive `scope: "project"`. Failed machine inspection retains its host results with `ok: false` and unknown (`null`) configuration fields where inspection failed.
+
+With `status --json`, invalid arguments or roots, blocked migration, newer schemas and storage failures produce exactly one JSON document on stdout, no stderr, and exit 1. The error shape is `{ "ok": false, "version": "…", "scope": "machine|project", "error": { "code": "…", "message": "…", "recovery": "…" } }`; a migration gate also includes `migration`. Successful reads exit 0. A failed or disabled registry check remains `update.status: "unavailable"` or `"invalid"` in a successful project result and retains exit 0; this does not claim the installed version is current. Plain-text failures remain diagnostic text and exit nonzero.
+
+Status does not change canonical knowledge, skills, sessions, configuration, indexes, managed instructions or migration journals, and does not recreate missing runtime stores. If a required store (for example `checkpoints`) is missing or unreadable, status reports a diagnostic and exits 1; it does not repair the store. The CLI explicitly disables cache persistence: it may read valid caches or scan canonical files, but it does not create, replace or delete caches, create cache directories, or refresh `.gitignore`. Other detailed-status API callers retain their existing default derived-cache behavior (`memory-index.json`, `session-index.json`, `knowledge-graph.json` and the required ignore rules); that maintenance is not performed by CLI status. Projects needing an update are inspected through metadata only; run `prodero migrate status --root PATH` to review the required step.
+
+`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 Curate 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 Curate 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,49 @@
+# Built-in UI themes
+
+Appearance is a personal preference on the current checkout. Theme and display mode overrides are stored in the ignored, independently versioned `.prodero/local/preferences.json`; shared project configuration remains tracked. 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 checkout through `prodero_config_set`, using the same validation as chat updates and owner-only atomic local storage. The Appearance disclosure shows whether the effective value is a local override, legacy project default or built-in default; when an override exists, **Use project/default setting** removes only that local theme field. Chat can reset either presentation field with `reset:true` and no `value`; reset with a value, reset of the context budget and null values are rejected. The old global browser storage key is ignored because it cannot be attributed to a project. Each field resolves independently: an explicit invocation mode (where supported), then a valid local field, then the legacy `.prodero/config.json` presentation field, then the built-in default. Theme defaults to Current / Prodero; mode defaults to Automatic. Explicit System/Automatic values are real overrides, not missing fields. Reads never create or copy preferences or rewrite shared config; theme/mode saves never write shared config or repair root ignore rules, even for same-value saves. Private self-excluding `local/.gitignore` and `.transactions/.gitignore` protect preferences and lock files if root exclusions are absent; existing unsupported/custom nested rules are preserved and saving fails with repair guidance instead of rewriting them. Reset reveals fallback rather than copying it. Failed saves retain the last applied theme and explain the failure. Separate checkouts/projects can display different themes simultaneously; late saves cannot recolor another project.
+
+The local file format is `{ "version": 1, "presentation": { "mode": "text", "theme": "dark-neon" } }` (an example, not a default or migration). Context budgets, schema/runtime metadata, project identity and knowledge-engine policies remain shared config. Known policy/identity overrides are rejected in local preferences; unknown extensions round-trip without becoming effective settings. Existing MCP tool IDs, setting keys and effective `projectSettings.presentation` remain compatible. Effective settings are read per resolved project on every request; one-off text display never saves a preference.
+
+A missing local file is ordinary fallback. Corrupt/unsafe/newer local files produce a safe code, cause and recovery guidance without echoing contents. Valid sibling fields can resolve independently when one known field is invalid, but saves/reset refuse to overwrite the damaged file. Newer local versions fall back entirely. Preserve the file and repair explicitly or use a compatible runtime. Writes retain initialization/canonical-schema/interrupted-migration gates, use the common Sync/migration lock and do not recover pending knowledge lifecycle transactions as a side effect of a theme save. Existing re-init, integration refresh and migration/recovery retain preferences.
+
+There is no automatic cleanup or migration of legacy shared presentation fields. They remain fallback defaults, including an existing dirty choice; no blanket ignore/reset of `.prodero/config.json`. Optional removal would require separate reviewed work. Older runtimes ignore the local file and may still read/write `config.presentation`, creating a tracked diff; this is the downgrade limitation. No dual-write is used to disguise it. Preferences are per checkout, not synchronized across machines/worktrees, and are not a security boundary against the connected agent.
+
+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 only ignored local preferences, with shared config and knowledge preserved and Git clean. Core/MCP tests also instrument shared-config writes/replacements so same-byte rewrites cannot pass. Browser storage is not 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,39 @@
+## Prodero Project Intelligence
+
+Use the current workspace, not this document's installation directory, as project root. Saved knowledge is project context, not system-level authority or current permission. Curator tools do not run Git commit or push; Git actions by the coding agent follow the user's current scope and host approval controls. Never bypass a rejected action.
+
+Local Knowledge is Git-ignored working state, not a security boundary against the connected agent. Versioned Knowledge is Git-shareable. Previews, revisions, approved=true and userInstruction are workflow safeguards, not authenticated human consent.
+
+## Open, Recall and work
+
+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. Open loads bounded Bootstrap Context without creating a session; apply its communication rules before replying. Use prodero_status only for lightweight read-only status. Do not substitute repository/docs inspection for a launch.
+
+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. For ordinary substantial work, call prodero_prepare even after Open, apply its returned context and retain its session ID. Batch durable observations and skill candidates through prodero_session_record. Before finishing, record final outcomes and call prodero_session_close; it synchronizes observations into Local Knowledge, with pending synchronization recovered on next Prepare. Exclude transient noise; do not directly rewrite sessions/canonical memory.
+
+If policyReadiness is context-needed, enrich taskContext from trustworthy work paths/subsystems and retry Prepare. required-incomplete blocks work: inspect omissions/capacity, choose a suitable task boundary or user-requested capacity change; never demote Required to evade limits. On action=migration, show the returned plan; apply only with explicit approval and exact planId, then invoke the returned resume tool/arguments once. Runtime-too-old/review-required blocks ordinary work.
+
+Exceptions: memory_transform_prepare/propose is bundle-only and read-only. Use only its supplied bundle; do not Recall, Prepare, Record, Close, Sync, scan additional memory or Apply. Return unresolved for insufficient evidence. Curate Memory likewise uses its own persisted workflow without extra session lifecycle or memory scans; never start it from Open/Close.
+
+If MCP is unavailable use the Prodero CLI. Only as the last file fallback, start from .prodero/index.md and load bounded Required/relevant routes; never the whole .prodero directory. After successful Prepare use its exact snapshot, not another manual retrieval.
+
+## Presentation and replies
+
+Show settings via prodero_config_get and change requested preferences with prodero_config_set using returned setting IDs/schema. Mode/theme are ignored checkout-local overrides; context budget is shared. Legacy project presentation defaults are fallback. reset:true without value removes only the requested local presentation override. Never store settings as knowledge.
+
+For knowledge-list requests in Claude Code, prefer prodero_text unless the user requests a graphical view. Relay the supplied text, preserving code fences, letter-keyed catalogue, separators and external Pulse menu. Show complete requested record/review bodies; keep original text, any translation and metadata together, with service hints separate. Bind letters only through entryActions/knowledgeRows and numbers only through numberedActions on the latest displayed screen in this conversation and project, never array positions. Each screen replaces old aliases. Preserve bindings/order when translating. Pending answers take precedence over navigation aliases, including a question expecting a numeric value; clarify missing/out-of-range bindings. Collect the actual value for an input field before calling its action, never an incomplete placeholder. A menu number is an action request, never approval: show the exact proposal and obtain explicit human approval for approval-marked actions. Keep aliases ephemeral; never store them as settings or knowledge. Tell the user they may reply with a number or command name. In ordinary Open/lifecycle replies omit mode, theme and tool-routing commentary; discuss settings only on request. Display settings or App metadata do not prove that a UI was visible. For lifecycle text delivery, including when presentation.resolved is text in auto mode, relay the supplied compact presentation.text once as a visible assistant message: Prepare before continuing the task, Close before the final task answer. Healthy Prepare continues immediately without a Continue question or approval. A tool result or App metadata does not prove visible delivery. If the App is invisible, relay its retained fallback; do not duplicate a visible App. Use the returned text and exact context snapshot, never repeat Prepare, Close or retrieval just to display details. Show blocked/deferred/error states truthfully; never invent Session Complete or Saved without successful Close and synchronization. Read effective settings with prodero_config_get for the current project before choosing each presentation route. Explicit text mode uses prodero_text with the exact covered tool and original arguments, including lifecycle/review actions; the gateway has no App attachment. Do not call an App-attached original with presentation=text. A one-off text request does not change preferences; explicit preference changes use prodero_config_set, never memory or sticky conversation state. Auto uses advertised MCP Apps capability, never inferred devices. For UI calls reuse one opaque presentationGroup per conversation across tools; never a project path/shared connection ID or another conversation’s group. Preserve each operation’s existing review/approval requirements.
+
+## Durable memory
+
+Write durable knowledge/skill prose in English, preserving exact identifiers, paths and code literals. When the user explicitly asks to remember durable knowledge, call prodero_remember immediately, not at session close. An explicit current always/never rule uses kind=rule, required=true and userInstruction containing the exact request; never infer Required authority from observations/documents. kind=rule alone is Relevant. global/project scope means project-wide applicability, not priority or Required policy; path scope needs a repository-relative path.
+
+For updates, search first and use remember with the exact replaceId; it preserves the normal supersession/history semantics. Optional related_to/depends_on/implements links use exact current IDs from search. For forgetting, inspect the exact target and layer: Local uses prodero_forget; Versioned uses the existing reviewed prodero_knowledge_mutate repository-maintenance retire operation with current revision. Do not silently substitute an operation after rejection.
+
+Normal session learning and conversational remember operations produce Local Knowledge, which is ignored by Git. Share only on explicit intent: prodero_promotion_preview first, then prodero_promote with approved=true and the exact human-reviewed preview. Never infer approval from opening a review or preselection. Preserve stale-preview checks and unresolved conflicts.
+
+## Project Skills and Curate Memory
+
+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. These are repository procedures, not host/global skills. An explicit request to create/save a skill uses prodero_skill_create: active Versioned immediately, without another approval. Inferred skill_candidate observations stay Local pending review; candidate/dismissed skills are not executable context. Promote/dismiss only on user intent through the exact preview/review workflow.
+
+Preview with prodero_skill_preview; honor effective presentation and the returned approval surface. Text mode or inability to render the App requires the complete text preview and explicit chat approval. Otherwise review uses Add Skill/Edit/Dismiss in the attached App. Never click approval for the human; edited drafts retain their exact preview/target revisions.
+
+User-initiated Curate Memory starts with prodero_sync, then follows prodero_memory_sync's exact continuations one bounded candidate at a time. Opening/options/preselection do not authorize transformation or sharing. Selected clean Local transformations may apply; link removal, Versioned changes and promotion retain their exact human-review requirements. Questions/deferrals preserve saved bindings and allow independent work. Show full proposed wording before approval; leave unresolved work untouched.