chore: remove internal documents and service directories (P2.2 part 1)

The commercial repository carries the product's internal history: audits,
screenshots, briefs, decisions, pricing, publication drafts, personal data
and research runs. None of it belongs in the community edition.

- delete judging/, "UAT 3/", benchmarks/ (including LoCoMo data under
  CC BY-NC), preflight-results/, gepa-phase-5/, notes/, decisions/,
  .understand-anything/, .agents/, .lovable/, the legacy sidecar/ package
  and waggle-cowork/ (an analysis of Claude Code sources)
- delete docs/ except docs/oss, the user guides (without the team-mode
  guide), the reference, methodology, architecture, getting-started and
  contributing pages, which P2.4 rewrites
- delete render.yaml, .parity-allowlist, the retired mind-parity and
  sync-mind workflows and 29 one-off scripts nothing references
- delete tests that only checked removed files (sidecar package, Render
  blueprint, UAT capture, benchmark harness isolation, internal audit and
  signing docs); drop sidecar/ and benchmarks/ from the hive-mind subtree
  split guard; prune ignore, attribute, lint and test globs
- replace the commercial README with an interim one for this edition

Source comments still point at some deleted docs; P2.2 part 2 cleans them
together with names and paths.
This commit is contained in:
shumeiko.it
2026-10-20 01:02:18 +02:00
parent 2e1999a3f6
commit 5f088698dd
1383 changed files with 67 additions and 503605 deletions

226
README.md
View File

@@ -1,201 +1,89 @@
# Waggle OS
# Waggle OS Community Edition
Workspace-native AI agent platform with persistent memory, model-agnostic orchestration, and skill-extensible capabilities. The current desktop release scope is Windows-first: a Tauri 2.0 app with a Vite-bundled web UI and bundled Node.js sidecar; macOS packaging and certification remain roadmap work.
Waggle is a local-first AI workspace: an agent with persistent memory, personas, skills,
connectors and scheduled automations. It runs as a Node.js sidecar with a React web UI, and
can be wrapped in a Tauri desktop shell. You bring your own model: a local model through
Ollama or a provider API key.
## Current Release Scope
> **Status: work in progress.** This branch is being converted from the commercial Waggle
> OS codebase into an open-source community edition. Billing, KVARK, compliance reporting
> and self-learning are already removed; memory is moving to a local mem0 store, and
> installers for Windows, macOS and Linux are not ready yet. The rules for this conversion
> are in [`AGENTS.md`](AGENTS.md) and the decision records in
> [`docs/oss/adr/`](docs/oss/adr/README.md).
The active launch gate is **Windows Solo**. Its in-scope external-agent release cohort is **Claude Code, Codex, and Hermes**. Each tool uses the user's own installation and authentication; Waggle does not redistribute provider credentials or bypass provider terms.
- **Cursor and OpenClaw are roadmap integrations.** They remain registered for detection and future development, but the production launcher, hooks, Fleet/task path, and direct run API do not offer them.
- Claude Desktop, Codex Desktop, and Hermes Desktop may appear as detected convenience launch surfaces; they are not separate memory-hook or agent-acceptance targets in this release gate.
- **ChatGPT/OpenAI is a model and memory-import surface**, not a separate local coding-agent launcher.
- The Windows Solo launch contract requires an exact-revision Windows installer qualification receipt to prove its bundled Node sidecar, no-Python OpenAI-compatible proxy, Waggle-managed local runtime/model, default in-process embedding path, and freedom from developer Node, Docker, Python, an external LiteLLM service, or a separately installed Ollama. A separate revision-bound router receipt must prove the smart-router primary, compact-tool-context, budget, and fallback paths. Router, persona, and authentication receipts may cover a later candidate only through an independently reviewed bounded no-impact attestation proving that no covered runtime surface changed; otherwise they must be rerun. A user-installed Ollama remains optional.
- Docker/LiteLLM deployment files remain optional server and team deployment choices; they are not desktop prerequisites.
Release status, revision-bound receipts, and any bounded carry-forward attestations are governed only by the current [launch recommendation](docs/production-readiness/09-LAUNCH_RECOMMENDATION.md). If it does not say **GO**, do not describe Waggle as production-ready or reuse historical scores or receipts as current release evidence.
### Current Windows Solo internal RC evidence — 2026-08-27
The current runtime candidate is private `main` commit
`23ad3fa5f99bddce648b84750a41365299aeb0da`. Its internal-pilot NSIS installer
(102,923,936 bytes; SHA-256
`7BFA9F9B13633A51CD3336B42E3EF904B7F7A568C6DEE4F6CED967CBD4F40A59`)
passed **64/64** clean-profile checks. The receipt proves bundled sidecar and offline
npm, FREE/Solo first boot, in-process embeddings, the Waggle-managed local runtime and
`qwen2.5:0.5b`, local-model chat, proxy restart, repair, relaunch, data preservation,
Exit/cleanup, and uninstall. Docker, Python, developer Node.js, external LiteLLM, and a
separately installed Ollama were not prerequisites.
- Private PR #66 merged as `23ad3fa5` after every blocking check passed: primary CI,
Playwright smoke and full E2E, Windows and both macOS Tauri verification targets, and
Hive Mind install/smoke on Windows, Ubuntu, and macOS. The tested PR head and merged
source have the same tree.
- Exact-current full and production dependency audits contain **0 Critical and 0 High**
findings. Lower-severity maintenance remains documented.
- The historical persona collection at `4c712ff6` still records all ten personas x3 at
or above 95/100 after documented independent adjudication, but it is not relabeled as
an exact-current seal. PR #66 changed memory behavior, so public release qualification
requires a fresh receipt or an explicit bounded semantic-impact attestation.
- Smart-router primary, compact-tool-context, durable-budget and fallback evidence, plus
the Claude Code, Codex, and Hermes official-user-auth canaries, remain historical
scoped evidence. No later change touched provider credential handling; the auth
harness read or copied no credential files.
- The curated Hive Mind mirror is hardened through private-to-maintainer PR #53, merged
on public `master` as `3410327800db3ea23f875d547a0c7f4d08826b7e`; Windows, macOS,
Ubuntu, and Ubuntu first-run smoke were green. The immutable drift baseline still
reports reviewed release blockers, so the next OSS package release remains a separate
maintainer-curated operation and is not implied by this Windows Solo RC.
Detailed local receipt paths, hashes, limitations, and integration gates are recorded in
the current [launch recommendation](docs/production-readiness/09-LAUNCH_RECOMMENDATION.md).
The internal signer (`CN=Egzakta Internal Pilot`) and DigiCert timestamp prove the pilot
pipeline but are not publicly trusted Authenticode. Public release is **not yet approved**:
a protected hosted build with a publicly trusted signer, an exact-candidate sealed
managed Deep Security report, current persona qualification, and either fresh or
explicitly attested smart-router and official-auth qualification remain mandatory.
## Architecture
## Repository layout
```
waggle-os/
├── apps/
│ ├── web/ # Main web app UI (React 19 + Vite + Tailwind 4 + base-ui/react)
│ ├── www/ # Marketing site (Next.js)
│ └── browser-ext/ # Browser extension (unpacked; not an npm workspace)
├── packages/ # 28 workspace packages (see "Packages" below)
├── app/ # Tauri 2.0 desktop shell (Rust) — loads the apps/web build
├── sidecar/ # Node.js sidecar bundled into the Tauri desktop binary
└── docs/ # Architecture, contributing, threat model, and guides
├── apps/web/ # Web UI (React 19, Vite, Tailwind 4)
├── app/ # Tauri 2 desktop shell (Rust); loads the apps/web build
├── packages/ # npm workspaces: agent, server, core, shared, marketplace,
│ # memory-contract, memory-mem0, cli, launcher, sdk, weaver, ...
└── docs/ # Guides, reference, and docs/oss for the community edition
```
### Packages
`AGENTS.md` lists the status of every package in this edition.
The monorepo has **28 packages** under `packages/`. They split into two groups.
## Run from source
**Product packages (15, MIT):**
| Package | Purpose |
|---|---|
| `agent` | Agent loop, orchestrator, tools, personas, workflows, and the evolution subsystem |
| `core` | Config, the encrypted vault, cron store, file store, telemetry, and compliance/audit |
| `server` | Fastify sidecar — local (solo) and team routes, SSE streaming, Stripe, KVARK client |
| `shared` | Shared types, Zod schemas, the tier system, and the MCP catalog |
| `marketplace` | Package catalog with the `SecurityGate` installer |
| `optimizer` | GEPA prompt optimization |
| `weaver` | Memory consolidation daemon |
| `waggle-dance` | Multi-agent coordination protocol |
| `worker` | Background job processor (BullMQ, team mode) |
| `sdk` | Plugin / skill SDK |
| `cli` | Command-line REPL |
| `launcher` | AI-tool launcher / dock backend |
| `admin-web` | Admin dashboard for team deployments |
| `wiki-compiler` | Knowledge / wiki compiler |
| `memory-mcp` | MCP server exposing the memory substrate to external agents |
**Memory substrate — `hive-mind-*` (13, Apache-2.0):** the persistent-memory core, mirrored to the public OSS repo [`marolinik/hive-mind`](https://github.com/marolinik/hive-mind).
| Package | Purpose |
|---|---|
| `hive-mind-core` | The memory substrate: `FrameStore`, `HybridSearch`, `KnowledgeGraph`, `IdentityLayer`, `AwarenessLayer`, plus Harvest ingestion (`src/mind` + `src/harvest`) |
| `hive-mind-cli` | CLI for the substrate |
| `hive-mind-mcp-server` | MCP server for the substrate |
| `hive-mind-shim-core` | Signal-emitter shim library |
| `hive-mind-wiki-compiler` | Wiki compiler (OSS) |
| `hive-mind-hooks-core` | Shared hook library |
| `hive-mind-hooks-*` | Per-tool capture hooks: `claude-code`, `claude-desktop`, `codex`, `codex-desktop`, `cursor`, `hermes`, `openclaw` |
> The memory substrate is developed **here** and mirrored out — never the reverse.
> See the "Memory Substrate Sync" section of [`CLAUDE.md`](./CLAUDE.md) before touching `packages/hive-mind-core`.
## Quick Start
### Windows Solo desktop
Use only the signed Windows installer and SHA-256 identified by a **GO** [launch recommendation](docs/production-readiness/09-LAUNCH_RECOMMENDATION.md). If that recommendation is not GO, no packaged desktop artifact is release-approved; use the source-development instructions below.
### Self-host from the private repository (Linux / macOS)
Prerequisites: Node.js `^20.19.0` or `>=22.12.0`, and npm.
```bash
gh repo clone marolinik/waggle-os
cd waggle-os
bash install.sh
```
This path is for maintainers with authenticated access to the private repository.
Do not publish an anonymous raw-file installer until the source/licensing decision is explicit.
Best for a VPS or homelab — this runs a headless Waggle server (no desktop shell):
- **Checks prerequisites, clones, builds, and starts** the Node.js sidecar, then prints the URL (`http://127.0.0.1:3333`). A 5-question wizard — install dir, port, data dir, build web UI, start now — is all Enter-defaulted; pass `--yes` to accept every default non-interactively.
- **Boots with zero API keys** in echo mode so the UI works immediately. Add a provider key later under **Settings → API Keys**, where it is stored in the encrypted vault — keys are never passed on the command line.
- **No sudo, ever.** A missing prerequisite prints the exact per-OS install command and exits; the installer never installs system packages for you.
Manage the running server with the installed wrapper: `scripts/waggle-server.sh status | logs | stop | start`. Re-running the one-liner against an existing install prints an upgrade hint instead of reinstalling.
### Run from source (development)
```bash
# Prerequisites: Node.js ^20.19.0 or >=22.12.0, npm
npm install
# (Optional) copy the env template. Provider API keys are normally set in-app
# (Settings → API Keys), which stores them in the encrypted vault — so you do
# NOT need to put keys in .env for a basic local run.
cp .env.example .env
# Terminal 1 — backend sidecar (http://localhost:3333)
npm run dev:server
# Terminal 2 — web app (http://localhost:8080)
npm run dev:web
# Open http://localhost:8080
npm run build:packages # workspace packages export dist/; the sidecar needs it
npm run build # builds the web UI into dist/
npm run dev:server # the sidecar on http://localhost:3333, serving the UI
```
The source tree follows the root `package.json` Node engine above. The packaged
Windows Solo desktop carries its own pinned Node.js 22.23.2 runtime, so an
installed user does not need a separate Node.js installation.
Open http://localhost:3333. Rebuild the UI and restart the sidecar to see UI changes:
the Vite dev server (`npm run dev:web`) cannot authenticate against the sidecar yet
(UF-003 in [`docs/oss/upstream-fixes.md`](docs/oss/upstream-fixes.md)).
`npm run dev:server` runs the Fastify sidecar via `tsx` (equivalent to
`cd packages/server && npx tsx src/local/start.ts`). `npm run dev:web` runs the
Vite dev server for `apps/web`.
Provider keys are entered in the app under **Settings → API Keys** and stored in the
encrypted vault, so a basic local run needs no `.env` file. `.env.example` lists the
optional variables.
**Embeddings.** By default `EMBEDDING_PROVIDER=auto` downloads a small in-process
model (~23 MB, cached under `~/.waggle/models/`) and works fully offline. For
better recall — and to reproduce any hive-mind benchmark — install
[Ollama](https://ollama.com), run `ollama pull nomic-embed-text`, and set
**Embeddings.** By default `EMBEDDING_PROVIDER=auto` downloads a small in-process model
(about 23 MB, cached under `~/.waggle/models/`) and works offline. To use Ollama instead,
install [Ollama](https://ollama.com), run `ollama pull nomic-embed-text`, and set
`EMBEDDING_PROVIDER=ollama`.
> **Windows:** if the sidecar fails to start with an esbuild platform error, see
> [Troubleshooting](docs/CONTRIBUTING.md#troubleshooting) in the contributing guide.
| Variable | Description |
|---|---|
| `ANTHROPIC_API_KEY` | Claude API key; can be set in the app instead. |
| `OPENAI_API_KEY` | Enables OpenAI models and optional OpenAI embeddings. |
| `EMBEDDING_PROVIDER` | `auto` (default), `inprocess`, `ollama`, `voyage`, `openai` or `mock`. |
| `LITELLM_BASE_URL` | Optional external LiteLLM-compatible proxy. |
## Environment Variables
## Checks
Provider keys are stored in the encrypted vault (set via **Settings → API Keys**)
and hydrated into the process at boot, so most of these are optional for a local
run. See [`.env.example`](./.env.example) for the full contract.
```bash
npm run build:packages # build all workspace packages
npm run typecheck:web # type-check the web UI
npm run lint # lint the packages
npm run check:deps # every import is a declared dependency
npm test # unit tests
```
| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | Recommended | Claude API key. Optional in `.env` — can be set in-app instead (vault). |
| `OPENAI_API_KEY` | No | Enables OpenAI models and optional OpenAI embeddings. |
| `EMBEDDING_PROVIDER` | No | `auto` (default) · `inprocess` · `ollama` · `voyage` · `openai` · `mock`. `auto` tries in-process → Ollama → API → mock. |
| `LITELLM_BASE_URL` | No | Optional external LiteLLM-compatible proxy URL. The Windows Solo desktop uses its bundled no-Python proxy unless explicitly configured otherwise. |
| `DATABASE_URL` | Team only | PostgreSQL connection string. |
| `REDIS_URL` | Team only | Redis for the background job queue. |
Known failures and the numbers to compare against are in
[`docs/oss/baseline.md`](docs/oss/baseline.md).
## Documentation
- [Getting Started](docs/GETTING-STARTED.md) — first-run walkthrough
- [Architecture](docs/ARCHITECTURE.md) — package structure, data flow, extension points
- [Contributing](docs/CONTRIBUTING.md) — setup, tests, PR process, troubleshooting
- [Threat Model](THREAT_MODEL.md) — trust boundary and security controls
- [Security Policy](SECURITY.md) — how to report a vulnerability
- [Getting Started](docs/GETTING-STARTED.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Contributing](docs/CONTRIBUTING.md)
- [Threat Model](THREAT_MODEL.md)
- [Security Policy](SECURITY.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
The guides predate the community edition and still describe some removed features; they
are rewritten before the first release.
## License
This repository is licensed under the [MIT License](./LICENSE), **except** the
`hive-mind-*` packages under `packages/`, which are licensed under **Apache-2.0**.
Each `hive-mind-*` package carries its own `LICENSE` file, which governs that
package. See [Packages](#packages) for the split.
package.