chore(starters): add agents files

Signed-off-by: Cory Rylan <crylan@nvidia.com>

Author: coryrylan

projects/starters/angular/AGENTS.md

@@ -0,0 +1,27 @@
+# Elements Angular Starter
+
+This file only covers how this starter wires Elements into Angular. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Register used Elements in the Angular component file that owns the template, as in `src/app/app.ts`.
+- Add `CUSTOM_ELEMENTS_SCHEMA` to the standalone component metadata before using `nve-*` tags in `app.html`.
+- Keep theme and utility CSS imports in `src/styles.css`; Angular component styles should stay local to component layout refinements.
+- Keep `nve-theme` and `nve-transition` on `src/index.html`.
+
+## Angular Syntax
+
+- Use normal Angular template syntax with custom elements: `[property]` for JavaScript properties, `[attr.name]` for attributes, and `(event)` for custom events.
+- Boolean attributes on custom elements usually need `[attr.hidden]="condition ? '' : null"` when the attribute semantics matter.
+- Use Angular router primitives outside or inside Elements slots normally; Elements do not own Angular state.
+
+## Forms
+
+- Use Elements form wrappers around native inputs so Angular forms keep owning value and validation state.
+- Bind Angular reactive forms to the nested native control, not to the `nve-*` wrapper.
+- Put Angular conditional rendering for validation messages on `nve-control-message` or around it, depending on the control state.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/angular` after schema, import, or template changes.
+- Run `pnpm run lint` when editing TypeScript, HTML templates, or CSS.

projects/starters/bundles/AGENTS.md

@@ -0,0 +1,25 @@
+# Elements Bundles Starter
+
+This file only covers how this starter wires Elements into a static bundle page. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Load pre-built CSS bundles from `@nvidia-elements/styles`, `@nvidia-elements/themes`, and any optional package bundle in `src/index.html`.
+- Load pre-built JavaScript bundles with module scripts in `src/index.html`.
+- Keep bundle paths rooted through the Vite alias for `./node_modules` from `vite.config.ts`.
+- Use this starter only when loading all registered components is acceptable; it trades tree-shaking for drop-in integration.
+
+## Optional Package Bundles
+
+- Include an optional package bundle only when the page uses that package. The current starter includes Monaco because it renders `nve-monaco-input`.
+- Pair optional package JavaScript and CSS bundles when the package ships both.
+
+## DOM Events
+
+- Attach listeners with script code, not inline event handler attributes.
+- Query typed Elements only after the bundle import has run.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/bundles` after changing bundle paths or static HTML.
+- Run `pnpm run dev` only when visual browser verification is needed.

projects/starters/eleventy-ssr/AGENTS.md

@@ -0,0 +1,24 @@
+# Elements Eleventy SSR Starter
+
+This file only covers how this starter wires Elements into Eleventy with Lit SSR. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Configure Lit SSR in `eleventy.config.js` through `@lit-labs/eleventy-plugin-lit`.
+- Keep `mode: 'worker'` for SSR isolation unless the build requirement changes.
+- Provide server-renderable Elements through `componentModules`; include `@nvidia-elements/core/dist/icon/server.js` before component `define.js` entrypoints when icons can render server-side.
+- Use metadata to generate broad component entrypoint lists only for SSR demos that intentionally exercise many Elements.
+
+## Hydration
+
+- Import `@lit-labs/ssr-client/lit-element-hydrate-support.js` in the client module script before importing client-side `define.js` modules.
+- Match server `componentModules` and client `define.js` imports for components rendered in the HTML.
+
+## Template Constraints
+
+- Keep raw generated examples filtered away from components that are not SSR-safe for this starter.
+- If transforming example templates, keep the transforms local and explicit in `src/index.11ty.js`.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/eleventy-ssr` after SSR config, metadata filtering, or template changes.

projects/starters/eleventy/AGENTS.md

@@ -0,0 +1,26 @@
+# Elements Eleventy Starter
+
+This file only covers how this starter wires Elements into Eleventy. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Keep global Elements CSS in `src/_layouts/index.css`.
+- Register Elements used by layout or markdown content in `src/_layouts/index.ts`.
+- Keep shared page shell markup in `src/_layouts/index.11ty.js`; page files should supply content.
+- Use `@11ty/eleventy-plugin-vite` for bundling the layout entrypoint.
+
+## Markdown Rendering
+
+- Add `nve-text` and `nve-layout` attributes through the markdown-it renderer in `eleventy.config.js` when markdown should receive Elements typography.
+- Keep renderer mappings constrained to token types that markdown-it exposes predictably: headings, paragraphs, links, and lists.
+- Let raw `nve-*` HTML pass through markdown only when the page intentionally owns that markup.
+
+## Routing
+
+- Keep the `<base>` URL and Vite `base` aligned with `PAGES_BASE_URL`.
+- Use relative links in generated tab markup so static output works under the starter base path.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/eleventy` after layout, renderer, or asset pipeline changes.
+- Run `pnpm run lint` when editing Eleventy config or layout TypeScript.

projects/starters/go/AGENTS.md

@@ -0,0 +1,26 @@
+# Elements Go Starter
+
+This file only covers how this starter wires Elements into Go templates. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Render Elements markup through `html/template` in `src/index.html`.
+- Keep dynamic values in the Go `PageData` shape and pass them into the template; do not concatenate HTML strings in handlers.
+- Use static bundles or a separate frontend build pipeline. This starter is the static-bundle path.
+
+## Static Assets
+
+- Treat the current CDN comments in `src/index.html` as placeholders until a real Elements CDN path exists.
+- If serving local bundles instead, add explicit static file handling in `main.go` and point CSS and module imports at that route.
+- Keep theme attributes on the root HTML template, not in Go handler code.
+
+## Go Template Constraints
+
+- Use escaped template output for data values.
+- Only use trusted template HTML for checked Elements markup.
+- Keep routing and rendering small; move repeated page shell code into templates before adding more routes.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/go` after Go or template changes.
+- Run `pnpm run dev` for local rendering checks on `http://localhost:8080`.

projects/starters/hugo/AGENTS.md

@@ -0,0 +1,28 @@
+# Elements Hugo Starter
+
+This file only covers how this starter wires Elements into Hugo. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Mount Elements package `dist` folders in `hugo.toml` before referencing package assets from templates.
+- Keep static bundle CSS and module script loading in `layouts/baseof.html`.
+- Allow raw HTML through Goldmark only when content authors are trusted to write checked Elements markup.
+- Keep the Elements page shell in `layouts/baseof.html` and page-specific content in blocks or partials.
+
+## Render Hooks
+
+- Use Hugo render hooks to map markdown features onto Elements:
+  - headings: add `nve-text` based on heading level.
+  - links: add `nve-text="link"` and external-link attributes.
+  - tables: render `nve-grid`, `nve-grid-header`, `nve-grid-row`, and cells.
+  - code blocks: render `nve-codeblock`.
+- Register the package bundle for any component introduced by a render hook.
+
+## Base URLs
+
+- Keep local and hosted base URL handling in `baseof.html`.
+- Use relative links in tabs and partials so static output works under the hosted starter path.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/hugo` after config, template, or render-hook changes.

projects/starters/importmaps/AGENTS.md

@@ -0,0 +1,26 @@
+# Elements Import Maps Starter
+
+This file only covers how this starter wires Elements through browser import maps. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Keep the import map in `src/index.html` aligned with the packages copied by `build.js`.
+- Map both bare package names and trailing-slash subpaths for Lit packages and `@nvidia-elements/core`.
+- Import individual `define.js` files from the mapped `@nvidia-elements/core/` prefix.
+- Load CSS with normal `<link>` tags because there is no bundler to process CSS imports.
+
+## Static Copy Script
+
+- Update `build.js` whenever the import map references a new package that must exist in `dist/node_modules`.
+- Copy package `dist` folders for Elements packages; copy full dependency folders only when browser subpath imports require them.
+- Keep the copy list explicit.
+
+## Constraints
+
+- Use this starter for no-build prototypes and browser-native module loading.
+- Prefer a Vite starter when tree-shaking, TypeScript transforms, or production bundling matter.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/importmaps` after import map or copy script changes.
+- Use `pnpm run dev` to catch browser import resolution errors.

projects/starters/lit-library/AGENTS.md

@@ -0,0 +1,26 @@
+# Elements Lit Library Starter
+
+This file only covers how this starter wires Elements into reusable Lit components. For component APIs, use the Elements CLI/MCP documentation. For production core components, use repository component guidance; this starter is for reusable domain components outside `@nvidia-elements/core`.
+
+## Integration Points
+
+- Export side-effect-free classes from feature `index.ts` files.
+- Put custom element registration in sibling `define.ts` files.
+- Add every public deep import to `package.json#exports` and `typesVersions`.
+- Keep `./**/define.js` in `sideEffects` so bundlers preserve registration entrypoints.
+
+## Composing Elements
+
+- Import Elements classes from side-effect-free entrypoints when using a scoped registry.
+- Define composed Elements in the same registry used by `static shadowRootOptions.customElementRegistry`.
+- Use `define.js` entrypoints only for global registration tests or consuming app examples.
+
+## Component Authoring
+
+- Keep public props primitive unless an ADR or local requirement justifies the exception.
+- Emit standard DOM events with `bubbles: true` and `composed: true` when crossing the shadow root.
+- Prefer form-associated custom elements when the domain component behaves as one form control.
+
+## Verification
+
+- Run `pnpm run build`, `pnpm run test`, and `pnpm run lint` in `projects/starters/lit-library` after component, export, or package changes.

projects/starters/mpa/AGENTS.md

@@ -0,0 +1,26 @@
+# Elements MPA Starter
+
+This file only covers how this starter wires Elements into a Vite multi-page app. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Keep shared Elements CSS in `src/common/index.css`.
+- Keep shared Elements registrations in `src/common/index.ts`.
+- Import `./common/index.js` from each page entrypoint before page-specific code.
+- Add new HTML pages to `vite.config.ts` `build.rolldownOptions.input`.
+
+## Page Structure
+
+- Each page owns its `<title>`, metadata, stylesheet link, and module script.
+- Keep selected navigation state local to each page's static HTML.
+- Use root-relative dev paths in source HTML when Vite owns serving; verify build output after adding nested pages.
+
+## View Transitions
+
+- Keep `nve-transition` on the root HTML for global transitions.
+- Add component-level transition attributes only to pages that need them.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/mpa` after adding pages or changing shared entries.
+- Run `pnpm run lint` after TypeScript or config changes.

projects/starters/nextjs/AGENTS.md

@@ -0,0 +1,31 @@
+# Elements NextJS Starter
+
+This file only covers how this starter wires Elements into Next.js. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead.
+
+## Integration Points
+
+- Use the React custom elements type augmentation in `src/global.d.ts`.
+- Keep global theme attributes on `src/pages/_document.tsx`.
+- Keep global CSS imports in `src/styles/globals.css`.
+- Register Elements in the page or component module that renders them.
+
+## Next.js Runtime
+
+- This starter uses the pages router and `output: 'export'`.
+- Keep `basePath`, `output`, and `distDir` aligned in `next.config.ts` for static starter output.
+- Import server-specific modules, such as `@nvidia-elements/core/icon/server.js`, only when a component needs server render support.
+
+## SSR Status
+
+- Treat `@lit-labs/nextjs` integration as experimental in this starter. Do not enable it casually; the current config leaves it commented with the upstream issue.
+- If enabling Lit SSR, import or configure it before any Elements registration imports and run a full build.
+
+## JSX Syntax
+
+- Use React custom element event naming such as `onclose` for a `close` event.
+- Use primitive JSX props for custom element properties and strings for attributes when the Elements API expects attributes.
+
+## Verification
+
+- Run `pnpm run build` in `projects/starters/nextjs` after React, config, SSR, or type changes.
+- Run `pnpm run lint` after TSX or config edits.