@mclean-capital/neura 1.10.2 → 2.1.0

package/README.md

@@ -1,8 +1,10 @@
 # @mclean-capital/neura
 
-> Neura CLI — install, manage, and talk to the Neura AI assistant from your terminal.
+> **A voice-first, proactive AI operating system.** Say the wake word and talk to Neura from any device — no click-to-start, no tap-to-speak.
 
-Neura is a proactive, autonomous AI operating system. It combines real-time voice conversation, continuous visual understanding, and autonomous worker agents. This CLI installs and manages the Neura core service, and also acts as a full client via `neura chat` and `neura listen`.
+Neura is a self-hosted AI assistant that runs as a persistent background service on your machine. It's always listening for the wake word via on-device ONNX inference (zero cloud cost while passive), streams voice conversations via Grok's Eve voice when active, and continuously watches your camera or screen through a Gemini Live vision watcher. It remembers what you've talked about across sessions, manages your tasks, and proactively reminds you about deadlines.
+
+This package is the full Neura distribution: **the CLI, the core service, and all runtime dependencies** ship together as one npm install. No separate downloads, no matching platform tarballs — one command installs everything.
 
 ## Install
 
@@ -10,17 +12,84 @@ Neura is a proactive, autonomous AI operating system. It combines real-time voic
 npm install -g @mclean-capital/neura
 ```
 
-Requires Node.js >= 22.
+This fetches the CLI **plus** the bundled core service and its native dependencies (`onnxruntime-node` for wake-word detection, `@electric-sql/pglite` for local storage). If `onnxruntime-node` fails to install, the whole install fails loudly — voice is a required feature, not an optional one.
+
+Requires **Node.js >= 22**.
+
+### Supported platforms
+
+| Platform                            | Supported |
+| ----------------------------------- | :-------: |
+| macOS — Apple Silicon (M1/M2/M3/M4) |    Yes    |
+| macOS — Intel (x64)                 |  **No**   |
+| Windows — x64 / arm64               |    Yes    |
+| Linux — x64 / arm64                 |    Yes    |
+
+**Intel Macs are not supported.** Neura's wake-word detector runs on
+`onnxruntime-node`, and upstream dropped Intel Mac (`darwin/x64`) binaries
+starting with version 1.24. Because voice is a required feature — not an
+optional one — `npm install -g @mclean-capital/neura` will appear to
+succeed but core will crash at startup with
+`Cannot find module '../bin/napi-v6/darwin/x64/onnxruntime_binding.node'`.
+
+If you're on an Apple Silicon Mac but see the `darwin/x64` error, you've
+installed the Intel build of Node under Rosetta. Reinstall Node as arm64:
+
+```bash
+nvm uninstall <version>
+arch -arm64 nvm install <version>
+```
+
+For true Intel Macs, there's no workaround short of self-building against
+an older onnxruntime-node — we recommend running Neura on a supported
+machine instead.
 
 ## Quick start
 
 ```bash
 neura install     # interactive setup: API keys, auto-port, service registration
-neura start       # start the core service
-neura chat        # text chat with Neura from your terminal
-neura listen      # voice chat (mic + speaker)
+                  # (auto-starts the core service)
+neura listen      # voice chat (mic + speaker, wake-word ready)
+# OR:
+neura chat        # text chat from your terminal
+```
+
+After `neura install` completes, core runs as a background OS service — launchd on macOS, systemd on Linux, a Scheduled Task (or Startup folder shim as fallback) on Windows. Say your wake word — by default **"jarvis"** — and Neura activates a voice session. Stop talking for 5 minutes and it drops back to passive listening.
+
+### Windows notes
+
+Windows doesn't have a clean "run as background service" path for a voice-first assistant. A proper Windows Service (via `sc.exe`, nssm, or WinSW) runs in **Session 0**, which is isolated from every interactive user session and cannot access the user's microphone or audio devices — a hard blocker for wake-word detection. So on Windows we use a per-user **Scheduled Task** instead, registered by `schtasks.exe` with `/SC ONLOGON /RL LIMITED`. No UAC prompt, no admin rights, no bundled binaries.
+
+If `schtasks /Create` refuses (some corporate / GPO-locked Windows configurations require elevation even for user-level tasks), `neura install` transparently falls back to a `neura-core.cmd` launcher in `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\`. The core still starts on next logon — `neura install` will tell you which path was taken so you know what to expect.
+
+Trade-offs you should know about on Windows:
+
+- **The core only runs while you're logged in.** When you log out, it stops; when you log back in, Windows starts it again. There's no pre-login boot. If you need 24/7 availability, use macOS or Linux.
+- **Status telemetry is thinner** than a real service. `neura status` reports up/down by pid, but there's no Windows event-log integration or automatic crash-restart policy beyond "start fresh on next logon".
+- **The Task Scheduler path is manageable from the GUI.** Open Task Scheduler and look for `neura-core` under the top-level Task Scheduler Library. If you took the Startup folder fallback, the shim is at the path above — delete the file to disable.
+
+`neura config set` works normally on Windows. The launcher shim only exports `NEURA_HOME`, so the core re-reads `config.json` on every restart — same behavior as macOS and Linux. Changes take effect on the next `neura restart` without needing `neura install`.
+
+## Update
+
+```bash
+neura update
+# equivalent to: npm install -g @mclean-capital/neura@latest && neura restart
 ```
 
+The `neura update` command runs `npm install -g @mclean-capital/neura@latest` and restarts the core service so the new version takes effect.
+
+### Upgrading from v1.10.x or earlier
+
+v1.11.0 moved the core service bundle from a separate GitHub release tarball into the CLI's npm package itself. Older CLIs expect the tarball layout and **cannot self-update to v1.11.0**. If you're on v1.10.x and `neura update` prints a 404 or "Download failed" error, bootstrap manually:
+
+```bash
+npm install -g @mclean-capital/neura@latest
+neura install   # rewrites service file to point at the new bundled core path
+```
+
+After this one-time step, `neura update` works normally for all future upgrades.
+
 ## Commands
 
 ### Setup & service lifecycle