You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`./scripts/launch.sh up dev` is the canonical launcher. The explicit fallback is `docker compose -f docker-compose.unified.yml --profile dev up -d` (`docker-compose.unified.yml` is the only compose file shipped).
74
+
73
75
| Service | URL | Description |
74
76
|:--------|:----|:------------|
75
77
| Frontend |http://localhost:3001| 3D knowledge graph interface (via Nginx) |
76
78
| API |http://localhost:4000/api| REST + WebSocket endpoints (Rust/Actix-web) |
77
79
| Solid Pod |http://localhost:8484| Embedded Solid pod server (solid-pod-rs) |
docker-compose -f docker-compose.yml -f docker-compose.voice.yml --profile dev up -d
84
-
```
82
+
<summary><strong>Voice routing and multi-user XR overlays</strong></summary>
85
83
86
-
Adds LiveKit SFU (port 7880), turbo-whisper STT (CUDA), and Kokoro TTS. Requires GPU for real-time transcription.
87
-
88
-
</details>
89
-
90
-
<details>
91
-
<summary><strong>Enable multi-user XR (Vircadia World Server)</strong></summary>
92
-
93
-
```bash
94
-
docker-compose -f docker-compose.yml -f docker-compose.vircadia.yml --profile dev up -d
95
-
```
96
-
97
-
Adds Vircadia World Server with avatar sync, HRTF spatial audio, and collaborative graph editing.
84
+
The voice (LiveKit + whisper + TTS) and Vircadia World Server overlays are not currently shipped as separate compose files. `docker-compose.unified.yml` is the only compose file in the repository; there are no `docker-compose.voice.yml` or `docker-compose.vircadia.yml` overlays to stack on top of it. Any voice/XR services are configured within the unified compose definition or via the host launcher, not by overlaying additional compose files.
98
85
99
86
</details>
100
87
@@ -246,7 +233,7 @@ flowchart LR
246
233
247
234
### Agent Control Surface Protocol
248
235
249
-
Agents publish structured Nostr events; the relay routes them; the forum renders decision surfaces; humans respond with cryptographically signed events. The governance audit trail is immutable by construction.
236
+
VisionClaw does **not** currently emit governance panels. What ships today is the bead-provenance bridge (`src/services/nostr_bridge.rs`), which republishes kind 30001 bead records as kind 9 Nostr events. The Agent Control Surface Protocol — agents publishing structured panel events that a relay routes, a forum renders as decision surfaces, and humans answer with cryptographically signed responses — is a **planned integration**, not a shipped emitter. The authoritative contract for the panel kinds below lives in [docs/architecture/agent-control-surface-panels.md](docs/architecture/agent-control-surface-panels.md), which states plainly that VisionClaw does not publish panels; emission (kinds 31400/31402 via a future `ServerNostrActor`) is future work.
250
237
251
238
| Kind | Name | Flow |
252
239
|---|---|---|
@@ -257,6 +244,8 @@ Agents publish structured Nostr events; the relay routes them; the forum renders
| 31405 | PanelRetired | Agent → retires a control panel |
259
246
247
+
*(Planned contract — no VisionClaw emitter exists today.)*
248
+
260
249
### Embodied Agent Loop
261
250
262
251
Agent actions are not just audited — they are **visibly embodied** in the GPU/XR graph. When an agent acts (on a Solid pod, the knowledge graph, or the ontology), the action crosses the federation boundary and renders as a living event on the agent's actor node:
The backend uses Actix actors for supervised concurrency. GPU actors form a hierarchy: `GraphServiceSupervisor` → `PhysicsOrchestratorActor` → `ForceComputeActor`. All actors restart automatically on failure.
546
535
@@ -574,7 +563,6 @@ The backend uses Actix actors for supervised concurrency. GPU actors form a hier
@@ -730,13 +718,13 @@ See the [Contributing Guide](docs/CONTRIBUTING.md). Check [Known Issues](docs/KN
730
718
731
719
## License
732
720
733
-
[Mozilla Public License 2.0](LICENSE) — Use commercially, modify freely, share changes to MPL files.
721
+
[GNU Affero General Public License v3.0-only](LICENSE) — see [LICENSE](LICENSE) for the full text. Network use is distribution: if you run a modified version as a network service, you must offer its complete source to its users.
734
722
735
723
---
736
724
737
725
<divalign="center">
738
726
739
-
**VisionClaw is the knowledge engineering substrate of [VisionClaw](https://github.com/DreamLab-AI/VisionClaw), built by [DreamLab AI](https://www.dreamlab-ai.com).**
727
+
**VisionClaw is the knowledge engineering substrate of [VisionFlow](https://github.com/DreamLab-AI/VisionFlow), built by [DreamLab AI](https://www.dreamlab-ai.com).**
`./scripts/launch.sh up dev` is the canonical launcher; the explicit fallback is `docker compose -f docker-compose.unified.yml --profile dev up -d` (`docker-compose.unified.yml` is the only compose file shipped).
24
+
23
25
Open [http://localhost:3001](http://localhost:3001) for the 3D graph interface and [http://localhost:4000/api](http://localhost:4000/api) for the REST API. The graph store is the embedded Oxigraph triple store (ADR-11) — there is no separate database browser UI.
24
26
25
27
Full setup details: [Deployment Guide](how-to/deployment-guide.md)
@@ -40,15 +42,11 @@ See [Sovereign Mesh ADRs](#sovereign-mesh-pod-integration-adr-028-ext-to-adr-052
40
42
41
43
---
42
44
43
-
## Agent Control Surface Protocol Integration (2026-05-12)
44
-
45
-
**Governance bridge between VisionClaw BrokerActor and Forum Kit relay mesh**. Two new server-signed Nostr event kinds:
45
+
## Agent Control Surface Protocol Integration (planned)
46
46
47
-
-**Kind 31400 — PanelDefinition**: `PublishGovernancePanel` registers/updates control panels (ActionInbox, Dashboard, ConfigForm, StatusBoard, ChatBridge) with schema, fields, actions, layout hints. NIP-33 replaceable by `d` tag.
48
-
-**Kind 31402 — ActionRequest**: `PublishActionRequest` submits cases for human review with priority, category, structured fields, and agent reasoning.
49
-
-**Dual-path enterprise RBAC**: `RequireRole` middleware now supports NIP-98 Schnorr auth (`nip98-auth` feature gate) alongside the existing `X-Enterprise-Role` header path. `Nip98RoleResolver` trait maps verified pubkeys to enterprise roles.
47
+
VisionClaw does **not** emit governance panels today. The live Nostr egress is the bead-provenance bridge (`src/services/nostr_bridge.rs`), which republishes kind 30001 bead-provenance records as kind 9 events. There is no `ServerNostrActor` and no 31400/31402 panel emission in the current build.
50
48
51
-
Source: `src/actors/server_nostr_actor.rs`, `src/middleware/enterprise_auth.rs` | Kinds added to `server_identity.rs``SUPPORTED_KINDS`and `metrics.rs``NostrKind` enum.
49
+
The Agent Control Surface Protocol — server-signed panel and action-request events bridging an agent broker to a Forum Kit relay mesh — is a **planned integration**. Its contract is defined in [architecture/agent-control-surface-panels.md](architecture/agent-control-surface-panels.md), the authoritative statement that VisionClaw does not publish panels. When implemented, panel emission (kind 31400 PanelDefinition, kind 31402 ActionRequest) would be carried by a future `ServerNostrActor`; the document specifies the kinds, fields, and RBAC model that emitter must satisfy.
52
50
53
51
---
54
52
@@ -220,7 +218,7 @@ Full reference index: [reference/INDEX.md](reference/INDEX.md)
Copy file name to clipboardExpand all lines: docs/analysis-visionclaw-x-understand-anything.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@
9
9
10
10
**Understand-Anything (UA)** is a Claude Code plugin that statically analyzes codebases (and Karpathy-pattern LLM wikis) to produce interactive knowledge graphs. It uses LLM-augmented analysis, language-specific parsers, and a React/ReactFlow 2D dashboard.
11
11
12
-
**VisionClaw (VC)** is a GPU-accelerated 3D knowledge graph platform that ingests Logseq markdown wikis, stores graph data in Neo4j, runs force-directed physics on CUDA, and renders via Three.js/WebXR in the browser with real-time binary position streaming.
12
+
**VisionClaw (VC)** is a GPU-accelerated 3D knowledge graph platform that ingests Logseq markdown wikis, stores graph data in embedded Oxigraph + SQLite (SPARQL triple store; ADR-11), runs force-directed physics on CUDA, and renders via Three.js/WebXR in the browser with real-time binary position streaming.
13
13
14
14
They solve **adjacent problems at different layers of the stack**: UA excels at *graph construction from source analysis*, VC excels at *GPU-powered real-time graph visualization and Solid-rs pod federation*. The combination would be greater than the sum of parts.
Diagram-driven audit (ruflo mesh: 1 sonnet interface cartographer + 2 opus auditors + 2 opus fixers, Fable queen). Successor to the 2026-05-28 production register (`docs/architecture/diagrams/00-anomaly-register.md` is the older 2026-06-03 settings/GPU register — both retained). Ground-truth map: [interface-sequences.md](interface-sequences.md).
4
+
5
+
```mermaid
6
+
mindmap
7
+
root((visionclaw 06-11))
8
+
2026-05-28 register
9
+
12 FIXED incl S1 SPARQL + D2..D6 docker
10
+
5 PARTIAL S2 S3 G1 CL2 CL3
11
+
2 OPEN C2 G3
12
+
Doc drift
13
+
phantom ACSP emitter — FIXED
14
+
MPL badge on AGPL repo — FIXED
15
+
24B/28B vs 52B wire width — FIXED
16
+
ADR-090 triple collision — RENUMBERED
17
+
New since 05-28
18
+
unauth enrichment decide — FIX IN FLIGHT
19
+
82GB stale agent worktrees
20
+
11 client files >700 lines
21
+
Protocol (open)
22
+
three coexisting binary encoders
23
+
V4 client header server never emits
24
+
```
25
+
26
+
## 2026-05-28 register re-verification (verdicts with evidence)
- S2 — `utils/auth.rs:46` still lets `Authenticated` satisfy `WriteGraph`, but every known mutator surface now carries explicit `RequireAuth::power_user()` route wraps. Tighten `has_permission` to finish.
32
+
- S3 — old literal `/settings` routes are dead (module disabled at `api_handler/mod.rs:135`), but live `/api/settings/*` GETs use `OptionalAuth` then discard it (`settings_routes.rs:1066`) — reads effectively anonymous.
33
+
- G1 — circuit-breaker real and wired (`MAX_CONSECUTIVE_GPU_FAILURES=5` → degraded+halt); CPU fallback remains an intentional warn-stub (GPU mandatory). Fails safe, not over.
- CL3 — reconnect/heartbeat timers balanced; binaryProtocol capped at 65536 entries; no remaining leak found.
36
+
37
+
**STILL-OPEN (2):** C2 settings read-modify-write race (`write_handlers.rs:44→198`, no version guard) — but the whole module is the *disabled* handler path; confirm dead → delete instead of fix. G3 — 3 `#[ignore]` gpu_stability tests on a stale API.
38
+
39
+
**ACCEPTED:** D1 docker.sock mount is `:ro`, dev-profile-only, explicitly commented.
40
+
41
+
## New findings since 2026-05-28
42
+
43
+
| ID | Sev | Where | Finding | Status |
44
+
|----|-----|-------|---------|--------|
45
+
| N1 | HIGH |`enrichment_proposals_handler.rs:178` + `main.rs:936`| Unauthenticated `POST /api/enrichment-proposals/{id}/decide`; `broker_pubkey` self-asserted from body (default "anon"); persists, broadcasts, triggers writeback — Sybil surface on the broker loop (introduced 023c847b0) |**Fix in flight this sweep** (auth gate matching sibling mutator precedent) |
46
+
| N2 | MED |`.claude/worktrees/`| 82 GB / 52 stale `agent-*` worktrees (gitignored). Pollutes grep and disk. | Flagged — operator call before deletion (`git worktree list` then prune + remove stale dirs) |
47
+
| N3 | MED | protocol | Three coexisting binary encoders: 28-byte V3F0 (`v3_frame.rs`, unused on the position path), 52-byte V3-extended (`binary_protocol.rs`, actual wire), 6-byte V4 header (client-send only, `frameTypes.ts:8` — server never emits it). Classic parallel-implementation divergence; consolidate or document authority. | Open |
48
+
| N4 | LOW |`endpoints.ts:85,350`| Client `updatePhysics` does GET-then-PUT; unified `POST /api/settings` has no JS caller; unknown setting paths silently fall back to localStorage-only. | Open |
49
+
| N5 | MED |`optimized_settings_actor.rs:596`| Settings writes don't broadcast to co-present clients (stale until reload). | Open |
50
+
| N6 | LOW |`position_updates.rs:742` vs subscribe path | Drag enforces pubkey check; position-stream subscribe doesn't — unauthenticated clients can receive the stream. Decide: public-viz by design, or gate. | Open |
51
+
| N7 | LOW | client | 11 files >700 lines (GemNodes 934, InstancedLabels 890, OnboardingWizard 794, settings.ts 780, CommandInput 761…) vs the 500-line project rule. | Open |
52
+
| N8 | LOW | code stragglers | Rename debt the docs already match: CUDA loader symbol still `visionflow_unified` (`ptx_loader.rs`), core crate still logs/refers to `webxr` (`visionclaw-protocol lib.rs:16`, RUST_LOG targets). Fix in code, then sweep docs. | Open |
53
+
| N9 | INFO |`solid_proxy_handler.rs:1874`| Without `solid-pod-embed` feature all `/solid/*` → 503; client has no guard. `filter_auth.rs:241` Phase-2 SQLite persistence is a stub. | Open |
54
+
55
+
## Doc drift resolved this sweep
56
+
57
+
README/docs-README phantom ACSP emitter (`ServerNostrActor`, 31400/31402 — never existed; reframed to the bead-provenance bridge reality per `agent-control-surface-panels.md`); MPL 2.0 badge/section → AGPL-3.0-only; 24B/28B wire-width claims → 52-byte `WireNodeDataItemV3` (+ ADR-061 amendment note); 23→21 actors; dead compose-file commands → `./scripts/launch.sh up dev`; Neo4j present-tense claim → Oxigraph+SQLite; GraphManager hooks-layer note; `src/uri/mod.rs` citations; ADR-090 collision → renumbered ADR-103/ADR-104; self-referential footer.
58
+
59
+
**Left for operator decision:** ADR-089 (CQRS-bus removal, Proposed) vs the "114 CQRS handlers" headline — reconcile status once the direct-dispatch reclassification (C1) is accepted. XR-domain docs (Vircadia/WebXR→Godot) untouched — in-flight work.
0 commit comments