Add plugin authoring best-practices section and ref docs

[Copilot]

• Review current plugins guide and plugin-lib API surface
• Understand type signatures: RootDecoratorDef, ItemDecoratorDef, ResolverDef, EnvGraphDataTypeDef, VarlockPlugin metadata, error classes
• Delete reference/plugin-api/ folder (5 individual pages removed)
• Create reference/plugin-api.mdx — single page in the style of root-decorators / functions reference pages
• Update astro.config.ts sidebar to add one "Plugin API" entry under Reference
• Run parallel_validation

[changeset-bot]

⚠️ No Changeset found

Latest commit: caaadfb

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	varlock-website	caaadfb	Commit Preview URL Branch Preview URL	Apr 15 2026, 07:32 PM

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@env-spec/parser@621

npm i https://pkg.pr.new/varlock@621

commit: caaadfb