chore: align repo scaffolding with the package standard

.github/workflows/ci.yml

@@ -1,30 +1,31 @@
-name: CI
+name: ci
 
 on:
-  push:
-    branches: [main]
   pull_request:
+  push:
     branches: [main]
 
 jobs:
-  verify:
+  check:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [24]
+    timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 24
       - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.4.0
       - run: bun install --frozen-lockfile
-      - run: bun run typecheck
-      - run: bun run lint
-      - run: bun run format:check
-      - run: bun test
+      - run: bun run check
       - run: bun run build
       - run: bun run contrast-test
       - run: bun run dep-guard
+      - run: bun run test:e2e
+      - name: node consumer smoke
+        run: |
+          set -euo pipefail
+          TARBALL="$PWD/$(npm pack --silent)"
+          mkdir -p "$RUNNER_TEMP/c" && cd "$RUNNER_TEMP/c"
+          npm init -y >/dev/null && npm pkg set type=module >/dev/null
+          npm install "$TARBALL"
+          node -e 'import("@corbits/react-ui").then((m) => { for (const n of ["Button", "ChatThread", "Badge"]) if (typeof m[n] !== "function") throw new Error("missing export: " + n); })'

.github/workflows/cla.yml

@@ -0,0 +1,53 @@
+name: CLA Assistant
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, synchronize]
+
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+
+concurrency:
+  group: cla-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Maintainer fast path
+        if: >-
+          github.event_name == 'pull_request_target' &&
+          (contains(fromJSON('["TheGreatAxios","brianjfox"]'), github.event.pull_request.user.login) ||
+           endsWith(github.event.pull_request.user.login, '[bot]'))
+        run: echo "Maintainer or bot pull request; CLA not required."
+      - name: CLA Assistant
+        if: >-
+          ((github.event.comment.body == 'recreate-signatures' ||
+            github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') ||
+           github.event_name == 'pull_request_target') &&
+          !(github.event_name == 'pull_request_target' &&
+            (contains(fromJSON('["TheGreatAxios","brianjfox"]'), github.event.pull_request.user.login) ||
+             endsWith(github.event.pull_request.user.login, '[bot]')))
+        # corbitsdev/cla-assistant-action v2.6.1-node24: upstream v2.6.1 on node24.
+        uses: corbitsdev/cla-assistant-action@ef6d3e51db8232fe93090810f13bde30497c1d74
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          path-to-document: "https://github.com/${{ github.repository }}/blob/main/CLA.md"
+          path-to-signatures: "signatures/version1/cla.json"
+          branch: "cla-signatures"
+          allowlist: TheGreatAxios,brianjfox,*[bot]
+          custom-notsigned-prcomment: >-
+            Thank you for your contribution. Before it can be merged, please read our
+            [Contributor License Agreement](https://github.com/${{ github.repository }}/blob/main/CLA.md)
+            and sign it by posting a new comment on this pull request containing
+            exactly the line below (nothing else):
+          custom-pr-sign-comment: "I have read the CLA Document and I hereby sign the CLA"
+          custom-allsigned-prcomment: "All contributors have signed the CLA."

.gitignore

@@ -1,11 +1,9 @@
 node_modules/
 dist/
+*.tsbuildinfo
 *.tgz
+coverage/
 .env
-.env.local
-*.tsbuildinfo
+.env.*
 .DS_Store
-scratch/
 build/
-.worktrees/
-.agent-state/

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+## Purpose
+
+`@corbits/react-ui` is the React component library for agent and workflow
+surfaces: chat, runs, artifacts, charts, layout and controls, with a Tailwind v4
+theme. It owns the components, hooks, theme tokens and the prebuilt stylesheet.
+It does not fetch data, talk to a backend, or import server-side packages; data
+arrives as props.
+
+## Layout
+
+- `src/ui/`: components.
+- `src/blocks/`: composed screens (login form, auth layout).
+- `src/hooks/`: shared hooks (controllable state, popovers, list selection,
+  reduced motion).
+- `src/test/`: test helpers.
+- `src/lib/`: internal helpers; not exported unless listed in `src/index.ts`.
+- `src/index.ts`: the hand-written root barrel.
+- `src/theme.css`, `src/styles.css`: tokens and keyframes; the prebuilt sheet
+  entry.
+- `stories/`: Ladle stories, kept out of `src/` so they never ship in `dist/`.
+- `scripts/dep-guard.mjs`, `scripts/contrast-test.mjs`: the CI gates.
+- `scripts/test-dom-setup.ts`: happy-dom preload for unit tests (`bunfig.toml`).
+- `e2e/`: checks against the built package.
+
+## Rules
+
+- Sibling imports are relative and end in `.js`; there is no path alias.
+- Public API goes in `src/index.ts`. A public module that statically imports an
+  optional peer stays out of the barrel and gets its own `exports` entry.
+  `dep-guard` fails if one reaches the barrel.
+- No `@workbench/*` imports, and no server-side packages in a component.
+- A `ui/` or `blocks/` module that calls a hook, creates a context, defines an
+  inline handler or imports an optional peer starts with `"use client"`;
+  stateless components and `hooks/`/`lib/` stay unmarked. `dep-guard` checks
+  both ways.
+- A framework-level library the consumer already has is a peer; adding a peer is
+  a breaking change.
+- Accessibility is a merge requirement: full keyboard operation, visible focus
+  that returns to the opener when an overlay closes, real elements over roles,
+  an accessible name on every control, colour never the only channel, and
+  `prefers-reduced-motion` respected.
+- Generic names only (agent, workflow, artifact, ...); no product brands in a
+  module, prop, type or fixture.
+- No `any` without a comment explaining why the type system leaves no
+  alternative.
+
+## Local development
+
+```sh
+bun install
+bun run check
+```