feat(agent): ship AI agent rules with npx init-agent installer

[garrity-miepub]

Summary

Ships AI agent rules with the @mieweb/ui package, plus a one-command installer that puts them where coding agents actually look. Goal: any agent working in a consumer repo uses DataVis NITRO for tables and reaches for @mieweb/ui components before inventing its own UI.

npx @mieweb/ui init-agent

Why an installer?

Agents don't read files inside node_modules, so shipping an AGENTS.md in the tarball alone does nothing. The CLI copies the rules into the two places agents do read:

1. .github/instructions/mieweb-ui.instructions.md — auto-applied by VS Code Copilot to **/*.{ts,tsx,js,jsx} via applyTo frontmatter
2. A marked block in AGENTS.md — the cross-tool convention read by Claude Code, Cursor, Codex, etc.

Idempotent: rerunning refreshes the marked block in place, so consumers rerun after upgrading to pull new rules. Existing AGENTS.md content is preserved.

The rules (agent/mieweb-ui.instructions.md)

14 rules, with ❌/✅ violation examples where agents most often go wrong (sourced from lessons/component-policy.md):

1. Tables start with DataVis NITRO — always propose DataVisNitroGrid first; Table only if the human explicitly insists; AGGrid is deprecated; never hand-roll a grid
2. Buttons belong in a ButtonGroup — 2+ adjacent buttons, or a single button with a long/dynamic label (for orientation="auto" ellipsis control); icon-only buttons require aria-label
3. Component-first — check the 126+ component catalog before writing raw HTML
4. Composition slots, not custom markup — ModalHeader/Body/Footer, CardHeader/Content, Table* sub-components
5. Variants and sizes, not className hacks — Button variants/sizes over utility-class overrides
6. Never hardcode colors — semantic tokens (bg-primary-600, text-muted-foreground), chart CSS variables
7. Theme through the brand system — ThemeProvider + @mieweb/ui/brands, never global CSS resets
8. Feedback states use library components — Spinner/Skeleton/LoadingPage, Alert/Toast, ErrorPage, Progress
9. Accessibility is not optional — accessible names, semantic HTML, aria-live via Toast/Alert, focus management
10. i18n and RTL — externalize text, logical classes (ms-*/me-*) never ml-*/mr-*, Intl APIs
11. Forms — library fields with labels; DateInput/DateRangePicker never raw type="date"
12. Imports and Tailwind setup — main barrel vs. subpaths; TW4 @source vs. TW3 preset + safelist
13. Deprecations are law
14. When no component exists — verify in Storybook first, build in @mieweb/ui style, propose upstreaming

Changes

• agent/mieweb-ui.instructions.md — rules template (single source; the CLI derives both install targets from it)
• agent/init-agent.mjs — the mieweb-ui bin (plain Node, zero deps)
• agent/README.md — folder purpose + maintenance note
• package.json — bin entry; agent added to files (verified in tarball via npm pack --dry-run)
• eslint.config.js — config block for Node CLI scripts (scripts/, agent/) with node globals
• README.md — "AI Agent Rules" section

Testing

• Fresh consumer dir: creates both .github/instructions/… and AGENTS.md with all 14 rules ✅
• Existing AGENTS.md: appends block, preserves content ✅
• Rerun: refreshes block in place, no duplication ✅
• Bare/unknown command: usage message, correct exit codes ✅
• pnpm typecheck ✅ · pnpm lint ✅ · prettier ✅

Follow-ups (future PRs)

• ESLint plugin for hard enforcement (no-restricted-imports on @mieweb/ui/ag-grid, raw <table> rule)
• MCP server exposing the component catalog (list_components, get_component_docs)
• llms.txt on the Storybook site / Context7 indexing

[Copilot]

Pull request overview

This PR packages @mieweb/ui AI-agent guidance alongside the library and adds an npx-driven installer to copy those rules into locations agents commonly read in consumer repositories (.github/instructions/ and an AGENTS.md marked block).

Changes:

• Add an agent/ rules template (mieweb-ui.instructions.md) plus an installer CLI (agent/init-agent.mjs) exposed via a new package bin.
• Ensure the agent/ assets ship in the published package (files update) and document usage in the repo README.
• Add an ESLint config override intended for Node .mjs scripts under scripts/ and agent/.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Documents the new “AI Agent Rules” installer command and outputs.
package.json	Ships agent/ in the tarball and exposes the mieweb-ui bin that powers npx @mieweb/ui init-agent.
eslint.config.js	Adds a Node CLI scripts override (globals + console rule).
agent/README.md	Explains purpose of the agent/ folder and what each file does.
agent/mieweb-ui.instructions.md	Introduces the agent rules template (Copilot frontmatter + policy content).
agent/init-agent.mjs	Implements the installer: writes .github/instructions/... and updates/inserts the marked AGENTS.md block.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cloudflare-workers-and-pages]

Deploying ui with    Cloudflare Pages

Latest commit:	14daa0b
Status:	✅  Deploy successful!
Preview URL:	https://ba3006dc.ui-6d0.pages.dev
Branch Preview URL:	https://feat-agent-instructions.ui-6d0.pages.dev

View logs

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (1)

agent/init-agent.mjs:57

• If AGENTS.md contains a <!-- mieweb-ui:begin --> marker but is missing the matching <!-- mieweb-ui:end --> marker, the current logic falls into the append branch. On the next run, end may match the END marker from the newly appended block, causing the refresh path to replace everything from the dangling BEGIN up to that END (potentially deleting unrelated content in between). Handle the “BEGIN without END” case explicitly to avoid corruption and repeated non-idempotent writes.

  const start = current.indexOf(BEGIN);
  const end = start === -1 ? -1 : current.indexOf(END, start + BEGIN.length);
  let updated;
  if (start !== -1 && end !== -1) {
    updated = current.slice(0, start) + block + current.slice(end + END.length);

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (2)

agent/mieweb-ui.instructions.md:35

• Rule 10 says to externalize all user-facing text (no hardcoded English strings in JSX), but this Rule 2 example uses hardcoded labels (Back/Cancel/Permanently delete this record). That inconsistency can cause agents to copy/paste non-i18n-safe examples. Add an explicit note in the example that string literals are placeholders and should be externalized per Rule 10.

// Multiple buttons

agent/mieweb-ui.instructions.md:67

• This code block includes hardcoded English strings (e.g., "Save", "Active") even though Rule 10 later states no hardcoded user-facing text in JSX. Adding a brief note here makes the examples consistent with the i18n rule and reduces the chance agents copy literals into real code.

// ❌ Violations