[pullfrog]

Sub-issue 2/5 of #102. Docs-only, no code behavior change.

What this adds

docs/plugin-host-compat.md — the plugin-side convention for how to probe host APIs, the companion to the "which commit provides each API" matrix in docs/compatibility.md (#131):

• The three rules: probe at the call site with one predicate per host API (exact-surface typeof / version / import / hasattr / data-shape checks — never version strings); a missing optional API disables only its feature, never the plugin; one per-session warning that names the plugin, the feature, and the missing requirement (API + matrix commit).
• The corollary that guards the whole system: an optional feature must never raise the plugin's basic-mode floor (Piano floors 0.3.0-alpha.1; a fork-only API can only gate the feature that uses it).
• A canonical JS helper (HOST_FEATURES + hostFeature() / assumeHostFeature(), including an optional window.feedBack.diagnostics.contribute contribution) and the backend equivalent (routes.py guarded import + context["log"].warning, never raise from setup()).
• Per-row probe + degradation contract for all seven matrix rows: dlc_paths._resolve_dlc_path, sloppak.read_member_bytes, chart-transform (chartTransformDomain.version === 1), the /ws/sync/{session_id} connect-probe (can't be typeof'd), setExternalFrameDriver/renderFrame/renderFrameAt, playerContexts.version === 1, and getPhrases().top_difficulty (typeof === 'number' post-ready, with the "optional but load-bearing" nuance where 0 is a valid tier).
• Where the host does NOT help today: minHost is metadata passthrough only (nothing under static/ reads it), and capability declarations are intent, not a probe.
• A checklist for plugin PRs adding optional features.

Also: README docs-list entry, a CLAUDE.md pointer under Plugin Best Practices, and a CHANGELOG [Unreleased] entry.

Scope exclusions (deliberate)

• No new core API. The degradation scenario is a plugin running on an old host; a helper that only new hosts ship can't be the mechanism — the convention is self-contained plugin-side feature detection.
• No minHost changes — making it actionable/feature-scoped is sub-issue 3/5.
• No plugin loading, capability, or minHost behavior changes. All probes were verified against current static/highway.js, static/capabilities/chart-transform.js, static/capabilities/player-identity.js, and plugins/__init__.py; commit hashes and upstream/fork-only tags match docs/compatibility.md exactly.

Closes #132.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using big-pickle (free) ｜ 𝕏}

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	0

Docs-only PR (#132) adding docs/plugin-host-compat.md — the plugin-side convention for probing required vs optional host APIs — plus README, CLAUDE.md, and CHANGELOG.md pointers. No runtime code changed.

Verification performed

• All seven matrix commit hashes confirmed present in the repo: 0dcc913, d876ded, 05be9eb, 03e1c1d, f7c761c, 7633211, e5339c0.
• lib/dlc_paths._resolve_dlc_path, lib/sloppak.read_member_bytes, static/capabilities/chart-transform.js (chartTransformDomain.version === 1), static/capabilities/player-identity.js (playerContexts.version === 1), and static/highway.js (renderFrame/renderFrameAt/setExternalFrameDriver, getPhrases().top_difficulty) all match the doc's probe predicates exactly.
• static/ contains no minHost reads, confirming the "metadata passthrough only" claim.
• static/diagnostics.js exposes contribute(pluginId, payload), matching the recommended diagnostics contribution.
• lib/safepath.safe_join exists as the fallback cited for lyrics_karaoke.
• docs/compatibility.md, docs/capability-recipes.md referenced by the new doc exist.
• CHANGELOG entry lands under the [Unreleased] → ### Added section, consistent with the matrix entry above it.

Files Reviewed (4 files)

• docs/plugin-host-compat.md — new doc; all code/commit claims verified accurate
• CHANGELOG.md — single [Unreleased] entry added
• CLAUDE.md — new "Host compatibility" subsection under Plugin Best Practices
• README.md — docs-list entry added

---

_{Reviewed by free · Input: 523.3K · Output: 7.4K · Cached: 637.4K}