@niq.run/niq-darwin-x64 0.1.1 → 0.2.0

package/bin/README.md

@@ -1,71 +1,95 @@
 # niq
 
-> **niq runs programs that haven't been written yet.**
-
-niq is an **event-driven, decentralized agent runtime**. It is a single agent, but one composed of many **Workers** (a Worker Swarm) that collaborate over an event bus — each worker handles its own focus, and together they form the complete agent.
+niq is an **event-driven agent runtime**. It is a single agent composed of many **Workers** that collaborate over an event bus — each worker handles its own focus, and together they form the complete agent.
 
 niq has exactly three core concepts:
 
-- **Worker** — a unit that can do things, like an **actor**: it has its own state and communicates only by sending and reacting to messages. A Worker subscribes to events, processes them, and publishes new events. Every capability (reasoning, tool execution, safety guards, lifecycle) is a Worker; there is only one extension concept.
-- **Program** — the source code of a Worker's capability (natural-language Prompts, or formalized DSL Scripts).
+- **Worker** — a unit that can do things, like an **actor**: it has its own state and communicates only by sending and reacting to messages. A Worker subscribes to events, processes them, and publishes new events. The Worker is niq's only extension point.
+- **Program** — the source code of a Worker's capability: a natural-language prompt (like the skills of mainstream agents) or a DSL script (like programmatic tool calling, PTC). Both forms are source code for generating tool calls.
 - **Event** — the only communication language between Workers, delivered over the event bus.
 
-Core insight: **collaboration is extension.** niq grows not by adding new abstractions, but by adding more participants that cooperate over the event bus. Extending a capability and having a human join the collaboration are the same act — a user is just another collaborating participant, and there can be one or many of them. In niq, everything is workers collaborating over the event bus.
+> **Collaboration is extension.**
+
+niq grows not by adding new abstractions, but by adding more participants that cooperate over the event bus. Every capability (reasoning, tool execution, safety guards, lifecycle) is a Worker. Extending a capability and having a human join the collaboration are the same act — a user is just another collaborating participant, and there can be one or many of them. In niq, everything is workers collaborating over the event bus.
 
 > **Status: early, fast-moving development.** The design is still evolving; APIs and behavior may change without notice.
 
-## Project layout
+## Install
 
+**npm** (recommended):
+
+```sh
+npm install -g @niq.run/niq
 ```
-core/         interfaces & types (contracts, not implementations)
-pkg/          implementations (workers, services, bus, transports)
-internal/     control plane, project runtime, WebUI
-cmd/          CLI entry point
-doc/          design docs & dev notes
+
+**Install script** (installs to `~/.niq/bin`):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/niq-run/niq/main/install.sh | sh
+```
+
+**From source** (Go 1.25+):
+
+```sh
+git clone https://github.com/niq-run/niq
+cd niq && make build   # → ./bin/niq
 ```
 
 ## Quick start
 
-### Prerequisites
+niq has two layers: a **control plane**, and **projects** — each project is an isolated agent instance with its own event bus, worker set and WebUI on its own ports.
 
-- Go 1.22+
-- A model API key (for the reason worker), set in `~/.zshenv`:
+```sh
+# start the control plane (default :9527)
+niq
+```
 
-  ```sh
-  export OPENAI_API_KEY=sk-xxxx
-  ```
+Open **http://localhost:9527** — the control plane's WebUI lists your projects and can create and start one from a template, no terminal needed.
 
-### Run
+Prefer the CLI? Both steps can also be done manually:
 
 ```sh
-# Start the control plane (listens on :9527 by default)
-cd niq && go run ./cmd/niq/
+niq project create my-project
+niq project run my-project
+```
 
-# Or build first
-make build
-./bin/niq
+Each project serves its own WebUI — use it to chat, watch the event flow and manage workers. Ports are assigned dynamically on first run and then persisted per project, so they stay stable across restarts (`--bus` / `--webui` override). `niq project list` shows each project's `webui` and `bus` ports.
 
-# Then create and run a project from the WebUI, or from the CLI:
-./bin/niq project create my-project
-./bin/niq project run my-project
-```
+### Model provider
 
-Once started, open <http://localhost:19763> for the WebUI — chat, inspect events, and view workers.
+The `reason` worker talks to an LLM provider. Provider settings (endpoint, model, API key) live in `~/.niq/common/providers/provider.json`; `api_key` and header values support environment-variable expansion — e.g. `"api_key": "${OPENAI_API_KEY}"` keeps secrets out of stored files.
+
+## Project layout
+
+```
+core/      interfaces & types (contracts, not implementations)
+pkg/       implementations (workers, services, bus, transports)
+internal/  control plane, project runtime, WebUI
+cmd/       CLI entry point
+npm/       npm distribution (launcher shim + package template)
+ext/       external worker implementations (HTTP)
+```
 
-### Build & test
+## Build & test
 
 ```sh
-cd niq && go build ./... && go vet ./...
-cd niq && go test ./pkg/eventbus/ -count=1
+go build ./... && go vet ./...
+go test ./pkg/eventbus/ -count=1
 ```
 
-### Data directory
+## Data directory
 
 Runtime data lives under `~/.niq/`:
 
 ```
 ~/.niq/
-  ├── id/identities.json    # worker identity registry (owned by the bus)
-  ├── programs/             # Program storage
-  └── niq.log               # run log
+  bin/                         prebuilt binary (install.sh)
+  niq.log                      control-plane log
+  common/
+    templates/                 project templates
+    providers/provider.json    shared provider config (API keys via env expansion)
+  projects/<id>/               one directory per project
+    id/identities.json         worker identity registry (owned by the bus)
+    programs/                  Program storage
+    logs/                      daily-rotated run logs
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niq.run/niq-darwin-x64",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "niq binary for darwin-x64",
   "license": "MIT",
   "os": ["darwin"],