docs(plugins): document plugin contract v2, the inventory and ADR 0034

[thymikee]

Summary

Part 3 of 4 of #3755 (umbrella #3747), stacked on #3768. Blocked by #3748: do not merge before it.

Docs only:

• website/docs/docs/plugins.md: v2 authoring (./agent-device export, factory with options, setup, credentials with byBackend, connection), entry discovery and the no-fallback rule, the registry order and duplicate rule, daemon status and the inventory entry shape, and a short section on v1 plugins.
• ADR 0034, "Provider plugin registry" (brief): three sources, one shape, set fixed per daemon, failure isolation, and a short daemon-ownership note pointing to feat(client): explicit daemon lifecycle with ensureDaemon() and attach clients #3754 and feat(host): startAgentDevice() for embedder-owned daemons #3757. Indexed in docs/adr/README.md.
• CHANGELOG.md entry for the contract, registry, isolation, inventory and daemon status.
• limrun.md and build-an-integration.md follow the renamed diagnostic and contract.

Runtime tests do not apply to prose; the docs checks in check:affected ran.

Validation

pnpm check:affected --run --head a304bb7f40 (the stack top, which contains this layer): passed (exactCommit).

🤖 Generated with Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.37 MB	5.37 MB	0 B
Package (unpacked)	5.37 MB	5.37 MB	0 B
Package (download)	1.62 MB	1.62 MB	+1 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.6 ms	26.6 ms	-0.1 ms
CLI --help	78.9 ms	76.8 ms	-2.1 ms

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-3769/
Built to branch gh-pages at 2026-10-17 11:59 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[cubic-dev-ai]

All reported issues were addressed across 6 files

_{You’re at about 93% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

This PR is ready at 058826d. CI is green, with 14 checks and none failing, and the change is docs-only. No conflicts. Not blocking, take or leave: the Connect section at website/docs/docs/plugins.md#L95 lists resolve({flags,env,cwd,stateDir}) and verify({flags,env}), but the contract in packages/plugins/src/contract.ts also passes host to both callbacks, so the example could add it; and the CHANGELOG.md entry is one long bullet that mixes contract, registry, status, fingerprint and Limrun changes, so a few shorter bullets would read better. I compared the docs against the base branch head (5645905), not a checkout of this PR head. I did not run the docs build, trace the registry ordering or the plugins list inventory behavior into code, or check the ADR header format against ADRs 0001-0033. Nothing else stands in the way; the stack merges in order (#3767, #3768, then this PR).

[thymikee]

Thanks. Taken in 5c46bf5: the Connect example now passes host to resolve and verify, with a sentence saying it is the same ProviderPluginHost that setup gets, and the CHANGELOG entry is split into five bullets (contract, registry, failure isolation and status, client fingerprint and Limrun fingerprint, partial-Limrun diagnostic).

[thymikee]

The PR is ready. At f93a0a0 the docs match the contract and inventory types they describe, and CI is green with 14 checks and none failing. I found no conflicts. Nothing is left to do before merge. I only checked the contract and inventory types the docs describe. I did not read ADR 0034 in full (I only grepped it for status and fingerprint claims), and I did not trace the daemon status CLI rendering. The stacked code under the docs (daemon registration and registry) is also outside what I read.

Not blocking, take or leave: website/docs/docs/plugins.md:39 says plugins list --json reports "whether their factory loads and validates". For a version 1 plugin, loadInstallation returns the legacy adapter without importing the entry, so it reports compatible even if the entry throws on import or has no default factory. You could add "(for a version 1 plugin, whether its manifest is valid)".

[thymikee]

Rebased onto the new #3768. Docs and ADR 0034 now describe registry.close() as the single cleanup owner, composition choosing candidates, and the daemon.json states. check:affected --run --head c09dbc6c4f passes.

[thymikee]

The PR is ready. At c4ac622 the docs match the code they describe, and no code changes are needed.

Not blocking, and you can take or leave these: the two docs sentences that say only a missing daemon.json means stopped could say that a missing or stale record means stopped, and that an unreadable or invalid file never does. The CHANGELOG entry could also describe the embedder source as the contract's third slot, coming in #3757, since the only composition at this head uses built-in and store candidates.

The earlier clean review was at fc0516a (#3769 (comment)). This head is that work rebased onto #3768. I read the docs files and the code they describe, and did not run the docs build, link checks, or tests.

The only check still pending is Smoke Tests, which is queued and has not run. This PR changes docs only, so it cannot affect a smoke route. Smoke Tests must finish green before merge. There are no conflicts.

This review covers c4ac622. The newer head 22f4e58 is the same two commits rebased onto bddb30f, with no content change.

[thymikee]

The PR is ready at 22f4e58. The earlier clean review of fc0516a still holds, and the 8 threads that were open then are now resolved. The checks are green (19 checks, 0 not passing, docs-only diff) and there are no conflicts.

Not blocking: the line "Only an absent file means stopped" in website/docs/docs/plugins.md is too narrow, because daemon-registration.ts:146-162 also reports stopped for a record with a null or dead pid, and the ADR 0034 rule "only absent reads as a stopped daemon" has the same gap. You could say that a missing or stale record means stopped, and that an unreadable or invalid file never does. Take it or leave it.

I checked the status state machine and the inventory type, but not how the CLI renders daemon status output. The CHANGELOG sentence that calls the embedder a source depends on #3757, and I did not check that the source is wired at the base. I also did not re-check each resolved thread against its fix. Nothing else stands in the way, so merge once the base PR in the stack lands.

[thymikee]

Pushed 224b819616. Applied: the docs now say a missing or stale record means stopped and an unreadable or invalid file never does, and describe embedder as the third source slot arriving with #3757 (plugins.md, ADR 0034, changelog). The lease-refusal paragraph now mentions failedPlugins. check:affected --run --head a304bb7f40 passes on the stack top.

[thymikee]

The PR is ready. At 224b819 the docs match the code, and the earlier review is still the state of the PR. CI is green with 19 checks and none failing, and the diff is docs only, so no production code changes. There are no conflicts. Not blocking, and you can take it or leave it: website/docs/docs/plugins.md:37 says invalid means daemon.json "is not a daemon record", but the code returns invalid only when the file is not a JSON object (daemon-resolution.ts:102-108), while a JSON object that names no pid, such as {}, reads as stopped (daemon-registration.ts:156). Saying invalid means "not a JSON object" and that a record naming no daemon process reads as stopped would match the code, and ADR 0034 line 23 could change the same way. I did not re-run the gates, and I checked only the docs against the code at head. Cubic has not reviewed this head. Nothing else stands in the way, so this waits on a human merge, and the base #3768 stack lands first.