@plumbus/core 0.5.0 → 0.6.1

package/instructions/peer-dependencies.md

@@ -0,0 +1,46 @@
+# `@plumbus/core` peer dependency ranges
+
+Read this file **before** editing `peerDependencies` in any `packages/*/package.json`.
+
+## CRITICAL rules
+
+1. **Copy literals — do not derive ranges.** Never compute semver ranges from intuition. Copy the exact string from the table below or from a canonical `package.json` (`packages/mcp/package.json`, `packages/api/package.json`).
+2. **Never use `^0.x` caret ranges** on `@plumbus/core` peers in add-on packages. npm treats `^0.5.0` as **0.5.x only** (`>=0.5.0 <0.6.0`), not "0.5 and above."
+3. **pnpm passing locally does not prove peers are correct.** Backend Docker images install production deps with **npm** (`deployment.md` Rule 7). Wrong peers break Docker builds even when `pnpm install` succeeds.
+4. **Do not copy from CHANGELOG history.** Older releases documented incorrect ranges (`^0.5.0 <0.7.0` claimed to support 0.6.x — it does not under npm). Use this file and the canonical `package.json` files instead.
+
+## Canonical `@plumbus/core` peer strings
+
+| Package kind | `peerDependencies["@plumbus/core"]` | Canonical copy-from |
+|---|---|---|
+| Most add-ons (chat, chat-ui, knowledge-base, mcp, api, browser-extension) | `"0.5.x \|\| 0.6.x"` | `packages/mcp/package.json` |
+| Voice only (requires core 0.6+ media/cost APIs) | `"^0.6.0 <0.7.0"` | `packages/voice/package.json` |
+
+When adding a **new** publishable add-on under `packages/`, use `"0.5.x || 0.6.x"` unless the package genuinely requires core 0.6+ only (then use the voice pattern).
+
+## Forbidden patterns
+
+| Range | Why it is wrong |
+|---|---|
+| `"^0.5.0 <0.7.0"` | npm resolves `^0.5.0` to 0.5.x only — **rejects `@plumbus/core@0.6.0`** |
+| `"^0.5.0 <0.6.0"` | 0.5.x only — rejects 0.6.x |
+| `"^0.6.x"` or `"^0.6.0"` alone | Too loose or wrong syntax for multi-line support; use the table literals |
+| Widening an upper bound on a caret range | e.g. changing `<0.6.0` to `<0.7.0` on `^0.5.0` does **not** add 0.6.x support |
+
+## When `@plumbus/core` gets a new minor line (e.g. 0.7.0)
+
+Before tagging a core release:
+
+1. Update the literal table in **this file** (add `0.7.x` to the union, e.g. `"0.5.x || 0.6.x || 0.7.x"`).
+2. Update `peerDependencies["@plumbus/core"]` in **every** publishable add-on under `packages/` — copy the new literal everywhere; do not edit packages one-off with different strings.
+3. Patch-bump and publish each affected add-on.
+4. Update add-on `instructions/framework.md` (or `conventions.md`) peer lines to match.
+5. Run `pnpm lint`, `pnpm format:check`, `pnpm typecheck`, `pnpm test` from repo root.
+
+See also: `.agents/skills/bump-version/SKILL.md` (core **minor** bump checklist).
+
+## Related docs
+
+- `deployment.md` Rule 7 — backend `proddeps` uses `npm install --omit=dev`
+- `.agents/skills/new-package-instructions/SKILL.md` — new package `package.json` peers
+- `packages/mcp/package.json` / `packages/api/package.json` — canonical examples

package/instructions/translations.md

@@ -28,12 +28,33 @@ export const commonTranslation = defineTranslation({
 
 ## Rules
 
-- Place translation files in `app/translations/<name>.translation.ts`
-- Each file exports one `defineTranslation()` result
+- Place translation files in `app/translations/<name>.translation.ts` (classic layout), **or** use the locale-folder layout below
+- Each assembler exports one `defineTranslation()` result
 - All locales **must** have the same key set — mismatched keys throw at import time
 - Messages use ICU MessageFormat: `{name}` for interpolation, `{count, plural, ...}` for plurals, `{gender, select, ...}` for select
 - The `name` field is the namespace: keys resolve as `<namespace>.<key>` (e.g., `common.nav.overview`)
 
+## Locale-folder layout (optional)
+
+For larger catalogs, keep one folder per locale and a thin assembler:
+
+```
+app/translations/
+  en/common.messages.ts
+  he/common.messages.ts
+  common.translation.ts   # imports en + he, calls defineTranslation()
+```
+
+Scaffold with:
+
+```bash
+plumbus translation new myNamespace --locale-folders
+```
+
+Large namespaces (e.g. `staff`) can split further under `en/staff/*.messages.ts` and merge with a local `index.ts` before the assembler imports `./en/staff/index.js`.
+
+Discovery still loads only `defineTranslation()` exports; plain `messages` objects in locale folders are ignored.
+
 ## Server-Side Usage
 
 In capability handlers, use `ctx.translations.t()`:
@@ -49,13 +70,22 @@ The locale is resolved from the request context.
 | Command | Description |
 |---------|-------------|
 | `plumbus translation new <name>` | Scaffold a new translation file |
+| `plumbus translation new <name> --locale-folders` | Scaffold `en/`, `he/` message files + thin assembler |
 | `plumbus translation export` | Export to JSON or XLIFF 2.0 for professional translation |
 | `plumbus translation import` | Import translated JSON/XLIFF files back into source |
 | `plumbus translation status` | Report per-locale completion percentage |
 
 ## Frontend
 
-When translations exist, `plumbus ui generate` produces `generated/i18n/` with next-intl integration:
+When translations exist, `plumbus ui generate` produces `{frontend}/i18n/` with next-intl integration.
+
+Optional: emit per-locale bundles (same runtime API, smaller generated files):
+
+```bash
+plumbus ui generate --out-dir frontend --split-locale-bundles
+```
+
+Without the flag, output is unchanged — a single `i18n/messages.ts`.
 
 ```tsx
 import { useTranslations } from "next-intl";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumbus/core",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Plumbus framework core — types, SDK, runtime, CLI, test utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -70,7 +70,7 @@
   },
   "peerDependencies": {
     "@plumbus/api": "0.1.x",
-    "@plumbus/mcp": "0.5.x",
+    "@plumbus/mcp": "0.5.x || 0.6.x",
     "cron-parser": "^4.9.0",
     "redis": "^4.7.0"
   },
@@ -92,12 +92,16 @@
     "@biomejs/biome": "^2.4.6",
     "@types/node": "^25.4.0",
     "@vitest/browser": "^3.0.0",
+    "esbuild": "^0.25.12",
     "typescript": "^5.7.0",
-    "@plumbus/mcp": "0.5.0",
-    "@plumbus/api": "0.1.1"
+    "@plumbus/api": "0.1.2",
+    "@plumbus/voice": "0.3.0",
+    "@plumbus/mcp": "0.5.1"
   },
   "scripts": {
     "build": "tsc -b",
+    "build:voice-cli": "node scripts/build-voice-cli.mjs",
+    "pretest": "pnpm run build:voice-cli",
     "dev": "tsc -b --watch",
     "test": "vitest run",
     "test:watch": "vitest",