install: adopt the agent-first Install SOP v1 (install/verify/uninstall contract)

[loonghao]

Part of the ecosystem-wide install standardization tracked in dcc-mcp/dcc-mcp-core#2252 (Install SOP v1 full text, audit summary, and core-side work items). Companion: agent bug-feedback mechanism v2 in dcc-mcp/dcc-mcp-core#2253.

Audit findings for this repo (2026-08)

• Has installer + JSON doctor -- but doctor only checks file presence and cannot observe the real failure hotspot: the manual "enable in Python Plugin Manager" step and whether the extension actually loaded (no bootstrap error capture inside Krita).
• No uninstall command; no installer unit test (unlike gimp); no host preflight (Krita presence/version); macOS pykrita default path likely wrong.
• Hand-rolled staged install/rollback duplicates safe_replace_tree; core lifecycle helpers unused; no troubleshooting section in README.

Conformance checklist — Install SOP v1 (host-integrated adapter)

Docs & discoverability

• Root install.md following the standard template (Requirements / Supported versions / Agent quick path / Manual path / Verify / Upgrade / Uninstall / Troubleshooting); catalog instructions_url updated to point at its raw URL
• Platforms (win/mac/linux) stated explicitly

Installer surface (agent-first)

• Standard verbs: install | status | verify | uninstall | upgrade under the standard entry point (dcc-mcp-<dcc> <verb> or documented dcc-mcp-cli install --dcc-type <dcc> path) — no bespoke exe names or one-off arg shapes
• Uniform flags: --json --yes --dry-run --dcc-path <p> --python <p>; stable exit codes (0 ok / 10 preflight / 20 acquire / 30 install / 40 verify / 50 requires-restart)
• --json output uses the shared schema incl. machine-executable next_steps[] ({id, description, command|file_edit, why})

Preflight

• Host installation + embedded interpreter detection with --dcc-path / --python overrides; chosen interpreter recorded in the plan
• min_core_version + host version matrix checked before touching anything
• Partial/existing-install detection (fresh vs upgrade vs repair)

Install

• Host enablement automated (module/addon/plugin registration, env wiring) — GUI-only steps allowed only when the host physically requires them, emitted as one structured next_step
• Idempotent: re-running converges; staged replace, never delete-then-copy
• Windows-lock aware via dcc_mcp_core.install_lifecycle (inspect_install_root, safe_remove_tree / safe_replace_tree, structured requires_restart deferral)
• Install receipt written (files, versions, interpreter, host paths touched)

Verify & recover

• verify goes to usable: import check in the target interpreter → readiness probe (wait_for_sidecar_ready / ping skill) → directly_usable: true|false with failure_stage/failure_reason
• capture_bootstrap_errors wired around the startup hook
• Uninstall consumes the receipt; failed install/upgrade rolls back to the previous state (not to "nothing installed")
• Troubleshooting section covers the top observed failure modes

CI

• Install smoke in CI: plan + dry-run + receipt round-trip minimum; full host smoke where runners allow

Findings are from a read-only audit of the default branch on 2026-08-22. If the repo has moved since, treat the checklist as the source of truth. Reference implementations for each checklist area (3dsmax MZP uninstall, unity preflight, photoshop verify-to-usable, unreal checksum discipline, fpt pinned provisioning, tiled/gimp/krita JSON doctor) are listed in the tracking issue.

[loonghao]

Adapter-side implementation is now released in v0.4.0.

Evidence:

• implementation: PR feat: standardize Krita install lifecycle #7 / merge 793089c
• release: PR chore(main): release 0.4.0 #8 / merge 5f4bd69
• exact merge-SHA CI: run 32876322683, 4/4 successful
• release/publish: run 32876322954, 2/2 successful
• public PyPI: dcc-mcp-krita==0.4.0 wheel and sdist are available and non-yanked

This issue remains open because the checklist still requires the Core catalog follow-up in dcc-mcp/dcc-mcp-core#2252 to set instructions_url to this adapter raw install.md. No real Krita process or live operator gateway was exercised, so live-host readiness is not claimed.