@kognai/build 0.6.0

package/README.md

@@ -0,0 +1,91 @@
+# @kognai/build
+
+> The Kognai sovereign orchestrator as a CLI. Submit a task or a goal; get reviewed, compliance-gated deliverables — or a rejection with reasons. Runs on the cloud or **fully local ($0)**.
+
+```bash
+npx @kognai/build "TypeScript email validator function"
+```
+
+## What it does
+
+Every task runs a real pipeline, not a single LLM call:
+
+```
+generate → code review (primary) → code review (second pass) → compliance review → ship | reject
+```
+
+The third review (compliance) checks constitutional, legal, and security concerns and is **non-overridable** — a code-grade-A deliverable with a compliance FAIL is rejected. That's what distinguishes the Kognai runtime from a thin LLM wrapper.
+
+Under the hood it routes every model call through [`@kognai/orchestrator-core`](https://www.npmjs.com/package/@kognai/orchestrator-core), so you get tiered routing, cost accounting, and an optional local ($0) backend for free.
+
+## Install / Run
+
+```bash
+# zero-install
+export ANTHROPIC_API_KEY=sk-ant-...
+npx @kognai/build "<task>"
+
+# or globally — gives you `kognai` (REPL) and `kognai-build` (one-shot)
+npm install -g @kognai/build
+kognai
+```
+
+## Modes
+
+```bash
+# Task — one deliverable through the triple-supervisor
+kognai-build "Stripe webhook handler" --out src/webhook.ts
+
+# Goal — decompose into tasks, run each (TICKET-135 hierarchy)
+kognai-build --goal "Express CRUD service with Postgres" --out-dir ./svc
+
+# Sovereign — all inference local via Ollama ($0, no API key)
+kognai-build "log shipper" --sovereign
+
+# Swarm — delegate to the FULL orchestrator-core swarm
+#   (CEO planning · CTO governance gate · dual-supervisor · reconciliation)
+kognai-build --swarm "auth service with JWT" --out-dir ./auth
+
+# Mandate — sign a PACT mandate (cost envelope) before executing
+kognai-build --mandate "research synthesis tool" --out-dir ./tool
+
+# Optimization profile — coder + reviewers optimize for one axis
+kognai-build --goal "payments API" --profile security
+```
+
+Flags: `--out <path>` · `--out-dir <dir>` · `--sovereign` · `--swarm` · `--mandate` · `--profile <axis>` · `--no-compliance`
+
+## Sovereign mode
+
+`--sovereign` routes **all** inference to a local Ollama instance — coder, supervisors, and (in `--swarm`) the CEO/CTO too. No `ANTHROPIC_API_KEY` required, `$0` cost floor. Requires [Ollama](https://ollama.com) running locally with a capable model (e.g. `qwen3:14b`).
+
+## Workspace (`.kognai/`)
+
+Drop a `.kognai/config.yaml` in your project and the CLI binds to it: deliverables go to your configured root, runs are measured (KSL), and you can extend the registries via `.kognai/tools.json` / `.kognai/skills.json`.
+
+## Configuration
+
+| Env var              | Default              | Purpose                                   |
+|----------------------|----------------------|-------------------------------------------|
+| `ANTHROPIC_API_KEY`  | (required for cloud) | Claude API auth — not needed with `--sovereign` |
+| `CLAUDE_MODEL`       | `claude-sonnet-4-6`  | Override the cloud coder + reviewer model |
+
+## Compliance gate
+
+The non-overridable third reviewer checks:
+
+**Constitutional (the 3 Laws):** 1) Never Harm · 2) Earn Existence (no fake/deceptive functionality, fabricated metrics, hidden surveillance) · 3) Transparency to Creator (no obfuscation, embedded credentials, undisclosed telemetry).
+
+**Legal / Regulatory:** GDPR consent gates · tax-evasion shortcuts · copyleft lift.
+
+**Security (auto-fail):** hard-coded secrets · injection vectors · disabled TLS · eval on untrusted input.
+
+A FAIL on any category rejects the deliverable. Override with `--no-compliance` only for trusted local prototypes — never production.
+
+## Cost
+
+Cloud: ~$0.01–0.05 per task (the footer prints actual spend). `--sovereign`: $0. `--swarm` runs the full leadership ceremony and costs more per goal.
+
+## License
+
+MIT