@aintela/chat 0.2.16 → 0.2.17

package/README.md

@@ -1,17 +1,21 @@
-# @envision/aichat
+# @aintela/chat
 
 Embeddable AI chat component built on a WebSocket agent gateway. This repo
-is the new home for what was previously `packages/library/src/components/AiChat/`
-in `envision-abi` — extracted into a standalone package so it can be
-consumed as a real library (built, versioned, peer-dep'd) instead of via
-in-tree source aliasing.
+is the standalone home for what was previously
+`packages/library/src/components/AiChat/` in `envision-abi` — extracted into a
+real library (built, versioned, peer-dep'd) instead of in-tree source aliasing,
+and published to the public npm registry.
+
+> **Name history:** `@envision/aichat` → `@aia/chat` → **`@aintela/chat`** (the
+> npm `@aia` org was taken). Always install and import `@aintela/chat`.
 
 ## Layout
 
-This repo is the published package (`@envision/aichat`) at its root:
+This repo is the published package (`@aintela/chat`) at its root:
 
 - `src/`, `package.json`, `vite.config.ts`, `tsconfig.json` — library source + config
-- `dist/` — built output, gitignored (rebuilt on every install via `prepare`)
+- `dist/` — built output, gitignored; **shipped in the npm tarball** (built on
+  `prepack`/`prepare` via `vite build`)
 - `examples/demo/` — Vite + React SPA that exercises the library against a fake
   agent gateway, with an option to point at a real WSServer
 
@@ -22,9 +26,9 @@ npm install
 cd examples/demo && npm install && npm run dev    # http://localhost:5174
 ```
 
-The demo aliases `@envision/aichat` to the root `src/` during development so
-HMR works across the package boundary. To validate the built bundle the way
-a real consumer would:
+The demo aliases the package to the root `src/` during development so HMR works
+across the package boundary. To validate the built bundle the way a real
+consumer would:
 
 ```bash
 npm run build
@@ -33,19 +37,27 @@ npm run build
 
 ## Consuming
 
-Consumers install via a git URL — no public registry. Pin to a tag for
-reproducibility; npm's `prepare` script runs `vite build` so the consumer's
-`node_modules/@envision/aichat/dist/` is populated automatically.
+`@aintela/chat` is published to the **public npm registry** — install it like
+any package and pin a normal semver range:
+
+```bash
+npm install @aintela/chat
+```
 
 ```json
 {
   "dependencies": {
-    "@envision/aichat": "github:envision-tecnologia/aichat#v0.1.1"
+    "@aintela/chat": "^0.2.16"
   }
 }
 ```
 
-(`github:owner/repo#ref` is npm's shorthand for `git+ssh://git@github.com/owner/repo.git#ref` — both forms work; npm normalizes to the shorthand on install.)
+The tarball ships the prebuilt `dist/` (see the `files` field in `package.json`),
+so consumers don't build anything on install.
+
+Subpath entry points are exported for focused imports: `@aintela/chat` (root),
+plus `@aintela/chat/models`, `/services`, `/components`, `/hooks`, `/utils`,
+`/interfaces`, and the stylesheet `@aintela/chat/style.css`.
 
 Every peer in `peerDependencies` must be installed by the consumer at a
 compatible version — that's how shared singletons (React, MUI ThemeContext,
@@ -77,10 +89,11 @@ Open `coverage/index.html` in a browser for the drill-down report.
 
 ## Releasing
 
-Cut a release whenever you ship a behavior change (bugfix, new prop,
-breaking API change). Tags are the source of truth — consumers pin to
-them, so the tag-on-`main` workflow is intentional discipline, not
-overhead.
+Cut a release whenever you ship a behavior change (bugfix, new prop, breaking
+API change). Publishing is **tag-driven**: pushing a `v<semver>` tag runs the
+`publish-aia-chat.yml` workflow, which `npm publish`es to the public npm registry
+via npm **Trusted Publishing** (OIDC — no stored token) with build provenance.
+`access: public` comes from `package.json`'s `publishConfig`.
 
 ### 1. Bump + commit + tag + push
 
@@ -88,8 +101,8 @@ From the repo root, after the change is committed on `main`:
 
 ```bash
 # 1. bump version in package.json (semver: patch / minor / major)
-npm version patch --no-git-tag-version    # 0.1.1 → 0.1.2 (bugfix)
-# npm version minor --no-git-tag-version  # 0.1.x → 0.2.0 (new prop / feature)
+npm version patch --no-git-tag-version    # 0.2.16 → 0.2.17 (bugfix)
+# npm version minor --no-git-tag-version  # 0.2.x → 0.3.0 (new prop / feature)
 # npm version major --no-git-tag-version  # 0.x.y → 1.0.0 (breaking)
 
 # 2. commit the bump
@@ -101,38 +114,40 @@ git tag -a vX.Y.Z -m "vX.Y.Z — <short release note>"
 git push origin main vX.Y.Z
 ```
 
-`--no-git-tag-version` on `npm version` is deliberate: it bumps
-`package.json` without creating its own commit/tag, so you control the
-commit message and tag annotation explicitly (npm's defaults are
-ambiguous when the bump rides alongside the substantive change).
+The pushed `vX.Y.Z` tag triggers CI (`npm ci` + `npm publish --provenance`). The
+tag version and the `package.json` version must match. You can also run the
+workflow manually (**workflow_dispatch**) to publish whatever version is currently
+in `package.json`.
+
+`--no-git-tag-version` on `npm version` is deliberate: it bumps `package.json`
+without creating its own commit/tag, so you control the commit message and tag
+annotation explicitly (npm's defaults are ambiguous when the bump rides alongside
+the substantive change).
+
+> **One-time setup** (already done, noted here for recovery): on npmjs.com, the
+> `@aintela` org / package registers a Trusted Publisher for repo
+> `envision-tecnologia/aichat`, workflow `publish-aia-chat.yml`. A token fallback
+> (`NPM_TOKEN` secret → `NODE_AUTH_TOKEN`) is stubbed in the workflow if OIDC ever
+> needs to be bypassed.
 
 ### 2. Update consumers
 
-Each consumer pins the dep to a specific tag in its `package.json`:
+Each consumer bumps its semver range (or just reinstalls, if the existing range
+already covers the new version):
 
 ```diff
-- "@envision/aichat": "github:envision-tecnologia/aichat#v0.1.1",
-+ "@envision/aichat": "github:envision-tecnologia/aichat#v0.1.2",
+- "@aintela/chat": "^0.2.16",
++ "@aintela/chat": "^0.2.17",
 ```
 
-Then in the consumer's repo:
-
 ```bash
-npm install @envision/aichat
-# dashboard-app currently needs --legacy-peer-deps because of an
-# unrelated transitive peer conflict (MUI + pigment-css). Drop the flag
-# once that's resolved.
+npm install @aintela/chat
 ```
 
-npm re-clones the package at the new tag, runs the package's `prepare`
-script (which runs `vite build`), and updates the consumer's lockfile
-with the new commit SHA — so subsequent installs on other machines pull
-the exact same code, even if the tag is later moved (don't move tags).
-
 ### Quick smoke-test before tagging
 
-`v0.1.1` shipped with a part-eventType bug that the demo surfaced
-within seconds. Before pushing a tag, give it a minute:
+`v0.1.1` shipped with a part-eventType bug that the demo surfaced within seconds.
+Before pushing a tag, give it a minute:
 
 ```bash
 npm run build && npm run typecheck    # at repo root