Oracle Wave 3: UI v3 concat bundle + c3 oracle serve + docs refresh (v2.49.0) (#28)

* feat(oracle): UI v3 — split the 4,181-line oracle.html monolith into a concat bundle

oracle.html was the pre-refactor hub.html pattern: one file, ~780 lines of
CSS + ~400 lines of markup + a 2,967-line inline script. Following the hub
v2 concat architecture: new oracle_ui.html shell (CSS + markup +
__C3_ORACLE_SCRIPTS__ token) + 18 oracle/ui/ modules split at section
banners (core, busy, theme_tabs, crossgraph, header, projects, insights,
activity, suggestions, settings, agents, chat/{markdown,conversations,
stream_renderer,toolbar,input,send}, app.js LAST — the init IIFE).
_ORACLE_JS_FILES + _build_oracle_html() concatenate server-side with
per-file markers; / serves the cached bundle, /legacy serves the frozen
monolith for one release (both issue the dashboard session cookie).

Extraction is VERBATIM: a splitter script cut exact line ranges with a
tiling assertion (no gaps/overlaps), and a multiset diff proved the bundle
differs from the original script by only the intentional ORACLE_BUILD_TIME
bump. Whole-bundle esbuild parse clean. Deliberate deviation from the Wave-3
plan: no React/babel runtime — the logic is 100%% vanilla imperative and the
transferable hub pattern is the file structure + build pipeline, not the
framework; wrapping unowned vanilla code in React would add a CDN/transpile
failure surface for zero owned UI.

Also: pyproject package-data globs for oracle/ui + oracle/ui/chat (the '*'
top-level-only gotcha), and a new 'c3 oracle serve|start' subcommand (lazy
import, mirrors cmd_hub) so the server no longer requires the python entry
point. New tests/test_oracle_ui_bundle.py; wheel inspection confirms all 18
modules + shell + legacy ship.

* docs(oracle): oracle-guide caught up a full product generation; CHANGELOG v2.49.0

The guide documented the original memory/insight Oracle but none of what it
became: architecture.md gains Chat subsystem (tool loop, native-vs-text
protocol, full SSE event vocabulary), C3Bridge, Federated graph, and
Security model sections, all 17 services listed, stale line counts fixed,
Web UI section rewritten for the 8-tab concat bundle. api-reference.md adds
the /api/apikey, /api/chat, /api/graph/federated, /api/insights/cross and
/api/activity/digest/latest families plus the v2.47.0 write-gate auth note
and fixed /api/health payload. configuration.md now covers all 30 DEFAULTS
keys incl. the agents roster shape with the backend field. README leads
with c3 oracle serve. discovery-api.md lists c3_project/c3_artifacts, the
scope param, and delegate_task's project_path. changelog.md gains v1.3.0
(C3 v2.47.0-v2.48.0), v1.4.0 (C3 v2.49.0), and an honest 'previously
undocumented' block for the v2.32-v2.38 era features. AGENTS.md tree
updated; root CHANGELOG gains the v2.49.0 Wave 3 entry.

Author: drknowhow

AGENTS.md

@@ -133,9 +133,11 @@ claude-companion - v2/
     __init__.py
     config.py
     mcp_oracle.py
-    oracle.html
+    oracle.html        (legacy UI, served at /legacy for one release)
+    oracle_ui.html     (UI shell; JS concatenated from ui/ at serve time)
     oracle_server.py
-    services/ (16 files)
+    services/ (18 files)
+    ui/ (12 files + chat/ 6 files)
   oracle-guide/
     README.md
     api-reference.md

CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to Code Context Control (C3) are documented here.
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.49.0] - Unreleased
+
+### Oracle Wave 3: UI v3 concat bundle + `c3 oracle serve` + docs refresh
+
+#### UI architecture
+
+- **The 4,181-line `oracle.html` monolith is gone.** The dashboard now
+  follows the hub v2 concat architecture: an `oracle_ui.html` shell (CSS +
+  markup + `__C3_ORACLE_SCRIPTS__` token) plus **18 `oracle/ui/` modules**
+  split at section boundaries (core, busy, theme_tabs, crossgraph, header,
+  projects, insights, activity, suggestions, settings, agents,
+  `chat/{markdown,conversations,stream_renderer,toolbar,input,send}`, and
+  `app.js` — the init IIFE — last), concatenated server-side by
+  `_build_oracle_html()` with per-file markers. `GET /` serves the cached
+  bundle; **`GET /legacy` serves the frozen monolith for one release**, then
+  it will be removed. Extraction was verbatim (proven by a line-multiset
+  diff: the only delta is the `ORACLE_BUILD_TIME` bump) — zero behavior
+  change by construction.
+- Deliberate deviation from the original Wave-3 design: **no React/babel
+  runtime**. The Oracle UI logic is entirely vanilla imperative JS; the
+  transferable part of the hub pattern is the module structure + build
+  pipeline, and wrapping unowned vanilla code in a framework would have
+  added a CDN/transpile failure surface for zero owned UI.
+
+#### CLI
+
+- **`c3 oracle serve`** (alias `start`, `--port`, `--no-browser`) launches
+  the Oracle dashboard — no more `python oracle/oracle_server.py` required
+  (it still works). Lazy import keeps bare `c3` startup fast.
+
+#### Packaging
+
+- `pyproject.toml` package-data globs for `oracle/ui/*.js` +
+  `oracle/ui/chat/*.js` (the `"*"` globs only match a package's top level);
+  wheel inspection confirms all 18 modules + shell + legacy ship.
+
+#### Docs
+
+- `oracle-guide/` caught up a full product generation: chat subsystem + SSE
+  event protocol, C3Bridge, federated graph, security model (session cookie
+  + write gate), the 8-tab bundle UI, all missing config keys (incl. Wave
+  1–2 additions), missing endpoint families (`/api/apikey/*`, `/api/chat/*`,
+  `/api/graph/federated/*`, `/api/activity/digest/latest`), Discovery tool
+  list (c3_project/c3_artifacts/scope), and changelog entries v1.3.0 (Waves
+  1–2) / v1.4.0 (Wave 3) with a catch-up block for the previously
+  undocumented v2.32–v2.38 era features.
+
 ## [2.48.0] - Unreleased
 
 ### Oracle Wave 2: capability catch-up

cli/c3.py

@@ -5632,10 +5632,18 @@ def _bb_cmd_set_default(args, project_path: str) -> None:
 
 
 def cmd_oracle(args):
-    """Oracle Discovery API key + connection management."""
+    """Oracle dashboard server + Discovery API key management."""
     sub = getattr(args, "oracle_cmd", None)
+    if sub in ("serve", "start"):
+        # Lazy import: run_oracle builds all Oracle services (matches
+        # cmd_hub's deferred-import style so bare `c3` stays fast).
+        from oracle.oracle_server import run_oracle
+        run_oracle(port=getattr(args, "port", None),
+                   open_browser=not getattr(args, "no_browser", False))
+        return
     if sub != "api":
-        print("Usage: c3 oracle api {info,key,rotate,clear}")
+        print("Usage: c3 oracle {serve,api} — serve: launch the dashboard; "
+              "api {info,key,rotate,clear}: manage the Discovery key")
         return
 
     from oracle.config import load_config

cli/commands/parser.py

@@ -357,9 +357,18 @@ def build_parser(version: str, parse_cli_ide_arg):
     # ── Oracle Discovery API (v2.32.0) ──────────────────────────────────
     p_oracle = subparsers.add_parser(
         "oracle",
-        help="Oracle Discovery API key + connection management",
+        help="Oracle dashboard server + Discovery API key management",
     )
     or_subs = p_oracle.add_subparsers(dest="oracle_cmd")
+    or_serve = or_subs.add_parser(
+        "serve",
+        aliases=["start"],
+        help="Launch the Oracle dashboard server (REST + MCP discovery endpoints)",
+    )
+    or_serve.add_argument("--port", type=int, default=None,
+                          help="Server port (default: config 'port', 3331)")
+    or_serve.add_argument("--no-browser", action="store_true",
+                          help="Don't open the browser")
     or_api = or_subs.add_parser(
         "api",
         help="Show connection info / manage the Discovery API key",

oracle-guide/README.md

@@ -8,11 +8,14 @@ Oracle is an independent AI-powered memory management agent for the C3 ecosystem
 # Set your Ollama cloud API key
 export OLLAMA_API_KEY=your-key-here
 
-# Launch Oracle from the project root
-python oracle/oracle_server.py
+# Launch Oracle via the C3 CLI (v2.49.0+; alias: c3 oracle start)
+c3 oracle serve
 
 # Or with options
-python oracle/oracle_server.py --port 3332 --no-browser
+c3 oracle serve --port 3333 --no-browser
+
+# From a source checkout, the direct entry point still works
+python oracle/oracle_server.py [--port N] [--no-browser]
 ```
 
 Open `http://localhost:3331` in your browser.
@@ -23,6 +26,10 @@ Open `http://localhost:3331` in your browser.
 - **Ollama cloud**: Uses `https://ollama.com` with Bearer token auth by default. Can also target a local Ollama instance.
 - **Hub-aware**: Discovers projects through the C3 hub API or falls back to reading `~/.c3/projects.json` directly.
 - **Read + suggest-write**: Oracle reads project memory freely. Writes to project `.c3/facts/` require explicit user approval in the UI.
+- **Interactive chat**: a Chat tab (the default view) streams conversations with Oracle over SSE, with a tool-calling loop over the same tool registry the Discovery API exposes — native Ollama tool calling where the model supports it, text-protocol fallback otherwise.
+- **Team / Agents**: a configurable roster of specialist agents (Architect, Code Explorer, Memory Analyst by default) that chat can delegate sub-tasks to via `delegate_task`. Agents run on Ollama or, per-agent, on a CLI backend (codex/gemini/claude/auto) in read-only mode.
+- **Federated graph**: a Cross-Graph tab visualizes one memory graph across all projects, with embedding/TF-IDF similarity edges linking related facts between projects.
+- **Scheduled digest**: opt-in (`digest_enabled`) daily cross-project activity digest written by the background review loop and served at `/api/activity/digest/latest`.
 - **Discovery API (v2.32.0)**: External LLMs (Claude Code/Desktop or any function-calling model) can use Oracle's tools over MCP (`:3332/mcp`) and OpenAPI REST (`/api/discovery`) — Bearer-auth'd, loopback-bound, read + safe-action tiers only. See [Discovery API](discovery-api.md).
 - **Cross-project memory**: Maintains a global insight store (`~/.c3/oracle/cross_memory.json`) linking patterns, risks, and opportunities across projects.
 - **Background review**: A daemon thread periodically scans projects for changes, runs health checks, and generates consolidation suggestions.

oracle-guide/api-reference.md

@@ -4,6 +4,12 @@ Base URL: `http://localhost:3331` (configurable via `port` in config)
 
 All endpoints return JSON. POST endpoints accept JSON bodies with `Content-Type: application/json`.
 
+> **Auth (v2.47.0)**: ALL mutating (POST/PUT/DELETE) endpoints outside `/api/discovery/*`
+> require either the dashboard session cookie (a per-boot `HttpOnly` cookie issued on
+> `GET /` to loopback browsers) or the Discovery Bearer token
+> (`Authorization: Bearer <token>`). Unauthenticated mutations get `401`. `GET` reads
+> are open to allowed local origins; `/api/discovery/*` is Bearer-only (see below).
+
 ---
 
 ## Health & Config
@@ -17,7 +23,9 @@ Returns Oracle status and Ollama cloud availability.
   "status": "ok",
   "service": "c3-oracle",
   "model": "gemma4:31b-cloud",
-  "ollama_available": true
+  "ollama_available": true,
+  "model_verified": true,
+  "hub_available": true
 }
 ```
 
@@ -227,6 +235,55 @@ Dismiss an insight (marks `dismissed: true`, excluded from future listings).
 { "dismissed": true, "id": "ins_a1b2c3d4e5f6" }
 ```
 
+### `POST /api/insights/cross`
+
+On-demand cross-project insight generation from the federated graph. Requires at least
+2 projects with facts (defaults to all discovered projects with facts; override with
+`projects`).
+
+```json
+// Request (optional body)
+{ "projects": ["/path/a", "/path/b"] }
+
+// Response
+{ "generated": 3, "insights": [ ... ], "graph_stats": { ... } }
+```
+
+---
+
+## Federated Graph
+
+Cross-project memory graph: per-project fact graphs merged, plus `cross_similar`
+edges between facts of different projects (embeddings with TF-IDF fallback). Builds
+are cached (`federated_graph_ttl_sec` + facts mtimes); the project hierarchy overlay
+is recomputed per serve.
+
+### `GET /api/graph/federated`
+
+**Query params:** `projects` (comma-separated paths; default = all discovered projects
+with facts), `min_sim` (similarity threshold override), `top_k` (neighbors per fact),
+`force=1` (bypass cache).
+
+Returns `nodes`, `edges`, `projects` (each with `parent_slug`), `stats` (including
+`parent_child`), and `hierarchy` (parent/child project links).
+
+### `GET /api/graph/federated/node/<id>`
+
+One node's fact plus its cross-project neighbors.
+
+```json
+{ "node": { ... }, "neighbors": [ { "id": "...", "type": "cross_similar",
+  "scope": "cross", "weight": 0.82, "label": "...", "project": "..." } ] }
+```
+
+### `POST /api/graph/federated/rebuild`
+
+Invalidate the cache and force a rebuild. Optional body `{ "projects": [ ... ] }`.
+
+### `GET /api/graph/federated/stats`
+
+Graph stats + project list only (no nodes/edges).
+
 ---
 
 ## Activity
@@ -261,6 +318,19 @@ summary — best-effort, omitted on failure).
 > Also available as the discovery tool **`activity_report`** (identical payload) for
 > external LLMs over MCP, OpenAPI, and `POST /api/discovery/call`.
 
+### `GET /api/activity/digest/latest`
+
+Most recent **scheduled** digest, written by the review loop when `digest_enabled` is
+set (serves `~/.c3/oracle/activity_digests/latest.json`). On-demand digests from
+`/api/activity/digest` are not persisted here.
+
+```json
+{ "generated_at": "2026-07-02T00:00:12+00:00", "digest": { ... } }
+
+// No scheduled digest yet
+{ "digest": null, "generated_at": null }
+```
+
 ---
 
 ## Suggestions
@@ -368,6 +438,108 @@ Test generation with the current model. Sends a simple prompt and returns the re
 
 ---
 
+## Chat
+
+Interactive chat with Oracle (the dashboard's Chat tab). Conversations are persisted
+in `~/.c3/oracle/conversations/`.
+
+### `POST /api/chat`
+
+Streaming chat over SSE (`text/event-stream`). Each event is a JSON object on a
+`data:` line with a `type` field; the stream ends with a literal `data: [DONE]`.
+
+```json
+// Request
+{ "message": "what changed across my projects today?", "conversation_id": "c_..." }
+```
+
+**Event vocabulary** (documented once here; the same shapes appear in the agent
+sub-stream):
+
+| Type | Meaning |
+|------|---------|
+| `meta` | First event: `conv_id`, `model`, conversation `state` |
+| `status` | Progress updates (`message` + `detail`) |
+| `thinking` | Streamed model reasoning chunks |
+| `text` | Streamed visible answer chunks |
+| `tool_call` | Oracle invoking a tool (`name`, `args`, `tool_id`) |
+| `tool_result` | Tool output (`tool_id`, result) |
+| `agent_start` / `agent_round` / `agent_thinking` / `agent_text` / `agent_tool_call` / `agent_tool_result` / `agent_done` | Sub-stream while `delegate_task` runs a roster agent |
+| `done` | Turn complete (timing/stats) |
+| `error` | Terminal error for the turn |
+
+Tool calling is native Ollama tool calling when the model supports it (probed via
+`/api/show`), with automatic mid-turn fallback to the legacy `<tool_call>` text
+protocol if the model rejects native tools.
+
+### `GET /api/chat/conversations?limit=50`
+
+List conversations (most recent first).
+
+### `POST /api/chat/conversations`
+
+Create a conversation. Body `{ "title": "..." }` (optional). Returns `201` with `{ "id": "c_..." }`.
+
+### `GET /api/chat/conversations/<id>`
+
+Full message history: `{ "conversation_id": "...", "messages": [ ... ] }`.
+
+### `DELETE /api/chat/conversations/<id>`
+
+Delete a conversation. Returns `{ "ok": true }`.
+
+### `PUT /api/chat/conversations/<id>/title`
+
+Rename. Body `{ "title": "..." }`.
+
+### `GET /api/chat/conversations/<id>/state`
+
+Per-conversation state (focused projects, model, depth): `{ "state": { ... } }`.
+
+### `GET /api/chat/commands`
+
+Slash-command registry for frontend autocomplete: `{ "commands": [ ... ] }`.
+
+### `POST /api/chat/command`
+
+Execute a slash command (e.g. `/project`, `/model`, `/depth`, `/team`).
+
+```json
+// Request
+{ "conversation_id": "c_...", "command": "/depth deep" }
+```
+
+---
+
+## Discovery API key (`/api/apikey`)
+
+Dashboard-facing management of the Discovery Bearer token (stored in the OS keyring).
+The POST mutations are covered by the v2.47.0 write gate: they require the session
+cookie or the Bearer token.
+
+### `GET /api/apikey`
+
+Token status + connection info (`exists`, `masked`, `mcp_url`, `rest_base`,
+`openapi_url`, a ready-to-paste `.mcp.json` `snippet`, and the `api_enabled` /
+`api_require_auth` / `mcp_enabled` flags). The **unmasked** `key` is included only
+when the caller presents a valid Bearer token or the dashboard session cookie;
+otherwise `key` is empty and the snippet carries a `<token>` placeholder.
+
+### `POST /api/apikey/generate`
+
+Create a token if none exists. Reveals the key in the response (explicit local
+creation action, shown once for copy).
+
+### `POST /api/apikey/rotate`
+
+Replace the token with a fresh one (revealed once for copy).
+
+### `POST /api/apikey/clear`
+
+Delete the stored token.
+
+---
+
 ## Discovery API (external LLM tool surface)
 
 > Added in v2.32.0. Lets Claude or any function-calling LLM use C3's cross-project
@@ -431,11 +603,14 @@ Connection details for the MCP transport.
 ### Capability tiers
 
 - **read** — discovery only: `list_projects`, `search_facts`, `query_memory`,
-  `project_health`, `analyze_project`, `cross_insights`, `read_graph`, `c3_search`,
-  `c3_search_cross`, `c3_read`, `c3_compress`, `c3_validate`, `c3_status`,
-  `c3_memory_query`, `c3_edits`, `c3_edits_cross`.
+  `project_health`, `analyze_project`, `cross_insights`, `read_graph`,
+  `activity_report`, `c3_search`, `c3_search_cross`, `c3_read`, `c3_compress`,
+  `c3_validate`, `c3_status`, `c3_memory_query`, `c3_edits`, `c3_edits_cross`,
+  `c3_project`, `c3_artifacts` (the latter two are read-only by construction:
+  write verbs are blocked).
 - **action** — adds safe, non-code-edit writes: `suggest_action` (creates a
-  *pending* suggestion for human approval) and `delegate_task`.
+  *pending* suggestion for human approval) and `delegate_task` (optional
+  `project_path`, required for CLI-backed agents).
 - Code-editing tools are **never** exposed. Cap the tier via `api_max_tier`
   (`read` | `action`) in `~/.c3/oracle/config.json`.