create-yonderclaw 1.0.0

package/LICENSE

@@ -0,0 +1,44 @@
+MIT License
+
+Copyright (c) 2025 Yonder Zenith LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTICE REGARDING QIS PROTOCOL
+
+MetaClaw includes optional integration with the QIS (Quadratic Intelligence
+Swarm) Network, a service operated by Yonder Zenith LLC. The QIS
+Protocol is separately licensed and protected by 39 pending US patent
+applications covering distributed pattern synthesis methods.
+
+Use of the QIS Intelligence Network relay is governed by the QIS Protocol
+License v1.0, available at:
+https://yonderzenith.github.io/QIS-Protocol-Website/licensing.html
+
+The MIT License above applies to the MetaClaw installer and agent framework
+code only. It does not grant any rights under the QIS Protocol License or
+any associated patent rights.
+
+MetaClaw agents may connect to the QIS relay as end users of the service.
+Implementing, replicating, or reverse-engineering the QIS Protocol routing
+methods requires a separate license from Yonder Zenith LLC.
+
+Contact: contactyz@pm.me

package/README.md

@@ -0,0 +1,288 @@
+<p align="center">
+  <img src="docs/assets/yz-logo.png" alt="Yonder Zenith" width="200" />
+</p>
+
+<p align="center">
+  <img src="docs/assets/yonderclaw-banner.svg" alt="YonderClaw" width="700" />
+</p>
+
+<p align="center">
+  <strong>Autonomous AI Agents — Plug & Play</strong><br/>
+  <em>Deploy self-improving AI agents in minutes, not months.</em>
+</p>
+
+<p align="center">
+  <a href="#quick-start"><img src="https://img.shields.io/badge/get_started-00BEEA?style=for-the-badge&logo=rocket&logoColor=white" alt="Get Started" /></a>
+  <a href="https://yonderzenith.github.io/YonderClaw/"><img src="https://img.shields.io/badge/docs-00D9FF?style=for-the-badge&logo=readthedocs&logoColor=white" alt="Docs" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-10B981?style=for-the-badge" alt="MIT License" /></a>
+  <img src="https://img.shields.io/badge/version-3.3.0-FFD700?style=for-the-badge" alt="Version 3.3.0" />
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/node-18+-339933?style=flat-square&logo=node.js&logoColor=white" />
+  <img src="https://img.shields.io/badge/claude_code-CLI-00BEEA?style=flat-square&logo=anthropic&logoColor=white" />
+  <img src="https://img.shields.io/badge/platform-Windows-0078D6?style=flat-square&logo=windows&logoColor=white" />
+  <img src="https://img.shields.io/badge/database-SQLite-003B57?style=flat-square&logo=sqlite&logoColor=white" />
+  <img src="https://img.shields.io/badge/self--improving-yes-FFD700?style=flat-square" />
+</p>
+
+---
+
+## What is YonderClaw?
+
+YonderClaw is an **autonomous agent factory**. Pick an agent template, answer a few questions, and YonderClaw researches best practices, scaffolds the entire project, configures safety guardrails, builds a real-time dashboard, and launches your agent — all automatically.
+
+Your agents don't just run. They **learn, adapt, and improve themselves** through prompt versioning, A/B testing, and automatic optimization — governed by constitutional principles you define.
+
+```
+  ╔══════════════════════════════════════════════════════════════╗
+  ║                                                              ║
+  ║   You describe what you need.                                ║
+  ║   YonderClaw builds the agent.                                 ║
+  ║   The agent improves itself.                                 ║
+  ║                                                              ║
+  ╚══════════════════════════════════════════════════════════════╝
+```
+
+### Built on Claude Code — Runs on Your Max/Pro Subscription
+
+> **No API keys. No per-token billing. No surprise invoices.**
+>
+> YonderClaw is powered by **Claude Code CLI**, which means your agents run on your existing **Claude Max or Pro subscription** at a flat monthly rate. While other agent frameworks rack up per-token API costs, YonderClaw agents run unlimited on what you're already paying for.
+
+---
+
+## Quick Start
+
+```bash
+# One command — that's it
+npx create-yonderclaw
+```
+
+Or clone the repo:
+
+```bash
+git clone https://github.com/YonderZenith/YonderClaw.git
+cd YonderClaw
+npm install
+npm start
+```
+
+Or on Windows — just double-click **`setup.bat`**.
+
+The installer handles everything: detects your system, installs prerequisites, walks you through configuration, and deploys your agent.
+
+---
+
+## Agent Types
+
+<table>
+<tr>
+<td width="20%" align="center">
+<h3>🎯</h3>
+<strong>Outreach Claw</strong><br/>
+<sub>Email prospecting, follow-ups, auto-reply campaigns</sub>
+</td>
+<td width="20%" align="center">
+<h3>🔬</h3>
+<strong>Research Claw</strong><br/>
+<sub>Deep web research, source synthesis, report generation</sub>
+</td>
+<td width="20%" align="center">
+<h3>🛡️</h3>
+<strong>Support Claw</strong><br/>
+<sub>Inbox monitoring, ticket triage, intelligent auto-response</sub>
+</td>
+<td width="20%" align="center">
+<h3>📡</h3>
+<strong>Social Claw</strong><br/>
+<sub>Content creation, scheduling, engagement tracking</sub>
+</td>
+<td width="20%" align="center">
+<h3>⚡</h3>
+<strong>Custom Claw</strong><br/>
+<sub>Describe what you need — Claude configures it</sub>
+</td>
+</tr>
+</table>
+
+---
+
+## Architecture
+
+Every YonderClaw agent is a **self-contained autonomous system** with a file-based brain:
+
+```
+                    ┌─────────────────────────────────┐
+                    │         CLAUDE.md                │
+                    │    (Agent Identity + Rules)      │
+                    └────────────┬────────────────────┘
+                                 │ reads on every cycle
+                    ┌────────────▼────────────────────┐
+                    │         SOUL.md                  │
+                    │   (Constitutional Principles)    │
+                    └────────────┬────────────────────┘
+                                 │
+              ┌──────────────────┼──────────────────┐
+              │                  │                  │
+     ┌────────▼───────┐ ┌───────▼────────┐ ┌───────▼───────┐
+     │   state.json   │ │  tasks.json    │ │  memory/      │
+     │  (Agent State) │ │  (Task Queue)  │ │  (Knowledge)  │
+     └────────┬───────┘ └───────┬────────┘ └───────┬───────┘
+              │                 │                   │
+              └─────────────────┼───────────────────┘
+                                │
+                    ┌───────────▼──────────────┐
+                    │      agent.ts            │
+                    │   (13-Step Main Loop)    │
+                    │                          │
+                    │  ┌─ health-check.ts      │
+                    │  ├─ safety.ts            │
+                    │  ├─ self-improve.ts      │
+                    │  ├─ db.ts (SQLite)       │
+                    │  └─ cron-manager.ts      │
+                    └───────────┬──────────────┘
+                                │
+                    ┌───────────▼──────────────┐
+                    │     dashboard.html       │
+                    │   (Real-time Command     │
+                    │    Center + Voice)       │
+                    └──────────────────────────┘
+```
+
+---
+
+## What Every Agent Gets
+
+<table>
+<tr>
+<td>
+
+**Core Engine**
+- 13-step autonomous main loop
+- SQLite database (WAL mode, 11 tables)
+- Structured JSONL logging with 30-day rotation
+- Health checks on every cycle
+
+</td>
+<td>
+
+**Safety First**
+- Circuit breakers with configurable thresholds
+- Rate limiting (daily + hourly caps)
+- Constitutional principles (SOUL.md)
+- Dry-run mode for testing
+
+</td>
+</tr>
+<tr>
+<td>
+
+**Self-Improvement**
+- Prompt versioning and A/B testing
+- Automatic strategy optimization
+- Performance metrics tracking
+- Logic logging for decision auditing
+
+</td>
+<td>
+
+**Operations**
+- HTML Command Center with voice control
+- Windows Task Scheduler integration
+- Auto-start on boot
+- Desktop shortcut deployment
+
+</td>
+</tr>
+</table>
+
+---
+
+## Generated Agent Structure
+
+```
+my-agent/
+├── CLAUDE.md              # Agent identity, rules, and context
+├── SOUL.md                # Constitutional principles
+├── dashboard.html         # Command Center (open in browser)
+├── src/
+│   ├── agent.ts           # Main 13-step autonomous loop
+│   ├── db.ts              # SQLite database layer
+│   ├── safety.ts          # Circuit breaker + rate limits
+│   ├── self-improve.ts    # Prompt evolution engine
+│   ├── health-check.ts    # System validation
+│   └── cron-manager.ts    # Scheduled task management
+├── data/
+│   ├── state.json         # Live agent state
+│   ├── tasks.json         # Human + AI task tracking
+│   └── logs/              # Structured JSONL logs
+├── scripts/
+│   ├── launch.bat         # Start agent
+│   └── agent-cycle.bat    # Autonomous cron cycle
+└── memory/                # Agent knowledge files
+```
+
+---
+
+## Optional: QIS Intelligence Network
+
+<p align="center">
+  <img src="docs/assets/qis-logo.png" alt="QIS Protocol" width="120" />
+</p>
+
+YonderClaw agents can optionally connect to the **QIS (Quadratic Intelligence Swarm) Network** — a shared knowledge layer where agents deposit and query operational insights.
+
+```
+  Agent A ──deposit──▶ ┌──────────────┐ ◀──query── Agent C
+                       │  QIS Relay   │
+  Agent B ──deposit──▶ │  (Buckets)   │ ◀──query── Agent D
+                       └──────────────┘
+```
+
+- **No PII** flows through the network — only anonymized operational intelligence
+- All personal data (emails, contacts, transcripts) **stays on your machine**
+- The QIS Intelligence Network is a separate service operated by Yonder Zenith LLC
+
+> The QIS Protocol is protected by 39 pending US patent applications.
+> See [QIS Protocol License](https://yonderzenith.github.io/QIS-Protocol-Website/licensing.html) for details.
+
+---
+
+## Requirements
+
+| Requirement | Details |
+|------------|---------|
+| **Node.js** | v18 or higher (installer helps you get it) |
+| **Claude Code CLI** | Installed globally (installer helps you get it) |
+| **Claude Access** | Claude Max or Pro subscription required (or Anthropic API key) |
+| **OS** | Windows 10/11 (macOS/Linux support coming) |
+
+---
+
+## Commands
+
+```bash
+npm start              # Launch installer / start agent
+npm run dry-run        # Test without taking actions
+npm run status         # Check agent status
+npm run dashboard      # Regenerate dashboard
+npm run health-check   # Run system validation
+npm run self-update    # Trigger self-optimization
+```
+
+---
+
+## License
+
+YonderClaw is released under the **[MIT License](LICENSE)** — use it, modify it, build on it.
+
+The optional QIS Intelligence Network is a separately licensed service by Yonder Zenith LLC.
+
+---
+
+<p align="center">
+  <img src="docs/assets/yz-favicon.png" alt="YZ" width="32" /><br/>
+  <sub>Built by <a href="https://yonderzenith.github.io/QIS-Protocol-Website/"><strong>Yonder Zenith LLC</strong></a></sub><br/>
+  <sub><em>Redefining the Horizon</em></sub>
+</p>

package/bin/create-yonderclaw.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { execFileSync } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, "..");
+const entry = join(root, "installer", "index.ts");
+
+// Find tsx binary — check own node_modules, parent (npm flattened), and up
+const search = [
+  join(root, "node_modules", ".bin"),
+  join(root, "..", ".bin"),
+  join(root, "..", "..", ".bin"),
+];
+
+let tsxBin = null;
+for (const dir of search) {
+  const cmd = join(dir, process.platform === "win32" ? "tsx.cmd" : "tsx");
+  if (existsSync(cmd)) { tsxBin = cmd; break; }
+}
+
+if (!tsxBin) {
+  // Last resort: try npx cache location
+  const npxCache = join(root, "..", "..", "node_modules", ".bin", process.platform === "win32" ? "tsx.cmd" : "tsx");
+  if (existsSync(npxCache)) tsxBin = npxCache;
+}
+
+if (!tsxBin) {
+  console.error("Error: Could not find tsx. Install YonderClaw via: git clone + npm install + npm start");
+  process.exit(1);
+}
+
+try {
+  execFileSync(tsxBin, [entry], {
+    stdio: "inherit",
+    cwd: root,
+    shell: tsxBin.endsWith(".cmd"),
+  });
+} catch (e) {
+  process.exit(e.status || 1);
+}

package/docs/assets/metaclaw-banner.svg

@@ -0,0 +1,86 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 180">
+  <defs>
+    <linearGradient id="cyanGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#00BEEA;stop-opacity:1" />
+      <stop offset="50%" style="stop-color:#00D9FF;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#00BEEA;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="goldGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#FFD700;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#00BEEA;stop-opacity:1" />
+    </linearGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="3" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+    <filter id="softGlow">
+      <feGaussianBlur stdDeviation="8" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="700" height="180" fill="#0a0e17" rx="12"/>
+
+  <!-- Subtle grid lines -->
+  <g opacity="0.05" stroke="#00BEEA">
+    <line x1="0" y1="45" x2="700" y2="45"/>
+    <line x1="0" y1="90" x2="700" y2="90"/>
+    <line x1="0" y1="135" x2="700" y2="135"/>
+    <line x1="175" y1="0" x2="175" y2="180"/>
+    <line x1="350" y1="0" x2="350" y2="180"/>
+    <line x1="525" y1="0" x2="525" y2="180"/>
+  </g>
+
+  <!-- Decorative nodes -->
+  <circle cx="80" cy="40" r="3" fill="#00BEEA" opacity="0.3" filter="url(#softGlow)"/>
+  <circle cx="620" cy="140" r="3" fill="#00BEEA" opacity="0.3" filter="url(#softGlow)"/>
+  <circle cx="150" cy="150" r="2" fill="#00D9FF" opacity="0.2"/>
+  <circle cx="550" cy="30" r="2" fill="#00D9FF" opacity="0.2"/>
+  <circle cx="650" cy="60" r="2" fill="#FFD700" opacity="0.15"/>
+  <circle cx="50" cy="120" r="2" fill="#FFD700" opacity="0.15"/>
+
+  <!-- Decorative connection lines -->
+  <line x1="80" y1="40" x2="150" y2="70" stroke="#00BEEA" stroke-width="0.5" opacity="0.1"/>
+  <line x1="550" y1="30" x2="620" y2="60" stroke="#00BEEA" stroke-width="0.5" opacity="0.1"/>
+  <line x1="550" y1="140" x2="620" y2="140" stroke="#00D9FF" stroke-width="0.5" opacity="0.1"/>
+
+  <!-- Claw icon -->
+  <g transform="translate(115, 55)" filter="url(#glow)">
+    <path d="M0 35 Q5 0 20 10 Q25 20 20 35" fill="none" stroke="url(#cyanGrad)" stroke-width="2.5" stroke-linecap="round"/>
+    <path d="M15 30 Q20 -5 35 5 Q40 15 35 35" fill="none" stroke="url(#cyanGrad)" stroke-width="2.5" stroke-linecap="round"/>
+    <path d="M30 30 Q35 0 50 10 Q55 20 50 35" fill="none" stroke="url(#cyanGrad)" stroke-width="2.5" stroke-linecap="round"/>
+    <!-- Palm arc -->
+    <path d="M5 35 Q25 55 45 35" fill="none" stroke="url(#goldGrad)" stroke-width="2" stroke-linecap="round"/>
+  </g>
+
+  <!-- Main title -->
+  <text x="185" y="95" font-family="'Segoe UI', system-ui, -apple-system, sans-serif" font-size="56" font-weight="700" fill="url(#cyanGrad)" filter="url(#glow)" letter-spacing="-1">
+    MetaClaw
+  </text>
+
+  <!-- Version badge -->
+  <rect x="470" y="70" width="70" height="24" rx="12" fill="#FFD700" opacity="0.15"/>
+  <rect x="470" y="70" width="70" height="24" rx="12" fill="none" stroke="#FFD700" stroke-width="1" opacity="0.4"/>
+  <text x="505" y="87" font-family="'Segoe UI', system-ui, sans-serif" font-size="12" font-weight="600" fill="#FFD700" text-anchor="middle">v3.3.0</text>
+
+  <!-- Tagline -->
+  <text x="188" y="125" font-family="'Segoe UI', system-ui, sans-serif" font-size="16" fill="#7F8C8D" letter-spacing="3">
+    AUTONOMOUS AI AGENTS
+  </text>
+
+  <!-- Bottom accent line -->
+  <rect x="185" y="140" width="120" height="2" rx="1" fill="url(#cyanGrad)" opacity="0.6"/>
+  <rect x="315" y="140" width="40" height="2" rx="1" fill="url(#goldGrad)" opacity="0.4"/>
+
+  <!-- Yonder Zenith -->
+  <text x="188" y="165" font-family="'Segoe UI', system-ui, sans-serif" font-size="11" fill="#7F8C8D" opacity="0.6">
+    by Yonder Zenith LLC
+  </text>
+</svg>