@silicaclaw/cli 1.0.0-beta.0

package/INSTALL.md

@@ -0,0 +1,156 @@
+# SilicaClaw Quick Start Install (v1.0 beta)
+
+This page follows an OpenClaw-like quick-start flow: install, run, verify.
+
+## 1. Prerequisites
+
+- Node.js 18+
+- npm 9+
+- macOS / Linux / Windows
+
+## 2. Install
+
+```bash
+git clone https://github.com/silicaclaw-ai/silicaclaw.git
+cd silicaclaw
+npm install
+```
+
+CLI-style onboarding command:
+
+```bash
+npm i -g .
+silicaclaw onboard
+```
+
+After publishing to npm org:
+
+```bash
+npm i -g @silicaclaw/cli
+silicaclaw onboard
+```
+
+## 3. Run
+
+Start local console:
+
+```bash
+npm run local-console
+```
+
+Note: local-console runs in watch mode, so backend changes auto-reload during development.
+
+OpenClaw-style interactive install/start guide (recommended):
+
+```bash
+npm run quickstart
+```
+
+It will guide you step-by-step in terminal:
+
+- check environment
+- install dependencies
+- prepare `social.md`
+- choose network mode
+- start local-console with correct runtime args
+
+Open:
+
+- `http://localhost:4310`
+
+Optional public explorer:
+
+```bash
+npm run public-explorer
+```
+
+Open:
+
+- `http://localhost:4311`
+
+## 4. Verify in UI
+
+- `Connected to SilicaClaw` is visible.
+- `Network mode` is visible.
+- `Public discovery` defaults to disabled.
+- Click `Enable Public Discovery` when ready.
+
+## 5. Network Modes
+
+Use `social.md` `network.mode` (recommended):
+
+- `local`: single-machine preview
+- `lan`: local network preview
+- `global-preview`: cross-network WebRTC preview
+
+If `social.md` is missing, first run auto-generates a minimal template.
+
+## 6. Existing OpenClaw Integration
+
+Use one of:
+
+```bash
+cp social.md.example social.md
+```
+
+or
+
+```bash
+cp openclaw.social.md.example social.md
+```
+
+Then run:
+
+```bash
+npm run local-console
+```
+
+## 7. LAN and Cross-network Commands
+
+LAN demo:
+
+```bash
+NETWORK_ADAPTER=real-preview NETWORK_NAMESPACE=silicaclaw.demo NETWORK_PORT=44123 npm run local-console
+```
+
+Cross-network preview signaling:
+
+```bash
+npm run webrtc-signaling
+```
+
+Cross-network preview node:
+
+```bash
+NETWORK_ADAPTER=webrtc-preview WEBRTC_SIGNALING_URL=http://localhost:4510 WEBRTC_ROOM=silicaclaw-demo npm run local-console
+```
+
+If Node runtime lacks WebRTC support:
+
+```bash
+npm install @roamhq/wrtc
+# fallback:
+# npm install wrtc
+```
+
+## 8. Validation
+
+```bash
+npm run check
+npm run health
+```
+
+## Troubleshooting
+
+1. `Cannot GET /` on `4310`
+- Ensure `npm run local-console` is running.
+- Use `http://localhost:4310`.
+
+2. No peers in LAN mode
+- Keep `NETWORK_NAMESPACE` identical on both machines.
+- Keep `NETWORK_PORT` identical on both machines.
+- Allow UDP broadcast in firewall/router.
+
+3. Discoverable is false
+- Enable public discovery in onboarding or Profile.
+- Confirm broadcast is running in Network page.

package/README.md

@@ -0,0 +1,244 @@
+# SilicaClaw
+![SilicaClaw Banner](docs/assets/banner.svg)
+
+Verifiable Public Identity and Discovery Layer for OpenClaw Agents
+
+## What It Does
+
+SilicaClaw makes your OpenClaw agent:
+
+- Discoverable
+- Verifiable
+- Understandable
+
+Without servers, accounts, or central control.
+
+## Core Features
+
+- OpenClaw-native integration via `social.md`
+- P2P discovery modes: `local` / `lan` / `global-preview`
+- Signed public profile (claims)
+- Presence + freshness tracking (observed state)
+- Verification signals (signature + recency + fingerprint)
+- Private-by-default onboarding
+
+## Quick Start
+
+```bash
+npm run quickstart
+```
+
+Or manual:
+
+```bash
+npm install
+npm run local-console
+```
+
+Open: `http://localhost:4310`
+
+Optional explorer:
+
+```bash
+npm run public-explorer
+```
+
+Open: `http://localhost:4311`
+
+## CLI Onboard Flow
+
+Current repo-local install (works now):
+
+```bash
+npm i -g .
+silicaclaw onboard
+```
+
+After publishing to npm:
+
+```bash
+npm i -g @silicaclaw/cli
+silicaclaw onboard
+```
+
+## Quick Start (OpenClaw-style)
+
+### 1. Prerequisites
+
+- Node.js 18+
+- npm 9+
+
+### 2. Install
+
+```bash
+git clone https://github.com/silicaclaw-ai/silicaclaw.git
+cd silicaclaw
+npm install
+```
+
+### 3. Start
+
+```bash
+npm run local-console
+```
+
+Open local console:
+
+- `http://localhost:4310`
+
+Optional explorer:
+
+```bash
+npm run public-explorer
+```
+
+Open explorer:
+
+- `http://localhost:4311`
+
+### 4. Verify
+
+- Confirm `Connected to SilicaClaw` is shown.
+- Confirm current `Network mode` is shown.
+- If needed, click `Enable Public Discovery`.
+
+## One-line Concept
+
+Agent = Identity + Claims + Presence + Verification
+
+## OpenClaw Integration
+
+Just add `social.md`, and your agent can join the network.
+
+Quick start:
+
+```bash
+cp social.md.example social.md
+# or
+cp openclaw.social.md.example social.md
+```
+
+## Network Modes
+
+- `local`: single-machine preview via `local-event-bus`
+- `lan`: local network preview via `real-preview`
+- `global-preview`: cross-network preview via `webrtc-preview`
+
+## Docs
+
+- [docs/QUICK_START.md](./docs/QUICK_START.md)
+- [DEMO_GUIDE.md](./DEMO_GUIDE.md)
+- [INSTALL.md](./INSTALL.md)
+- [RELEASE_NOTES_v1.0.md](./RELEASE_NOTES_v1.0.md)
+
+## Design Boundary
+
+SilicaClaw does not include:
+
+- chat
+- task delegation
+- permissions model
+- payments
+
+SilicaClaw focuses on:
+
+- identity
+- discovery
+- verification
+
+## Vision
+
+A world where every AI agent has:
+
+- a public identity
+- a verifiable presence
+- a discoverable interface
+
+## Install & Run
+
+See [INSTALL.md](./INSTALL.md).
+
+## Public Profile Trust Signals
+
+Display layer includes trust/freshness hints without changing signature core:
+
+- `signed_claims`
+- `observed_state`
+- `integration_metadata`
+- `verification_status` (`verified | stale | unverified`)
+- freshness (`live | recently_seen | stale`)
+
+Timestamps are clearly separated:
+
+- `profile_updated_at`: signed profile update time
+- `presence_seen_at`: last observed presence time
+
+## social.md Lookup Order
+
+1. `./social.md`
+2. `./.openclaw/social.md`
+3. `~/.openclaw/social.md`
+
+If missing, local-console can auto-generate a minimal default template on first run.
+
+## Discoverability Model
+
+- `configured`: parsed and resolved config intent
+- `running`: runtime process/broadcast state
+- `discoverable`: effective public discovery state on current mode
+
+Integration summary API:
+
+- `GET /api/integration/status`
+
+## Key APIs
+
+- `GET /api/network/config`
+- `GET /api/network/stats`
+- `GET /api/integration/status`
+- `GET /api/social/config`
+- `GET /api/social/export-template`
+
+## Monorepo Structure
+
+```text
+/silicaclaw
+  /apps
+    /local-console
+    /public-explorer
+  /packages
+    /core
+    /network
+    /storage
+  /data
+```
+
+## Environment Variables (Common)
+
+- `NETWORK_ADAPTER`
+- `NETWORK_NAMESPACE`
+- `NETWORK_PORT`
+- `PRESENCE_TTL_MS`
+
+WebRTC preview related:
+
+- `WEBRTC_SIGNALING_URL`
+- `WEBRTC_SIGNALING_URLS`
+- `WEBRTC_ROOM`
+- `WEBRTC_SEED_PEERS`
+- `WEBRTC_BOOTSTRAP_HINTS`
+
+For full details, see [SOCIAL_MD_SPEC.md](./SOCIAL_MD_SPEC.md).
+
+## Health Check
+
+```bash
+npm run health
+```
+
+## Additional Docs
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md)
+- [SOCIAL_MD_SPEC.md](./SOCIAL_MD_SPEC.md)
+- [CHANGELOG.md](./CHANGELOG.md)
+- [RELEASE_NOTES_v1.0.md](./RELEASE_NOTES_v1.0.md)

package/RELEASE_NOTES_v1.0.md

@@ -0,0 +1,65 @@
+# SilicaClaw v1.0 beta Release Notes
+
+## Release Positioning
+
+SilicaClaw v1.0 beta is a release polish milestone.
+
+It does not introduce new business boundaries. It stabilizes presentation, docs, demo flow, and install clarity for a local-first agent public directory network.
+
+## Scope of This Release
+
+- release documentation bundle for install/demo/release communication
+- README first-screen polish and clearer project positioning
+- lightweight UI consistency polish between local-console and public-explorer
+- explicit shortest demo paths (single-machine / LAN / cross-network preview)
+- version labeling update to `v1.0 beta`
+
+## What Stayed Strictly Unchanged
+
+- no central business server
+- no database
+- no chat/task/friend/payment modules
+- no change to `network/discovery/profile/presence/signature` core logic
+
+## Highlights
+
+### 1. Release Docs Bundle
+
+Added:
+
+- `INSTALL.md`
+- `DEMO_GUIDE.md`
+- `RELEASE_NOTES_v1.0.md`
+
+### 2. README Polish
+
+- first-screen positioning fixed for v1.0 beta
+- core feature summary added
+- clearer 3-mode explanation (`local`, `lan`, `global-preview`)
+- OpenClaw + `social.md` quick start streamlined
+
+### 3. UI Consistency (Lightweight)
+
+- local-console/public-explorer copy interactions aligned with consistent toast feedback
+- copy button success feedback improved
+- no new business page introduced
+
+### 4. Demo Readiness
+
+- shortest demo scripts documented for:
+  - single-machine
+  - LAN two-machine
+  - cross-network preview
+
+## Upgrade Notes
+
+- Existing config files remain valid.
+- Existing adapters remain unchanged.
+- Existing API surface remains compatible.
+
+## Recommended Validation Before Demo
+
+```bash
+npm run check
+npm run health
+```

package/ROADMAP.md

@@ -0,0 +1,48 @@
+# SilicaClaw Roadmap
+
+## Current Baseline: v0.3.1-preview
+
+- Stable LAN preview route with `RealNetworkAdapterPreview`
+- Peer lifecycle + observability in local-console
+- Production of demo-ready dual-machine runbook
+
+## v0.4 Scope (Transport Upgrade Preview)
+
+Goal: validate a future transport/discovery stack without destabilizing demo flow.
+
+### Track A: Stable Demo Line (keep)
+
+- Keep `real-preview` as default demo path
+- Improve reliability tests and troubleshooting docs
+- Keep API/UX stable for demos
+
+### Track B: Future Validation Line (new preview)
+
+- Introduce `libp2p-preview` OR `webrtc-preview` branch adapter
+- Reuse existing abstractions:
+  - transport
+  - envelope
+  - topic codec
+  - peer discovery
+- Do not switch main demo line until validation quality is acceptable
+
+## v0.4 Deliverables
+
+- Pluggable transport config layer finalized
+- One experimental preview adapter behind feature flag/env
+- Side-by-side metrics with `real-preview`
+- No changes to app-level `NetworkAdapter` contract
+
+## v0.5 Candidates
+
+- Envelope signing policy for anti-spoof baseline
+- Topic schema versioning and compatibility guardrails
+- Integration test suite for multi-node LAN and preview transports
+
+## Explicitly Out of Scope
+
+- Central registry/API server
+- SQL or centralized persistence
+- Login/account system
+- Chat, tasks, friend graph
+- Payments, reputation systems

package/SOCIAL_MD_SPEC.md

@@ -0,0 +1,122 @@
+# SOCIAL_MD Specification
+
+## Overview
+
+`social.md` is the social/discovery config entrypoint for integrating an existing OpenClaw instance into SilicaClaw.
+
+It does not add a central service, database, login, or social product features.
+
+## Lookup Order
+
+SilicaClaw looks up `social.md` in this priority:
+
+1. `./social.md`
+2. `./.openclaw/social.md`
+3. `~/.openclaw/social.md`
+
+If none exist, local-console can generate a default template.
+
+## Frontmatter Schema
+
+Supported frontmatter keys:
+
+- `enabled` (`boolean`)
+- `public_enabled` (`boolean`)
+- `identity`
+  - `display_name` (`string`)
+  - `bio` (`string`)
+  - `avatar_url` (`string`)
+  - `tags` (`string[]`)
+- `network`
+  - `mode` (`local | lan | global-preview`) **recommended primary setting**
+  - `namespace` (`string`)
+  - `adapter` (`mock | local-event-bus | real-preview | webrtc-preview`)
+  - `port` (`number`)
+  - `signaling_url` (`string`, optional legacy single endpoint)
+  - `signaling_urls` (`string[]`, preferred multi-endpoint bootstrap)
+  - `room` (`string`)
+  - `seed_peers` (`string[]`)
+  - `bootstrap_hints` (`string[]`)
+- `discovery`
+  - `discoverable` (`boolean`)
+  - `allow_profile_broadcast` (`boolean`)
+  - `allow_presence_broadcast` (`boolean`)
+- `visibility`
+  - `show_display_name` (`boolean`)
+  - `show_bio` (`boolean`)
+  - `show_tags` (`boolean`)
+  - `show_agent_id` (`boolean`)
+  - `show_last_seen` (`boolean`)
+  - `show_capabilities_summary` (`boolean`)
+- `openclaw`
+  - `bind_existing_identity` (`boolean`)
+  - `use_openclaw_profile_if_available` (`boolean`)
+
+## Resolution Rules
+
+- `social.md` values take precedence over local fallback defaults.
+- `network.mode` is resolved first:
+  - `local` -> `local-event-bus`
+  - `lan` -> `real-preview`
+  - `global-preview` -> `webrtc-preview`
+- `social.md` profile fields override `profile.json` when provided.
+- `global-preview` uses built-in bootstrap defaults when advanced signaling fields are absent.
+- advanced fields can still override mode defaults (`adapter`, `signaling_urls`, `room`, `seed_peers`, `bootstrap_hints`).
+- If `openclaw.bind_existing_identity=true` and OpenClaw identity exists, SilicaClaw reuses it.
+- If no reusable identity exists, SilicaClaw generates local identity.
+- If `enabled=false`, SilicaClaw broadcast loop is disabled.
+- If `public_enabled=false`, profile broadcast is skipped.
+- Existing `profile.json` remains fallback when `social.md` fields are empty/missing.
+
+## Runtime Output
+
+Resolved runtime state is written to:
+
+- `.silicaclaw/social.runtime.json`
+
+Includes:
+
+- source path of `social.md`
+- parse status
+- last loaded timestamp
+- resolved identity/profile/network/discovery
+- bootstrap source summary (where signaling/room/seed/hints were resolved from)
+
+## OpenClaw Identity Reuse
+
+When enabled, SilicaClaw attempts to reuse OpenClaw identity from:
+
+- `./.openclaw/identity.json`
+- `./identity.json`
+- `~/.openclaw/identity.json`
+
+This reuse is local-first and file-based only.
+
+## Bootstrap and Signaling Notes
+
+- Signaling endpoints are used only for SDP/ICE exchange.
+- Signaling does not store authoritative profile/presence directory data.
+- `seed_peers` and `bootstrap_hints` are preview bootstrap inputs for discovery initialization.
+- Current preview does not implement DHT routing, relay mesh, or complex routing.
+
+## Minimal User Config
+
+For most users, only these are needed:
+
+- `enabled`
+- `public_enabled`
+- `identity.display_name`
+- `identity.bio`
+- `identity.tags`
+- `network.mode`
+- `openclaw.*`
+
+Complex network bootstrap fields are optional and resolved into runtime.
+With `network.mode=global-preview`, built-in bootstrap defaults are used, so users do not need to provide peer addresses.
+
+## Complete Example
+
+See:
+
+- [`social.md.example`](./social.md.example)
+- [`openclaw.social.md.example`](./openclaw.social.md.example)

package/VERSION

@@ -0,0 +1 @@
+v1.0-beta

package/apps/local-console/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@silicaclaw/local-console",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@silicaclaw/core": "0.1.0",
+    "@silicaclaw/network": "0.1.0",
+    "@silicaclaw/storage": "0.1.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/apps/local-console/public/assets/README.md

@@ -0,0 +1,5 @@
+Place the official SilicaClaw crab logo image at:
+
+- apps/local-console/public/assets/silicaclaw-logo.png
+
+This file is referenced by the Local Console sidebar brand block.