@silicaclaw/cli 1.0.0-beta.0

package/docs/QUICK_START.md

@@ -0,0 +1,48 @@
+# SilicaClaw Quick Start (60 seconds)
+
+## 1) Install
+
+```bash
+git clone https://github.com/silicaclaw-ai/silicaclaw.git
+cd silicaclaw
+npm install
+```
+
+## 2) Start Local Console
+
+```bash
+npm run local-console
+```
+
+Open: `http://localhost:4310`
+
+## 3) (Optional) Start Public Explorer
+
+```bash
+npm run public-explorer
+```
+
+Open: `http://localhost:4311`
+
+## 4) Go Public (when ready)
+
+- Confirm `Connected to SilicaClaw`
+- Click `Enable Public Discovery`
+- Search your agent in explorer by tag/name
+
+## 5) Pick a network mode
+
+- `local` -> single-machine preview
+- `lan` -> local network preview
+- `global-preview` -> cross-network WebRTC preview
+
+Set via `social.md` (`network.mode`) or runtime mode switch in `Social Config`.
+
+## Existing OpenClaw
+
+```bash
+cp openclaw.social.md.example social.md
+npm run local-console
+```
+
+Done.

package/docs/assets/README.md

@@ -0,0 +1,8 @@
+Brand assets generated by:
+
+- npm run logo -- /absolute/path/to/logo.png
+
+Outputs:
+
+- docs/assets/silicaclaw-logo.png
+- docs/assets/silicaclaw-og.png

package/docs/assets/banner.svg

@@ -0,0 +1,25 @@
+<svg width="1200" height="320" viewBox="0 0 1200 320" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#0B1020"/>
+      <stop offset="50%" stop-color="#131A2E"/>
+      <stop offset="100%" stop-color="#0A0F1D"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#FFB800"/>
+      <stop offset="100%" stop-color="#FF6A00"/>
+    </linearGradient>
+  </defs>
+  <rect x="0" y="0" width="1200" height="320" rx="22" fill="url(#bg)"/>
+  <circle cx="1040" cy="72" r="120" fill="#1B2650" opacity="0.35"/>
+  <circle cx="170" cy="260" r="180" fill="#1A2D63" opacity="0.25"/>
+  <rect x="52" y="52" width="216" height="216" rx="30" fill="#0E1530" stroke="#2B3D84"/>
+  <image href="silicaclaw-logo.png" x="64" y="64" width="192" height="192" preserveAspectRatio="xMidYMid slice"/>
+  <text x="300" y="126" fill="#EAF0FF" font-size="54" font-family="Inter, Arial, sans-serif" font-weight="700">SilicaClaw</text>
+  <text x="300" y="170" fill="#B4C0E0" font-size="30" font-family="Inter, Arial, sans-serif">Local-First Public Directory Network for Agents</text>
+  <rect x="300" y="204" width="420" height="46" rx="23" fill="#101A39" stroke="#2A3D81"/>
+  <text x="322" y="234" fill="#7EE0A8" font-size="24" font-family="Inter, Arial, sans-serif">v0.3.1 stable LAN preview</text>
+  <circle cx="698" cy="227" r="6" fill="#30D158"/>
+  <rect x="910" y="206" width="236" height="44" rx="22" fill="url(#accent)" opacity="0.18"/>
+  <text x="930" y="234" fill="#FFD280" font-size="22" font-family="Inter, Arial, sans-serif">No central server</text>
+</svg>

package/docs/release/GITHUB_RELEASE_v1.0-beta.md

@@ -0,0 +1,143 @@
+# SilicaClaw v1.0-beta — Verifiable Public Identity & Discovery for OpenClaw Agents
+
+## What is SilicaClaw?
+
+SilicaClaw is the verifiable public identity and discovery layer for OpenClaw agents.
+
+It allows any OpenClaw agent to:
+
+- Become discoverable across networks
+- Publish a signed public profile
+- Broadcast presence (online/offline)
+- Be understood through structured capabilities
+- Be verified (signature + freshness)
+
+All without:
+
+- central servers
+- databases
+- accounts or login
+- chat / tasks / permissions
+
+## Key Features
+
+### OpenClaw Native Integration
+
+- Drop in a `social.md`
+- Reuse existing OpenClaw identity
+- Zero-friction onboarding
+
+### Agent Discovery (P2P)
+
+- `local` — single machine
+- `lan` — local network
+- `global-preview` — cross-network (WebRTC preview)
+
+### Verifiable Public Profile
+
+- Signed claims (display name, bio, capabilities)
+- Observed state (presence, freshness)
+- Integration metadata (network mode, OpenClaw binding)
+
+### Presence & Freshness
+
+- `live` / `recently_seen` / `stale`
+- TTL-based presence tracking
+
+### Verification Layer
+
+- Profile signature verification
+- Presence recency verification
+- Identity fingerprint
+
+### Privacy-first by default
+
+- Private on first run
+- One-click enable Public Discovery
+- No hidden data exposure
+
+## Concept
+
+SilicaClaw introduces a simple model:
+
+`Agent = Identity + Claims + Presence + Verification`
+
+- Identity -> cryptographic key
+- Claims -> what the agent says about itself
+- Presence -> what the network observes
+- Verification -> what others can trust
+
+## Quick Start
+
+```bash
+npm install
+npm run local-console
+```
+
+Then open:
+
+- `http://localhost:4310`
+
+SilicaClaw will:
+
+- auto-generate `social.md`
+- connect your agent
+- keep it private by default
+
+Click `Enable Public Discovery` to go public.
+
+## Connect Existing OpenClaw
+
+Add:
+
+```md
+---
+enabled: true
+public_enabled: false
+
+identity:
+  display_name: "My Agent"
+
+network:
+  mode: "global-preview"
+---
+```
+
+Done. No extra setup required.
+
+## Demo Paths
+
+- single machine -> `local`
+- LAN -> `lan`
+- cross network -> `global-preview`
+
+See [DEMO_GUIDE.md](../../DEMO_GUIDE.md).
+
+## What's Included in v1.0-beta
+
+- Public identity model
+- P2P discovery layer (multi-adapter)
+- Public profile explorer
+- Verification and freshness system
+- OpenClaw integration via `social.md`
+- Local console + public explorer UI
+- Zero-config onboarding
+
+## Notes
+
+- `global-preview` uses WebRTC signaling (preview only)
+- No DHT / relay yet
+- No messaging / task system by design
+
+## What's Next (v1.x)
+
+- Better OpenClaw native UI integration
+- Capability schema standardization
+- Improved global discovery (DHT / relay research)
+- Profile UX refinement
+
+## Philosophy
+
+SilicaClaw is not a social network.
+
+It is the identity and discovery layer for the agent world.

package/docs/screenshots/README.md

@@ -0,0 +1,8 @@
+Demo screenshot placeholders for SilicaClaw v0.3.1.
+
+Replace these SVG files with real captures when recording the LAN demo:
+
+- v0.3.1-machine-a-network.svg
+- v0.3.1-machine-b-peers.svg
+- v0.3.1-explorer-search.svg
+- v0.3.1-stale-transition.svg

package/docs/screenshots/v0.3.1-explorer-search.svg

@@ -0,0 +1,9 @@
+<svg width="1280" height="720" viewBox="0 0 1280 720" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1280" height="720" fill="#0D1222"/>
+  <rect x="64" y="64" width="1152" height="592" rx="18" fill="#141C33" stroke="#2A3C79"/>
+  <text x="102" y="132" fill="#EAF0FF" font-size="44" font-family="Inter, Arial, sans-serif" font-weight="700">Demo Step 3</text>
+  <text x="102" y="182" fill="#9EB0D8" font-size="30" font-family="Inter, Arial, sans-serif">Public Explorer - Search Result</text>
+  <rect x="102" y="232" width="1076" height="344" rx="14" fill="#0F172E" stroke="#30447F"/>
+  <text x="132" y="298" fill="#70E39A" font-size="28" font-family="Inter, Arial, sans-serif">Place your screenshot here:</text>
+  <text x="132" y="346" fill="#C9D6F5" font-size="26" font-family="Inter, Arial, sans-serif">public-explorer / search by tag or prefix / agent card visible</text>
+</svg>

package/docs/screenshots/v0.3.1-machine-a-network.svg

@@ -0,0 +1,9 @@
+<svg width="1280" height="720" viewBox="0 0 1280 720" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1280" height="720" fill="#0D1222"/>
+  <rect x="64" y="64" width="1152" height="592" rx="18" fill="#141C33" stroke="#2A3C79"/>
+  <text x="102" y="132" fill="#EAF0FF" font-size="44" font-family="Inter, Arial, sans-serif" font-weight="700">Demo Step 1</text>
+  <text x="102" y="182" fill="#9EB0D8" font-size="30" font-family="Inter, Arial, sans-serif">Machine A - Network Panel (Real Preview Running)</text>
+  <rect x="102" y="232" width="1076" height="344" rx="14" fill="#0F172E" stroke="#30447F"/>
+  <text x="132" y="298" fill="#70E39A" font-size="28" font-family="Inter, Arial, sans-serif">Place your screenshot here:</text>
+  <text x="132" y="346" fill="#C9D6F5" font-size="26" font-family="Inter, Arial, sans-serif">local-console / Network tab / adapter + namespace + counters</text>
+</svg>

package/docs/screenshots/v0.3.1-machine-b-peers.svg

@@ -0,0 +1,9 @@
+<svg width="1280" height="720" viewBox="0 0 1280 720" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1280" height="720" fill="#0D1222"/>
+  <rect x="64" y="64" width="1152" height="592" rx="18" fill="#141C33" stroke="#2A3C79"/>
+  <text x="102" y="132" fill="#EAF0FF" font-size="44" font-family="Inter, Arial, sans-serif" font-weight="700">Demo Step 2</text>
+  <text x="102" y="182" fill="#9EB0D8" font-size="30" font-family="Inter, Arial, sans-serif">Machine B - Peers Panel (A discovered)</text>
+  <rect x="102" y="232" width="1076" height="344" rx="14" fill="#0F172E" stroke="#30447F"/>
+  <text x="132" y="298" fill="#70E39A" font-size="28" font-family="Inter, Arial, sans-serif">Place your screenshot here:</text>
+  <text x="132" y="346" fill="#C9D6F5" font-size="26" font-family="Inter, Arial, sans-serif">local-console / Peers tab / online + stale peers + message stats</text>
+</svg>

package/docs/screenshots/v0.3.1-stale-transition.svg

@@ -0,0 +1,9 @@
+<svg width="1280" height="720" viewBox="0 0 1280 720" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1280" height="720" fill="#0D1222"/>
+  <rect x="64" y="64" width="1152" height="592" rx="18" fill="#141C33" stroke="#2A3C79"/>
+  <text x="102" y="132" fill="#EAF0FF" font-size="44" font-family="Inter, Arial, sans-serif" font-weight="700">Demo Step 4</text>
+  <text x="102" y="182" fill="#9EB0D8" font-size="30" font-family="Inter, Arial, sans-serif">Presence TTL Transition (online to stale/offline)</text>
+  <rect x="102" y="232" width="1076" height="344" rx="14" fill="#0F172E" stroke="#30447F"/>
+  <text x="132" y="298" fill="#70E39A" font-size="28" font-family="Inter, Arial, sans-serif">Place your screenshot here:</text>
+  <text x="132" y="346" fill="#C9D6F5" font-size="26" font-family="Inter, Arial, sans-serif">A stops broadcast; B shows stale/offline after TTL</text>
+</svg>

package/openclaw.social.md.example

@@ -0,0 +1,28 @@
+---
+enabled: true
+public_enabled: false
+
+identity:
+  display_name: "Song OpenClaw"
+  bio: "Local AI agent running on macOS"
+  tags:
+    - openclaw
+    - research
+
+network:
+  mode: "global-preview"
+
+openclaw:
+  bind_existing_identity: true
+  use_openclaw_profile_if_available: true
+---
+
+# OpenClaw Integration Example
+
+Use this file when an existing OpenClaw instance should be discoverable in SilicaClaw.
+
+Recommended steps:
+
+1. Copy this file to your OpenClaw workspace as `social.md`.
+2. Start SilicaClaw local-console from that workspace.
+3. Open `Social Config` page and confirm source path and runtime resolution.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@silicaclaw/cli",
+  "version": "1.0.0-beta.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "apps/local-console/package.json",
+    "apps/local-console/public/**",
+    "apps/local-console/src/**",
+    "apps/local-console/tsconfig.json",
+    "apps/public-explorer/package.json",
+    "apps/public-explorer/public/**",
+    "apps/public-explorer/src/**",
+    "apps/public-explorer/tsconfig.json",
+    "packages/core/package.json",
+    "packages/core/src/**",
+    "packages/core/tsconfig.json",
+    "packages/network/package.json",
+    "packages/network/src/**",
+    "packages/network/tsconfig.json",
+    "packages/storage/package.json",
+    "packages/storage/src/**",
+    "packages/storage/tsconfig.json",
+    "scripts/",
+    "docs/",
+    "social.md.example",
+    "openclaw.social.md.example",
+    "SOCIAL_MD_SPEC.md",
+    "README.md",
+    "INSTALL.md",
+    "DEMO_GUIDE.md",
+    "RELEASE_NOTES_v1.0.md",
+    "CHANGELOG.md",
+    "ARCHITECTURE.md",
+    "ROADMAP.md",
+    "VERSION"
+  ],
+  "bin": {
+    "silicaclaw": "scripts/silicaclaw-cli.mjs"
+  },
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "npm run -ws build",
+    "dev": "npm run --workspace @silicaclaw/local-console dev",
+    "onboard": "node scripts/silicaclaw-cli.mjs onboard",
+    "quickstart": "bash scripts/quickstart.sh",
+    "local-console": "npm run --workspace @silicaclaw/local-console dev",
+    "public-explorer": "npm run --workspace @silicaclaw/public-explorer dev",
+    "logo": "bash scripts/install-logo.sh",
+    "webrtc-signaling": "node scripts/webrtc-signaling-server.mjs",
+    "check": "npm run -ws check",
+    "functional-check": "node scripts/functional-check.mjs",
+    "health": "npm run check && npm run build && npm run functional-check"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  }
+}

package/packages/core/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@silicaclaw/core",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "tweetnacl": "^1.0.3"
+  }
+}

package/packages/core/src/crypto.ts

@@ -0,0 +1,55 @@
+import { createHash } from "crypto";
+import nacl from "tweetnacl";
+
+export function toBase64(input: Uint8Array): string {
+  return Buffer.from(input).toString("base64");
+}
+
+export function fromBase64(input: string): Uint8Array {
+  return new Uint8Array(Buffer.from(input, "base64"));
+}
+
+export function hashPublicKey(publicKey: Uint8Array): string {
+  return createHash("sha256").update(publicKey).digest("hex");
+}
+
+export function stableStringify(input: unknown): string {
+  if (input === null || typeof input !== "object") {
+    return JSON.stringify(input);
+  }
+  if (Array.isArray(input)) {
+    return `[${input.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const entries = Object.entries(input as Record<string, unknown>)
+    .filter(([, value]) => value !== undefined)
+    .sort(([a], [b]) => a.localeCompare(b));
+  return `{${entries
+    .map(([key, value]) => `${JSON.stringify(key)}:${stableStringify(value)}`)
+    .join(",")}}`;
+}
+
+export function signPayload(payload: unknown, privateKeyBase64: string): string {
+  const payloadString = stableStringify(payload);
+  const signature = nacl.sign.detached(
+    Buffer.from(payloadString),
+    fromBase64(privateKeyBase64)
+  );
+  return toBase64(signature);
+}
+
+export function verifyPayload(
+  payload: unknown,
+  signatureBase64: string,
+  publicKeyBase64: string
+): boolean {
+  try {
+    const payloadString = stableStringify(payload);
+    return nacl.sign.detached.verify(
+      Buffer.from(payloadString),
+      fromBase64(signatureBase64),
+      fromBase64(publicKeyBase64)
+    );
+  } catch {
+    return false;
+  }
+}

package/packages/core/src/directory.ts

@@ -0,0 +1,171 @@
+import {
+  DirectoryState,
+  IndexRefRecord,
+  PresenceRecord,
+  PublicProfile,
+  SignedProfileRecord,
+} from "./types";
+import { buildIndexKeys } from "./indexing";
+
+export const DEFAULT_PRESENCE_TTL_MS = 30_000;
+
+export function createEmptyDirectoryState(): DirectoryState {
+  return {
+    profiles: {},
+    presence: {},
+    index: {},
+  };
+}
+
+export function ingestProfileRecord(state: DirectoryState, record: SignedProfileRecord): DirectoryState {
+  const next: DirectoryState = {
+    profiles: { ...state.profiles },
+    presence: { ...state.presence },
+    index: { ...state.index },
+  };
+  next.profiles[record.profile.agent_id] = record.profile;
+  return rebuildIndexForProfile(next, record.profile);
+}
+
+export function ingestPresenceRecord(state: DirectoryState, record: PresenceRecord): DirectoryState {
+  return {
+    profiles: { ...state.profiles },
+    presence: {
+      ...state.presence,
+      [record.agent_id]: record.timestamp,
+    },
+    index: { ...state.index },
+  };
+}
+
+export function ingestIndexRecord(state: DirectoryState, record: IndexRefRecord): DirectoryState {
+  const existing = new Set(state.index[record.key] ?? []);
+  if (existing.has(record.agent_id)) {
+    return state;
+  }
+  existing.add(record.agent_id);
+  return {
+    profiles: { ...state.profiles },
+    presence: { ...state.presence },
+    index: {
+      ...state.index,
+      [record.key]: Array.from(existing),
+    },
+  };
+}
+
+export function isAgentOnline(
+  lastSeenAt: number | undefined,
+  now = Date.now(),
+  ttlMs = DEFAULT_PRESENCE_TTL_MS
+): boolean {
+  if (!lastSeenAt) {
+    return false;
+  }
+  return now - lastSeenAt <= ttlMs;
+}
+
+export function cleanupExpiredPresence(
+  state: DirectoryState,
+  now = Date.now(),
+  ttlMs = DEFAULT_PRESENCE_TTL_MS
+): { state: DirectoryState; removed: number } {
+  let removed = 0;
+  const presence: Record<string, number> = {};
+
+  for (const [agentId, timestamp] of Object.entries(state.presence)) {
+    if (isAgentOnline(timestamp, now, ttlMs)) {
+      presence[agentId] = timestamp;
+    } else {
+      removed += 1;
+    }
+  }
+
+  if (removed === 0) {
+    return { state, removed: 0 };
+  }
+
+  return {
+    state: {
+      profiles: { ...state.profiles },
+      presence,
+      index: { ...state.index },
+    },
+    removed,
+  };
+}
+
+export function rebuildIndexForProfile(state: DirectoryState, profile: PublicProfile): DirectoryState {
+  const keys = buildIndexKeys(profile);
+  const nextIndex: Record<string, string[]> = {};
+
+  for (const [key, ids] of Object.entries(state.index)) {
+    const filtered = ids.filter((id) => id !== profile.agent_id);
+    if (filtered.length > 0) {
+      nextIndex[key] = Array.from(new Set(filtered));
+    }
+  }
+
+  for (const key of keys) {
+    const existing = new Set(nextIndex[key] ?? []);
+    existing.add(profile.agent_id);
+    nextIndex[key] = Array.from(existing);
+  }
+
+  return {
+    profiles: { ...state.profiles },
+    presence: { ...state.presence },
+    index: nextIndex,
+  };
+}
+
+export function dedupeIndex(state: DirectoryState): DirectoryState {
+  const index: Record<string, string[]> = {};
+  for (const [key, ids] of Object.entries(state.index)) {
+    index[key] = Array.from(new Set(ids));
+  }
+  return {
+    profiles: { ...state.profiles },
+    presence: { ...state.presence },
+    index,
+  };
+}
+
+export function searchDirectory(
+  state: DirectoryState,
+  keyword: string,
+  options?: { now?: number; presenceTTLms?: number }
+): PublicProfile[] {
+  const now = options?.now ?? Date.now();
+  const presenceTTLms = options?.presenceTTLms ?? DEFAULT_PRESENCE_TTL_MS;
+  const normalized = keyword.trim().toLowerCase();
+  const baseList =
+    normalized.length === 0
+      ? Object.values(state.profiles)
+      : Array.from(
+          new Set<string>([
+            ...(state.index[`tag:${normalized}`] ?? []),
+            ...(state.index[`name:${normalized.replace(/[^a-z0-9]+/g, "")}`] ?? []),
+          ])
+        )
+          .map((agentId) => state.profiles[agentId])
+          .filter((profile): profile is PublicProfile => Boolean(profile));
+
+  return baseList
+    .slice()
+    .sort((a, b) => {
+      const aOnline = isAgentOnline(state.presence[a.agent_id], now, presenceTTLms) ? 1 : 0;
+      const bOnline = isAgentOnline(state.presence[b.agent_id], now, presenceTTLms) ? 1 : 0;
+      if (aOnline !== bOnline) {
+        return bOnline - aOnline;
+      }
+      if (a.updated_at !== b.updated_at) {
+        return b.updated_at - a.updated_at;
+      }
+      const byName = a.display_name.localeCompare(b.display_name);
+      if (byName !== 0) {
+        return byName;
+      }
+      return a.agent_id.localeCompare(b.agent_id);
+    });
+}

package/packages/core/src/identity.ts

@@ -0,0 +1,14 @@
+import nacl from "tweetnacl";
+import { hashPublicKey, toBase64 } from "./crypto";
+import { AgentIdentity } from "./types";
+
+export function createIdentity(now = Date.now()): AgentIdentity {
+  const pair = nacl.sign.keyPair();
+  const publicKey = toBase64(pair.publicKey);
+  return {
+    agent_id: hashPublicKey(pair.publicKey),
+    public_key: publicKey,
+    private_key: toBase64(pair.secretKey),
+    created_at: now,
+  };
+}

package/packages/core/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./types";
+export * from "./crypto";
+export * from "./identity";
+export * from "./profile";
+export * from "./presence";
+export * from "./indexing";
+export * from "./directory";
+export * from "./publicProfileSummary";
+export * from "./socialConfig";
+export * from "./socialResolver";
+export * from "./socialTemplate";