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

[selfire1]

Thanks for adding the docs! It comes in handy as we're looking to build a custom internal plugin.

I started following the WIP docs. When using strict: true, I got a few errors that I needed to resolve with !.

This might not be the most elegant solution, but I just wanted to put on your radar that the examples require some coercion or checks.

[selfire1]

Suggested change

	async execute({ id, tokenResolver }) {
	// Await dynamic values (these may reference other schema items)
	const token = await tokenResolver?.resolve();
	instances[id].token = token ? String(token) : undefined;
	},
	});
	async execute({ id, tokenResolver }) {
	// Await dynamic values (these may reference other schema items)
	const token = await tokenResolver?.resolve();
	instances[id]!.token = token ? String(token) : undefined;
	}

[selfire1]

Suggested change

	process() {
	let instanceId = '_default';
	let refResolver: Resolver;
	if (this.arrArgs!.length === 1) {
	refResolver = this.arrArgs![0];
	} else {
	// first arg is the instance id – must be a literal
	if (!this.arrArgs![0].isStatic) {
	throw new SchemaError('Instance id must be a static value');
	}
	instanceId = String(this.arrArgs![0].staticValue);
	refResolver = this.arrArgs![1];
	}
	process() {
	let instanceId = '_default';
	let refResolver: Resolver;
	if (this.arrArgs!.length === 1) {
	refResolver = this.arrArgs![0]!;
	} else {
	// first arg is the instance id – must be a literal
	if (!this.arrArgs![0]!.isStatic) {
	throw new SchemaError('Instance id must be a static value');
	}
	instanceId = String(this.arrArgs![0]!.staticValue);
	refResolver = this.arrArgs![1]!;
	}
	if (!instances[instanceId]) {
	throw new SchemaError(
	`No MyPlugin instance "${instanceId}" found`,
	{ tip: 'Add @initMyPlugin() to your .env.schema file' },
	);
	}
	return { instanceId, refResolver };
	}

[philmillman]

Thanks @selfire1, we'll revisit and get something merged this week.