chore: add AI agent instruction files

.claude/CLAUDE.md

@@ -0,0 +1,56 @@
+# Pine Design System — Claude Code Instructions
+
+## Project Overview
+- Stencil.js web component library orchestrated with Nx (monorepo)
+- Core components live in `libs/core/src/components/`
+- All components are prefixed with `pds-` (e.g., `pds-button`, `pds-table`)
+- Each component may include: `*.tsx`, `*.scss`, `*.figma.ts`, `stories/`, `docs/`, `test/`, and auto-generated `readme.md`
+- Composite components have nested subcomponent directories (e.g., `pds-table/pds-table-row/`)
+- React wrappers are generated in `libs/react/`
+
+## Git Conventions
+- Commits, branches, and linting are enforced by lefthook hooks (commitlint, validate-branch-name, lint-staged) — do not skip hooks
+- Branch names must follow: `{type}/{description}` — accepted types: `chore`, `ci`, `docs`, `feat`, `fix`, `hotfix`, `perf`, `refactor`, `revert`, `style`, `test`
+- Do NOT include ticket or issue numbers in branch names or commit messages
+- Commit scope should match the component name (e.g., `feat(pds-table):`, `fix(pds-button):`)
+- Keep commit messages to a single line
+
+### Commit type rules — use the correct type for the files being committed:
+- `feat(component):` — new props, events, methods, or component behavior in `*.tsx`
+- `fix(component):` — bug fixes in component code
+- `test(component):` — test files (`*.spec.tsx`, `*.e2e.ts`)
+- `docs(component):` — MDX docs, Storybook stories, and documentation updates
+- `style(component):` — SCSS/CSS-only changes
+- `refactor(component):` — code restructuring with no behavior change
+- `chore:` — tooling, config, dependencies
+
+## Pull Requests
+- PR title must follow conventional commits format: `type(scope): description`
+- Always use the repo PR template at `.github/pull_request_template.md` for the PR body
+- If your branch is behind `main`, rebase before pushing: `git rebase main`
+- Requires at least two approved reviews before merging
+- See `CONTRIBUTING.md` for full contributor guidelines
+
+## Testing
+- Spec tests go in the component's `test/` folder (e.g., `pds-chip/test/pds-chip.spec.tsx`) using Stencil's `newSpecPage`
+- E2E tests also in the component's `test/` folder using Stencil's `newE2EPage`
+- Every new prop, event, or behavior needs corresponding test coverage
+
+## Documentation
+- JSDoc descriptions on `@Prop`, `@Event`, and `@Method` must use consistent terminology across components — review similar props/events on other components before writing new descriptions
+- When adding a prop or event that exists in a similar form on another component, match the wording and phrasing of the existing description
+
+## Build & Test (Nx)
+- Build all: `npm run build.all` (`npx nx run-many --target=build`)
+- Test all: `npm run test.all` (`npx nx run-many --target=test`)
+- Lint all: `npm run lint.all` (`npx nx run-many --target=lint`)
+- Target core only: `npx nx run @pine-ds/core:build`, `npx nx run @pine-ds/core:test`
+- After modifying a component's `*.tsx`, rebuild to regenerate `components.d.ts` and `readme.md`
+- Dev server: `npm run start` (Storybook at localhost:6006)
+- Linting: ESLint (with `@stencil-community/recommended` + `@typescript-eslint`), Prettier, and Stylelint
+- Generate a new component: `npm run stencil.generate pds-[component-name]` — choose `*.scss Format` when prompted, then copy `stories/` and `docs/` folders from an existing component
+
+## Boundaries
+- **Always:** follow existing component patterns, run lint and tests before committing, use conventional commits with component scope, match JSDoc terminology from similar components
+- **Ask first:** adding new dependencies, creating files outside component directories, making breaking API changes (removing props/events), modifying CI/CD or build config
+- **Never:** skip lefthook hooks, edit auto-generated files (`readme.md`, `components.d.ts`) manually, commit secrets or `.env` files, modify `node_modules/` or `dist/`

.cursor/rules/pine-components.mdc

@@ -0,0 +1,36 @@
+---
+description: Stencil component development patterns for Pine Design System
+globs: libs/core/src/components/**/*.tsx
+alwaysApply: false
+---
+
+# Pine Component Development
+
+## Coding Patterns
+
+- Use Stencil decorators: `@Component`, `@Prop`, `@State`, `@Event`, `@Listen`, `@Method`, `@Watch`
+- Props should have JSDoc comments — these generate the auto-docs in `readme.md`
+- Use `@Event()` with `EventEmitter` for custom events; prefix with `pds` (e.g., `pdsTableRowSelected`)
+- Shadow DOM is used — style with `::part()` attributes and `:host` selectors
+- ESLint: `@stencil-community/recommended` + `@typescript-eslint` + Prettier
+
+## Testing
+
+- Spec tests go in the component's `test/` folder (e.g., `pds-chip/test/pds-chip.spec.tsx`) using Stencil's `newSpecPage`
+- E2E tests also in the component's `test/` folder using Stencil's `newE2EPage`
+- Every new prop, event, or behavior needs corresponding test coverage
+- Run tests: `npx nx run @pine-ds/core:test`
+
+## Documentation
+
+- MDX docs in the component's `docs/` folder — include live examples with `<Canvas>` and `<Story>`
+- Storybook stories in the component's `stories/` folder — export a default meta + named story exports
+- `readme.md` is auto-generated by Stencil — do not edit manually
+- JSDoc descriptions on `@Prop`, `@Event`, and `@Method` must use consistent terminology across components — review similar props/events on other components before writing new descriptions
+- When adding a prop or event that exists in a similar form on another component, match the wording and phrasing of the existing description
+
+## Boundaries
+
+- **Always:** match existing component patterns, add test coverage for new props/events, use JSDoc on all public APIs
+- **Ask first:** adding new dependencies, breaking API changes (removing/renaming props or events)
+- **Never:** edit auto-generated `readme.md` or `components.d.ts`, skip Shadow DOM encapsulation

.cursor/rules/pine-project.mdc

@@ -0,0 +1,41 @@
+---
+description: Pine Design System project conventions, git workflow, and build commands
+alwaysApply: true
+---
+
+# Pine Design System
+
+Stencil.js web component library in an Nx monorepo. Core components live in `libs/core/src/components/`.
+
+## Component Structure
+
+- All components are prefixed with `pds-` (e.g., `pds-button`, `pds-table`)
+- Each component may include: `*.tsx`, `*.scss`, `*.figma.ts`, `stories/`, `docs/`, `test/`, and auto-generated `readme.md`
+- Composite components have nested subcomponent directories (e.g., `pds-table/pds-table-row/`)
+- React wrappers are generated in `libs/react/`
+- Generate new components: `npm run stencil.generate pds-[name]` — choose `*.scss Format`, then copy `stories/` and `docs/` from an existing component
+
+## Git Conventions
+
+- Lefthook enforces commitlint, validate-branch-name, and lint-staged — never skip hooks
+- Branch names: `{type}/{description}` — do NOT include ticket/issue numbers
+- Accepted branch types: `chore`, `ci`, `docs`, `feat`, `fix`, `hotfix`, `perf`, `refactor`, `revert`, `style`, `test`
+- Commit scope = component name (e.g., `feat(pds-table):`, `fix(pds-button):`), single line, no ticket numbers
+- Commit type by file: `feat:` for new component code/props, `fix:` for bug fixes, `test:` for specs/e2e, `docs:` for MDX/stories/docs, `style:` for SCSS only, `refactor:` for restructuring, `chore:` for tooling/config/deps
+- PR titles: `type(scope): description` — use the template at `.github/pull_request_template.md`
+- If your branch is behind `main`, rebase before pushing — requires at least two approved reviews before merging
+
+## Build & Test
+
+- Build all: `npm run build.all`
+- Test all: `npm run test.all`
+- Lint all: `npm run lint.all`
+- Target core only: `npx nx run @pine-ds/core:build`, `npx nx run @pine-ds/core:test`
+- After modifying `*.tsx`, rebuild to regenerate `components.d.ts` and `readme.md`
+- Dev server: `npm run start` (Storybook at localhost:6006)
+
+## Boundaries
+
+- **Always:** follow existing patterns, run lint/tests before committing, use conventional commits with component scope
+- **Ask first:** adding dependencies, creating files outside component dirs, breaking API changes, modifying CI/build config
+- **Never:** skip lefthook hooks, edit auto-generated files (`readme.md`, `components.d.ts`), commit secrets or `.env`

AGENTS.md

@@ -0,0 +1,66 @@
+# Pine Design System — Agent Instructions
+
+## Project Overview
+
+Stencil.js web component library in an Nx monorepo. Core components live in `libs/core/src/components/`.
+
+- All components are prefixed with `pds-` (e.g., `pds-button`, `pds-table`)
+- Each component may include: `*.tsx`, `*.scss`, `*.figma.ts`, `stories/`, `docs/`, `test/`, and auto-generated `readme.md`
+- Composite components have nested subcomponent directories (e.g., `pds-table/pds-table-row/`)
+- React wrappers are generated in `libs/react/`
+- Generate new components: `npm run stencil.generate pds-[name]` — choose `*.scss Format`, then copy `stories/` and `docs/` from an existing component
+
+## Component Development
+
+- Use Stencil decorators: `@Component`, `@Prop`, `@State`, `@Event`, `@Listen`, `@Method`, `@Watch`
+- Props should have JSDoc comments — these generate the auto-docs in `readme.md`
+- Use `@Event()` with `EventEmitter` for custom events; prefix with `pds` (e.g., `pdsTableRowSelected`)
+- Shadow DOM is used — style with `::part()` attributes and `:host` selectors
+- `readme.md` is auto-generated by Stencil — do not edit manually
+
+## Documentation
+
+- JSDoc descriptions on `@Prop`, `@Event`, and `@Method` must use consistent terminology across components — review similar props/events on other components before writing new descriptions
+- When adding a prop or event that exists in a similar form on another component, match the wording and phrasing of the existing description
+- MDX docs in the component's `docs/` folder — include live examples with `<Canvas>` and `<Story>`
+- Storybook stories in the component's `stories/` folder — export a default meta + named story exports
+
+## Git Conventions
+
+- Lefthook enforces commitlint, validate-branch-name, and lint-staged — never skip hooks
+- Branch names: `{type}/{description}` — do NOT include ticket or issue numbers
+- Accepted branch types: `chore`, `ci`, `docs`, `feat`, `fix`, `hotfix`, `perf`, `refactor`, `revert`, `style`, `test`
+- Commit scope = component name (e.g., `feat(pds-table):`, `fix(pds-button):`), single line, no ticket numbers
+- Commit type by file:
+  - `feat(component):` — new props, events, methods, or component behavior in `*.tsx`
+  - `fix(component):` — bug fixes in component code
+  - `test(component):` — test files (`*.spec.tsx`, `*.e2e.ts`)
+  - `docs(component):` — MDX docs, Storybook stories, and documentation updates
+  - `style(component):` — SCSS/CSS-only changes
+  - `refactor(component):` — code restructuring with no behavior change
+  - `chore:` — tooling, config, dependencies
+- PR titles: `type(scope): description` — use the template at `.github/pull_request_template.md`
+- If your branch is behind `main`, rebase before pushing — requires at least two approved reviews before merging
+- See `CONTRIBUTING.md` for full contributor guidelines
+
+## Testing
+
+- Spec tests go in the component's `test/` folder (e.g., `pds-chip/test/pds-chip.spec.tsx`) using Stencil's `newSpecPage`
+- E2E tests also in the component's `test/` folder using Stencil's `newE2EPage`
+- Every new prop, event, or behavior needs corresponding test coverage
+
+## Build & Test
+
+- Build all: `npm run build.all`
+- Test all: `npm run test.all`
+- Lint all: `npm run lint.all`
+- Target core only: `npx nx run @pine-ds/core:build`, `npx nx run @pine-ds/core:test`
+- After modifying `*.tsx`, rebuild to regenerate `components.d.ts` and `readme.md`
+- Dev server: `npm run start` (Storybook at localhost:6006)
+- Linting: ESLint (`@stencil-community/recommended` + `@typescript-eslint`), Prettier, and Stylelint
+
+## Boundaries
+
+- **Always:** follow existing component patterns, run lint and tests before committing, use conventional commits with component scope, match JSDoc terminology from similar components
+- **Ask first:** adding new dependencies, creating files outside component directories, making breaking API changes (removing props/events), modifying CI/CD or build config
+- **Never:** skip lefthook hooks, edit auto-generated files (`readme.md`, `components.d.ts`) manually, commit secrets or `.env` files, modify `node_modules/` or `dist/`