CTRL-REPO-WIDGET-01: Add repository-local AGENTS.md control file

[ja573]

Task identity

Field	Value
Programme	CTRL-DELIVERY-02
Parent	thoth-pub/thoth#824
Owning issue	#1
Task ID	CTRL-REPO-WIDGET-01
Repository	thoth-pub/metrics-widget
Risk	MEDIUM
Authorized base	dev @ ba3b9caa25e8e305e59a9b719c11d272c16d9013
Actual base	ba3b9caa25e8e305e59a9b719c11d272c16d9013 (re-verified immediately before branching; unchanged)
Task branch	feature/engineering/ctrl-repo-widget-01
PR target	dev

Scope

Control/documentation only. Creates exactly one new file: root AGENTS.md.

Whole-task diff:

A	AGENTS.md

No existing file is modified, deleted, moved or renamed. No version change, no tag, no release, no publication.

What the file records

• responsibility as the public embeddable React/JavaScript metrics package, including its public interface (exports, props, theme, CSS custom properties, exports map, type declarations);
• current dev -> main topology, with branch normalization explicitly deferred to BR-WIDGET-01;
• exact-base setup and deny-by-default granular action authorization (non-transitive);
• verified stack: React 19 peer dependency / TypeScript / Vite / Biome;
• public package/API compatibility responsibility across both supported consumer patterns — React consumers and vanilla-JavaScript/CDN consumers;
• thoth-pub/thoth-pyramid as a verified downstream package consumer (metrics-widget ^2.0.1);
• release-before-downstream-consumption ordering where a package release is required;
• current validation: npm ci, npm run lint, npm run build, npm run test:consumer, npm pack --dry-run where applicable;
• ordinary PR CI behaviour, and explicitly that ordinary PR CI does not publish npm packages;
• that a published GitHub release can invoke npm publication (publish.yml on release: published, trusted publishing via id-token: write);
• release, tag, version change and npm publication as separately authorized HIGH-impact actions;
• public Thoth GraphQL / OPERAS consumption, VITE_* build-time inlining, and an absolute prohibition on embedding machine/service credentials in package or browser code;
• independent exact-head review, implementation-report and HOLD/STOP rules.

It specializes the canonical doctrine in thoth-pub/thoth (root AGENTS.md, docs/engineering/ai-delivery/, docs/engineering/repository-map/) rather than copying or replacing it.

Validation

All commands run locally against this branch:

Command	Result
git diff --check	clean
npm ci	succeeds
npm run lint	exit 0 — 105 files checked, 1 pre-existing warning, 0 errors
npm run build	succeeds — library bundle and declaration files built
npm run test:consumer	exit 0 — packs, installs the tarball into a temp project and builds it as a real consumer
npm pack --dry-run	succeeds — metrics-widget-2.0.1.tgz, 16 files, version unchanged at 2.0.1

npm pack --dry-run does not publish. No publication step was invoked.

Effects

Category	Effect
Runtime / API / package interface	NONE
Migration / data	NONE
Auth / security implementation	NONE
Provider / runtime mutation	NONE
Release / publication	NONE
Version change	NONE (remains 2.0.1)
Dependency change	NONE

Automatic external effects

Ordinary pull-request CI (ci.yml: lint, build, consumer smoke test) is expected to run on this PR. That is normal and authorized. Observed CI results are reported on #1.

No GitHub release was created, no tag was pushed, and nothing was published to npm.

Gate

IMPLEMENTATION COMPLETE - FRESH INDEPENDENT EXACT-HEAD REVIEW REQUIRED

This PR stays DRAFT. The implementing agent has not approved, marked ready or merged, and must not.

Refs: thoth-pub/thoth#824, #1