@qvac/core 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Peer-to-peer AI across your devices",
   "exports": {
@@ -137,11 +137,13 @@
     },
     "./dist/assistant.cjs": "./dist/assistant.cjs"
   },
+  "bin": {
+    "duck": "./tui/index.mjs"
+  },
   "scripts": {
-    "build:tui": "node tui/build.mjs",
     "build:splash": "node tui/build-splash.mjs",
     "build:schema": "bare schema/build.ts",
-    "duck": "node tui/build.mjs && bare tui/index.mjs",
+    "duck": "node scripts/build-bundle.mjs && bare tui/index.mjs",
     "duck:warm": "bare tui/index.mjs",
     "mesh-peer": "bare examples/mesh-peer.mjs",
     "mesh-lab": "bare examples/mesh-lab.mjs",
@@ -217,6 +219,7 @@
   },
   "dependencies": {
     "@qvac/harness": "^0.2.1",
+    "@qvac/skills": "^0.1.3",
     "asenion": "^0.1.0",
     "autobee": "2.6.0",
     "b4a": "^1.8.1",
@@ -243,6 +246,7 @@
     "bare-subprocess": "^6.1.0",
     "bare-supervisor": "^0.1.1",
     "bare-system-logger": "^1.0.3",
+    "bare-tui": "^0.0.3",
     "bare-url": "^2.4.5",
     "blind-peer": "^3.10.2",
     "blind-peering": "^2.7.0",
@@ -284,7 +288,6 @@
     "bare-runtime": "^1.30.0",
     "bare-sidecar": "^0.5.2",
     "bare-stow": "^0.1.4",
-    "bare-tui": "^0.0.3",
     "brittle": "^4.0.2",
     "holepunch-types": "^0.2.1",
     "hyperdht": "^6.32.0",

package/tui/README.md

@@ -0,0 +1,133 @@
+# duck
+
+The interactive chat TUI over `@qvac/core` — the real llama.cpp harness (via
+`@qvac/sdk`), the real chunk stream, a real mesh.
+
+## Installation
+
+`duck` ships in the `@qvac/core` package, so an install puts it on PATH:
+
+```sh
+npm i -g @qvac/core   # duck
+```
+
+In the repo:
+
+```sh
+bun run duck        # build the assistant bundle, then run
+bun run duck:warm   # reuse the last-built bundle
+```
+
+`duck` runs the SAME `dist/assistant.bundle` the desktop app ships — the stow of
+`worker/assistant-sidecar.mjs` that `scripts/build-bundle.mjs` builds. `bun run
+duck` rebuilds it first, because a stale bundle decodes with the old wire format
+and dies on the first call whose encoding changed; a freshly written bundle also
+pays a one-time cold start on its first spawn (OS page-cache miss + the
+platform's security assessment of the new binary and its native addons). The TUI
+host (`index.mjs`, `app.mjs`) is not in that bundle, so while iterating on the
+TUI use `duck:warm`. Rebuild after changing any `worker/`, wire, or `lib/`
+source.
+
+The bundle carries its JS but not its native addons: `build-bundle.mjs` offloads
+those beside the bundle and leaves the forest out of the tarball, shipping
+`dist/prebuilds-manifest.json` instead. `lib/prebuilds.mjs` links this host's
+addons back into place from the installed `node_modules` on first run — which is
+why an installed `duck` needs no postinstall step.
+
+`index.mjs` is the `duck` bin — a `#!/usr/bin/env bare` script, so `bare` has to
+be on PATH (`bare-runtime` puts it in `node_modules/.bin`). `bare-tui` needs
+Bare's native TTY; the TUI will not run under node.
+
+## Usage
+
+```
+duck [--storage <dir>] [--temp] [--headless]
+```
+
+Flags may appear in any order. Joining a mesh is `/join qvac://mesh/…` inside
+the app, not a boot argument.
+
+- `--storage <dir>` — a self-contained root (its own corestore and SDK home
+  under `<dir>`). `QVAC_STORAGE` is the env fallback.
+- `--temp` — the same, in a throwaway dir. `QVAC_TEMP=1` is the env fallback.
+- `--headless` — brings the same stack up with no TUI: prints the mesh invite,
+  then streams logs (including the sidecar child's own output) to stdout until
+  ctrl+C. A mesh peer to point other instances at, and the only live view of
+  the boot the TUI hides.
+
+Storage defaults to the desktop app's release root (`resolveStorage`, i.e.
+`<platform-persistent>/qvac/dev`), so the TUI resumes the same mesh and chats
+the desktop persists there — one at a time (the corestore is single-writer, so
+quit the desktop first) and only across matching Core/schema versions. Models
+stay in the shared global `~/.qvac/models`; `QVAC_ENV` picks another channel.
+
+To run alongside another qvac app that already holds the SDK registry lock, use
+an explicit root — it puts the SDK home and its lock on a scratch
+`<dir>/sdk-home`. Models are still shared; `QVAC_MODEL_CACHE_PATH` isolates
+those too.
+
+The TUI copies its mesh invite to the clipboard on ctrl+y; a running TUI moves
+mesh with `/join qvac://mesh/…`. See [../docs/tui-commands.md](../docs/tui-commands.md)
+for the full command set.
+
+## Environment
+
+| Variable                                                    | Effect                                                                                                                                                                                               |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `QVAC_MODEL`                                                | Overrides the demo agent's model — a registry name, or a local path/URL                                                                                                                              |
+| `QVAC_MMPROJ`                                               | Pairs models with their mmproj projections so ctrl+V'd images reach the model natively. One value applies to every model; `model=mmproj,model2=mmproj2` pairs are per-model. `QVAC_INPROCESS=1` only |
+| `QVAC_IMAGE_MODEL`                                          | Enables the `generate_image`/`edit_image` tools — a catalog choice (`sd2` \| `sdxl` \| `flux2-klein`), or a local diffusion model                                                                    |
+| `QVAC_IMAGE_LLM`, `QVAC_IMAGE_VAE`, `QVAC_IMAGE_PREDICTION` | FLUX.2 is a companion set: the Qwen3 text encoder, the VAE, and `flux2_flow` (required for img2img)                                                                                                  |
+| `QVAC_LOG_FILE`, `QVAC_LOG_LEVEL`                           | Move the log file / pick the level (`debug` \| `info` \| `warn` \| `error`, default `info`)                                                                                                          |
+| `QVAC_BOOT_TIMING=1`                                        | Prints the total connect time after the TUI exits. Per-stage stamps exist only under `QVAC_INPROCESS=1` — the shared assistant sidecar carries no boot timer                                         |
+| `QVAC_INPROCESS=1`                                          | Runs Core and Client in this process, no sidecar — the only topology that can inject a live harness object                                                                                           |
+
+```sh
+QVAC_MODEL=~/.qvac/models/3a65a2a3c6a30a47_Qwen3.5-4B-Q4_K_M.gguf \
+QVAC_MMPROJ=~/.qvac/models/0e037fa9ec5dddcf_Qwen3.5-4B.mmproj-Q8_0.gguf \
+duck
+```
+
+Logs (Core's own lines, and the sidecar child's piped stdout/stderr — the
+llama.cpp and SDK output) go to `<storage.root>/assistant.log`, as they do on
+desktop. Nothing is printed: the TUI owns the tty.
+
+## Layout
+
+| Path        | Responsibility                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------ |
+| `index.mjs` | The `duck` bin — CLI, storage resolution, and the two topologies (sidecar, in-process)     |
+| `app.mjs`   | The TUI itself — state, keys, commands, rendering                                          |
+| `lib/`      | Leaf helpers: wrapping, selection, rendering, export, knowledge import, uploads, prebuilds |
+
+## Splash
+
+An empty transcript — first boot, and a fresh chat — shows `../ducks.png` as
+half-block truecolor art, centered, with that state's own caption beneath it
+(`starting up…`, `connecting to the mesh…`, `(say hello)`).
+
+`lib/splash-art.mjs` is generated and committed; regenerate it when the image
+changes:
+
+```sh
+bun run build:splash
+```
+
+It carries four cuts — 64x32, 48x24, 32x16 and 24x12 cells. `splash()` takes
+the widest that fits the body and falls back to the bare caption when none
+does, so a roomy window gets more of the illustration and a 24-row terminal
+still gets a duck. The ladder tops out well short of a full-screen window: this
+is a splash above the prompt, not a wallpaper.
+
+## Busy words
+
+A run with no model progress to report shows a duck-themed gerund instead of
+`thinking…` — `Dabbling…`, `Pondering…`, `Quackompiling…`. The word is a pure
+function of the run id (`lib/busy-words.mjs`), so it holds for that whole run
+rather than flickering on every repaint, and two runs rarely land on the same
+one. States that _do_ have something to report keep saying it (`loading X…`,
+`downloading X: 40%`).
+
+## License
+
+Apache-2.0