nova-ai-pro 1.2.3.dev78__tar.gz → 1.2.3.dev85__tar.gz

{nova_ai_pro-1.2.3.dev78 → nova_ai_pro-1.2.3.dev85}/.gitignore

@@ -142,3 +142,7 @@ frontend/tsconfig.tsbuildinfo
 
 # PyInstaller build debris
 *.spec
+
+# GitHub API debug dumps (gh jobs listing pulled during local debugging)
+jobs.json
+jobs_auth.json

{nova_ai_pro-1.2.3.dev78 → nova_ai_pro-1.2.3.dev85}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nova-ai-pro
-Version: 1.2.3.dev78
+Version: 1.2.3.dev85
 Summary: NOVA AI — modular AI assistant backend with composable intelligence primitives
 Project-URL: Homepage, https://github.com/Hamza35779/NOVA-AI
 Project-URL: Documentation, https://hamza35779.github.io/NOVA-AI/
@@ -89,6 +89,11 @@ Requires-Dist: mkdocs-literate-nav>=0.6; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocs>=1.6; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: dpo-training
+Requires-Dist: peft>=0.10; extra == 'dpo-training'
+Requires-Dist: torch>=2.0; extra == 'dpo-training'
+Requires-Dist: transformers>=4.40; extra == 'dpo-training'
+Requires-Dist: trl>=0.8; extra == 'dpo-training'
 Provides-Extra: energy-all
 Requires-Dist: amdsmi>=6.1; extra == 'energy-all'
 Requires-Dist: pynvml>=12.0; extra == 'energy-all'

{nova_ai_pro-1.2.3.dev78 → nova_ai_pro-1.2.3.dev85}/docs/architecture/learning.md

@@ -618,3 +618,11 @@ The `lora_finetune` op is now real: `LoraFinetuneApplier` (`src/nova_ai/learning
 ### Model proving ground (head-to-head model A/B)
 
 `nova_ai.learning.proving` closes the model-adoption loop: a benchmark synthesized from high-feedback traces (`PersonalBenchmarkSynthesizer`) is run through `EvalRunner` twice — candidate vs incumbent, same seed, same judge (the incumbent itself by default) — and `RunSummary.per_subject` keys accuracy by routing query class (`classify_query`). A verdict requires ≥ 3 scored samples per class per side; adoption additionally requires a ≥ `min_margin` win. Winners land in `~/.nova_ai/learning/proving/policy_map.json` via `nova prove adopt`, and SmartRouter serves them per class only with the opt-in `proving_adoption` router flag. The gauntlet is read-only; adoption is the only mutation and is reversible (`nova prove revert`). See [Model Proving Ground](../learning/proving-ground.md).
+
+### Memory consolidation (the sleep cycle)
+
+`nova_ai.memory.consolidation` turns episodic traces into durable knowledge: `SessionMiner` clusters recent traces by query class (optionally refined by embedding similarity), a local LLM distills each cluster into atomic facts (`{content, topic, confidence}`), and `FactStore` (`~/.nova_ai/learning/consolidation/facts.db`) deduplicates them, resolves contradictions by confidence (winner supersedes; unconfident pairs coexist), and decays facts untouched for `decay_days`. Active facts render as a bounded core-memory block (`memory.consolidation.inject`) prepended to every query by `QueryOrchestrator.ask` — fail-open: an empty or broken fact base never breaks answering. Off by default; `nova memory consolidate forget` is the manual override. See [Memory Consolidation](../learning/memory-consolidation.md).
+
+### Skill Foundry (synthesize skills from repeated tool runs)
+
+`nova_ai.learning.skillforge` turns repeated multi-step tool workflows into skills: `PatternMiner` groups `TOOL_CALL` trace steps by ordered sequence (≥ `min_pattern_count` repetitions, feedback ≥ `min_feedback`), `SkillSynthesizer` has the local LLM write a `skill.toml` constrained to the real `ToolRegistry` catalog and the observed call order, and `run_gauntlet` verifies the candidate in three gates — static (name/capabilities/unknown-tool rejection), replay (mined examples through `SkillExecutor`, code/shell steps forced through the subprocess sandbox), and judge (LLM vs the trace's known-good result). Adoption writes `~/.nova_ai/skills/generated/<name>/skill.toml` with a provenance block — discovered automatically, reversible with `nova forge revert`. Off by default; `nova forge adopt` is the only mutation. See [Skill Foundry](../learning/skill-foundry.md).

nova_ai_pro-1.2.3.dev85/docs/learning/conversation-forking.md

@@ -0,0 +1,112 @@
+---
+title: Conversation Forking
+description: Fork the conversation, race two models on the real query, keep the winner — and every pick becomes DPO training data
+---
+
+# Conversation Forking: keep the winner, train on the choice
+
+Most chat apps make you *accept* an answer. NOVA lets you **keep both** — and then asks which one was better. Fork the conversation to get a second branch, regenerate for a fresh sibling answer, race two models head-to-head on the real query. Your pick is recorded as a **preference pair**, and the DPO training lane turns those pairs into a model that answers the way *you* would have chosen.
+
+**The pitch: every fork, regen, and race ends in a pick — and every pick is training data.**
+
+## The preference flywheel
+
+```
+   ┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ Conversation │───▶│ Fork / Regenerate│───▶│ Model race        │
+   │ tree (nodes  │    │ = sibling answer │    │ 2+ models, one    │
+   │ with parent) │    │ under same prompt│    │ prompt, judged    │
+   └──────────────┘    └──────────────────┘    └─────────┬─────────┘
+                                                         ▼
+   ┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ nova train   │◀───│ preference_pairs │◀───│ You pick (app /   │
+   │ run --lane   │    │ table: chosen vs │    │ auto-judge first- │
+   │ dpo          │    │ rejected, source │    │ line YES/NO)      │
+   └──────────────┘    └──────────────────┘    └───────────────────┘
+```
+
+## How the tree works
+
+Conversations are stored as a **tree of nodes**, not a linear transcript. Every message is a node with a `parent_id`; the visible conversation is one root-to-tip path. A fork is not a copy — it is a **second child of the same parent**, so both branches see the identical history and nothing is duplicated:
+
+```
+(root) ── user: "review this patch"
+             ├── assistant: "ship it"            ◀ pick this
+             └── assistant: "one bug: off-by-1"   (sibling from fork/regen/race)
+```
+
+- **Fork** (`POST /api/conversations/{id}/fork`, app Fork button) — creates a sibling of the chosen node carrying the same content with a `fork_of` metadata marker. Continue down either branch.
+- **Regenerate** (`POST /api/conversations/{id}/regenerate`) — generates a fresh assistant answer under the same prompt node via the server engine, returning the new sibling and the existing ones. In the app: the Regenerate button under the last assistant message. Cycle through siblings with the «» arrows.
+- **Race** (`POST /api/conversations/{id}/race`) — races 2+ models on one prompt node. Each model becomes a sibling assistant node. With `judge: true` (or `nova conversation` auto-judging) a strict judge compares the two strongest candidates with the same first-line YES/NO convention as the [Proving Ground](proving-ground.md); the winner is recorded automatically.
+
+## Recording a pick
+
+Sibling groups only become training data when a **choice** is made — by you or the judge:
+
+- **In the app** — picking a sibling with the arrows records the pair (`source: regen`); racing records it automatically (`source: race`).
+- **In the CLI** — `nova conversation pick NODE_ID --source fork` marks one sibling chosen and its sisters rejected.
+- **From traces** — the DPO miner also reads the trace store: the same query asked twice with feedback improving (`source: regen`), or a thumbs-down followed by a later better answer (`source: thumbs`).
+
+Each pick writes one `preference_pairs` row: the full `prompt_path`, `chosen_id`, `rejected_ids`, `source` (`fork | regen | race | thumbs`), timestamp. Provenance is complete — you can always ask *why* the model was shown a choice.
+
+## The DPO lane
+
+The pairs feed a second training lane alongside the SFT loop. Where SFT teaches the model *what a good answer looks like*, **DPO (Direct Preference Optimization)** teaches it *which of two answers is better* — exactly the signal forking produces.
+
+```bash
+# See how much preference data you have
+nova conversation pairs
+
+# Train a DPO adapter (same benchmark gate + pending review as SFT)
+nova train run --lane dpo
+```
+
+- Config: `[learning.training] dpo_enabled = true`, `dpo_min_pairs = 20`, `dpo_tag_prefix = "nova-dpo"`.
+- Adapters land under `adapters/<run_id>/dpo/`, run records carry `lane = "dpo"`, and Ollama deploys tag as `nova-dpo-<model>` — so the [Proving Ground](proving-ground.md) can prove the tuned adapter against the base automatically.
+- Scheduling works too: `nova scheduler create "nightly dpo" --cron "0 4 * * *" --metadata '{"kind": "train", "lane": "dpo"}'`.
+
+Details, config, and the trainer's own knobs (β, LoRA rank, epochs): [Self-Training → Preference tuning lane](self-training.md#preference-tuning-lane).
+
+## Quickstart
+
+```bash
+# Headless fallback for the app UI
+nova conversation list
+nova conversation show CONV_ID          # ASCII tree, ◀ marks the active path
+nova conversation show CONV_ID --node NODE_ID
+
+# Record a choice between sibling answers
+nova conversation pick NODE_ID --source fork
+
+# Count the DPO data you have accrued
+nova conversation pairs                 # or --json for scripts
+```
+
+## API reference
+
+All endpoints are mounted under `/api/conversations` in the server app:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /api/conversations` | Create a conversation (`{title}`) → `{id, root_id}` |
+| `GET /api/conversations` | List conversations (id, title, node count, last activity) |
+| `GET /api/conversations/{id}/tree` | Whole tree: `{nodes, children}` keyed by parent |
+| `POST /api/conversations/{id}/messages` | Add a node (`{role, content, parent_id?}`) |
+| `POST /api/conversations/{id}/fork` | Sibling fork of a node (`{node_id}`) |
+| `POST /api/conversations/{id}/regenerate` | Fresh engine-generated sibling answer |
+| `POST /api/conversations/{id}/race` | `{models, prompt_node_id?, judge?}` → per-model candidates + winner |
+| `POST /api/conversations/nodes/{id}/feedback` | Attach a thumbs score to a node |
+| `POST /api/conversations/nodes/{id}/pick` | `{chosen_node_id, source?}` → preference pair |
+| `GET /api/conversations/preference-pairs` | Recorded pairs (the DPO miner's input) |
+
+## Artifacts
+
+| Path | Contents |
+|------|----------|
+| `~/.nova_ai/conversations.db` | The conversation tree + preference pairs |
+
+## See also
+
+- [Self-Training — Preference tuning lane](self-training.md#preference-tuning-lane) — what happens to the pairs.
+- [Model Proving Ground](proving-ground.md) — the same head-to-head + judge discipline, for models instead of answers.
+- [Memory Consolidation](memory-consolidation.md) — the other consumer of your conversation history.

nova_ai_pro-1.2.3.dev85/docs/learning/fleet-oracle.md

@@ -0,0 +1,100 @@
+---
+title: Fleet Oracle
+description: "Best 8B model for code on a 4090?" — answered by the fleet, not the vendor
+---
+
+# Fleet Oracle: ask the fleet, not the vendor
+
+Vendor benchmarks are marketing. Community leaderboards are outliers. What actually answers "*will this model be fast on my machine?*" is real people running real workloads on real hardware — which is exactly what the Fleet Oracle pools.
+
+NOVA machines can (opt-in) publish a tiny anonymized report of their hardware and per-model performance averages to a shared git repo. Anyone can then query that dataset locally: `nova oracle ask "best 8B model for code on a 4090?"`.
+
+**Everything is local by default. Sharing is OFF until you flip it on.**
+
+## The loop
+
+```
+   ┌────────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ Your telemetry │───▶│ build_report     │───▶│ git push          │
+   │ (stays local)  │    │ fixed field list │    │ (only if opt-in)  │
+   └────────────────┘    └──────────────────┘    └─────────┬─────────┘
+                                                           ▼
+   ┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ nova oracle  │◀───│ query_fleet      │◀───│ shared dataset    │
+   │ ask "..."    │    │ buckets + winner │    │ (git repo)        │
+   └──────────────┘    └──────────────────┘    └───────────────────┘
+```
+
+## Privacy model: a fixed field list, nothing else
+
+The report is not a redaction of something bigger — it is **constructed from a fixed field list**. There is no code path that could leak anything else:
+
+| Field | Value |
+|-------|-------|
+| `hardware.platform` | `windows` / `linux` / `darwin` |
+| `hardware.cpu_count` | core count |
+| `hardware.ram_gb` | total RAM (rounded) |
+| `hardware.gpu.{vendor,name,vram_gb}` | GPU shape only — no compute capability, no count |
+| `models[].model_id` | e.g. `qwen3.5:9b` |
+| `models[].engine` | e.g. `ollama` |
+| `models[].call_count` | calls in the window |
+| `models[].avg_latency_s`, `avg_ttft_s` | latency averages |
+| `models[].avg_throughput_tok_per_sec` | throughput |
+| `models[].avg_tokens_per_joule` | energy efficiency |
+| `models[].total_tokens` | volume in the window |
+| `report_id` | `hash_id(platform|cpu|ram|gpu)` — a stable pseudonym for dedupe |
+
+What never leaves the machine: **no prompts, no responses, no file paths, no user IDs, no timestamps** (only the aggregation window length), no IP addresses. Models with fewer calls than `min_calls_per_model` are dropped (k-anonymity) so a personal model can't be fingerprinted.
+
+```toml
+# ~/.nova_ai/config.toml
+[learning.fleet]
+share_reports = false          # opt-in — this is the switch
+dataset_repo = ""              # git URL of the shared dataset repo
+min_calls_per_model = 5        # k-anonymity threshold
+since_days = 30                # aggregation window
+```
+
+## Commands
+
+```bash
+# Build and preview the report — see exactly what sharing would publish
+nova oracle export
+nova oracle export -o report.json     # write it to a file instead
+
+# Publish it (refuses unless share_reports = true)
+nova oracle push
+
+# Ask the fleet — answered locally from the dataset, no LLM involved
+nova oracle ask "best 8B model for code on a 4090?"
+nova oracle ask "most energy efficient model on 16 gb?"
+
+# Config + dataset state
+nova oracle status
+```
+
+## How questions are answered
+
+Deliberately simple and explainable — no LLM in the loop:
+
+1. **Intent** — keyword buckets pick the ranking metric: *fast/latency* → avg latency (lower wins), *throughput/tok/s* → throughput, *energy/efficient/watt* → tokens per joule, *code* → throughput as the quality proxy.
+2. **Hardware bucket** — the question's VRAM hint (`"24 gb"` or a known card like `4090`) selects a VRAM bucket (`<=8GB`, `9-16GB`, `17-24GB`, `25-48GB`, `>48GB`).
+3. **Winner** — within the bucket, per-model stats are call-weighted across machines; the metric winner is the headline. The full table is printed underneath.
+
+Every answer is inspectable: the table shows machines and call counts behind it, so you can see how much data the answer rests on.
+
+## Running a fleet dataset
+
+The dataset is an ordinary git repo of `reports/<report_id>.json` files — no server, no API. To host one: create a repo, point `dataset_repo` at it for everyone in the group, and merge push requests if you want curation. Any git remote works (GitHub, Gitea, a bare repo on a NAS).
+
+## Artifacts
+
+| Path | Contents |
+|------|----------|
+| `~/.nova_ai/fleet/cache/` | Local clone of the dataset repo (read + push staging) |
+
+## See also
+
+- [Telemetry](../user-guide/telemetry.md) — the local data the reports are built from.
+- [Model Proving Ground](proving-ground.md) — proving candidate models on *your* traces before adopting them.
+- [Self-Training](self-training.md) — the other consumer of your local performance data.

nova_ai_pro-1.2.3.dev85/docs/learning/memory-consolidation.md

@@ -0,0 +1,112 @@
+---
+title: Memory Consolidation
+description: NOVA sleeps on your conversations and wakes up smarter — distilling durable facts into a core memory it injects into every query
+---
+
+# Memory Consolidation: NOVA's sleep cycle
+
+Every chat leaves traces, and the useful parts — your stack, your naming conventions, "deploys on Fridays are forbidden", the project you keep circling back to — stay scattered across hundreds of rows. Memory consolidation is a **sleep cycle**: on schedule (or on demand) NOVA replays recent conversations, clusters the related ones, and distills them into a short list of **atomic facts** with provenance. Those facts become a compact **core memory** prepended to every query, so NOVA *stays* knowing you without you re-explaining.
+
+**The pitch: NOVA sleeps on your conversations and wakes up smarter.**
+
+## The cycle
+
+```
+   ┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ Recent traces│───▶│ SessionMiner     │───▶│ Fact extraction   │
+   │ (traces.db)  │    │ (class buckets + │    │ (local LLM per    │
+   │              │    │  embedding       │    │  cluster → JSON)  │
+   └──────────────┘    │  clusters)       │    └─────────┬─────────┘
+                       └──────────────────┘              ▼
+   ┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ Core memory  │◀───│ facts.db         │◀───│ Dedup + resolve   │
+   │ in every     │    │ (confidence,     │    │ contradictions    │
+   │ query        │    │  provenance)     │    │ (recency+conf)    │
+   └──────────────┘    └──────────────────┘    └───────────────────┘
+```
+
+1. **Mine** — recent traces are bucketed by query class (`code` / `math` / …), then optionally split further by embedding similarity within each class. Clusters smaller than `min_session_messages` are dropped: one-off chats are noise, patterns are signal.
+2. **Distill** — each cluster goes to the local model with a strict extraction prompt (JSON array of `{content, topic, confidence}` — no prose). Clusters fail independently; a broken cluster never sinks the run.
+3. **Resolve** — new facts are deduplicated against the active fact base (exact/containment match → the old row is *touched*, its `last_seen` refreshed). Contradictions ("prefers tabs" vs "does not prefer tabs") are resolved by **confidence**: a strictly more confident new fact supersedes the old one; an unconfident one is recorded *alongside* and both stay.
+4. **Decay** — facts untouched for `decay_days` flip from `active` to `decayed` and stop being served. Memory that isn't reinforced fades — like yours.
+5. **Serve** — active facts render as a `## What NOVA knows about you` block (packed under `core_memory_max_chars`, highest confidence first) and are injected as a system message on every query.
+
+## Quickstart
+
+```toml
+# ~/.nova_ai/config.toml
+[learning.consolidation]
+enabled = true
+```
+
+```bash
+# Run one cycle (background by default, --foreground to watch it work)
+nova memory consolidate run --foreground
+
+# Inspect what NOVA learned
+nova memory consolidate status      # latest run summary
+nova memory consolidate facts       # the fact base as a table
+
+# Something wrong or stale? Remove it — the manual override always wins
+nova memory consolidate forget fact_ab12cd34ef56
+```
+
+Fact provenance is preserved end-to-end: every fact stores the trace IDs of the conversations it was distilled from, so you can always trace a "fact" back to where NOVA got it.
+
+## Running it nightly
+
+Create a scheduler task with `kind="consolidate"` metadata (requires `[learning.consolidation] enabled = true`):
+
+```bash
+nova scheduler create "memory sleep cycle" --cron "30 3 * * *" \
+  --metadata '{"kind": "consolidate"}'
+```
+
+The scheduled run behaves exactly like a foreground run and logs `[consolidate] run consol_…: completed (facts_added=N, …)` to the task's run log.
+
+## The injection contract
+
+Core-memory injection is **fail-open everywhere**: an empty fact base injects nothing, a broken fact store logs at debug and the query proceeds untouched, and the block is capped at `core_memory_max_chars` so it can never crowd out your actual prompt. It composes with (and runs after) the existing vector-memory context injection — vector memory provides *what you told NOVA before*, core memory provides *what NOVA concluded*.
+
+## Safety model
+
+1. **Off by default** — `enabled = false`; nothing runs until you opt in.
+2. **Manual override is supreme** — `forget` removes a fact instantly; a superseded fact keeps its row (status `superseded`, with `superseded_by`) so history is auditable.
+3. **Local-only** — extraction uses your configured local engine (`judge_model = ""` → `intelligence.default_model`); no conversation content leaves the machine.
+4. **Bounded** — `max_facts_per_run` caps distillation per run; the served block is capped by characters.
+
+## Config reference
+
+```toml
+[learning.consolidation]
+enabled = false              # master switch
+schedule = ""                # cron expression; empty = run manually
+min_session_messages = 6     # skip clusters smaller than this
+max_facts_per_run = 50       # cap on facts distilled per run
+judge_model = ""             # "" uses intelligence.default_model
+decay_days = 90              # facts untouched this long stop being served
+core_memory_max_chars = 4000 # core-memory block budget
+```
+
+## Artifacts
+
+| Path | Contents |
+|------|----------|
+| `~/.nova_ai/learning/consolidation/facts.db` | Fact base (`nova memory consolidate facts`) |
+| `~/.nova_ai/learning/consolidation/runs.db` | Run history (`nova memory consolidate status`) |
+| `~/.nova_ai/learning/consolidation/last_run.log` | Background run output |
+
+## CLI reference
+
+| Command | What it does |
+|---------|-------------|
+| `nova memory consolidate run [--foreground]` | Run one sleep cycle |
+| `nova memory consolidate status` | Latest run summary |
+| `nova memory consolidate facts [-n N]` | Fact table (confidence, topic, content) |
+| `nova memory consolidate forget FACT_ID` | Remove a fact (manual override) |
+
+## See also
+
+- [Model Proving Ground](proving-ground.md) — the same distill→verify→adopt-by-hand discipline, for models.
+- [Memory](../user-guide/memory.md) — the vector memory store consolidation composes with.
+- [Conversation Forking](conversation-forking.md) — the other way your conversation history becomes training signal.

{nova_ai_pro-1.2.3.dev78 → nova_ai_pro-1.2.3.dev85}/docs/learning/self-training.md

@@ -107,6 +107,40 @@ Background runs spawn a detached process (Windows-safe) writing to `~/.nova_ai/l
 | `~/.nova_ai/learning/training/runs.db` | Run history (`nova train list`) |
 | `~/.nova_ai/learning/training/merged/<model>/` | Merged models (llamacpp target) |
 
+## Preference tuning lane (DPO)
+
+SFT clones *an* answer; **DPO (Direct Preference Optimization)** teaches the model *which of two answers is better*. The second training lane consumes the preference pairs recorded by [conversation forking](conversation-forking.md) — fork/regenerate/model-race sibling choices — plus two trace-derived signals (same query asked twice with feedback improving, and a thumbs-down followed by a better later answer).
+
+```
+   ┌──────────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ preference_pairs │───▶│ DPO miner        │───▶│ DPOTrainer (trl + │
+   │ fork / regen /   │    │ dedup, drop      │    │ LoRA, β=0.1, lr   │
+   │ race / thumbs    │    │ identical pairs  │    │ 5e-6, 1 epoch)    │
+   └──────────────────┘    └──────────────────┘    └─────────┬─────────┘
+                                                         ▼
+   ┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ nova-dpo-    │◀───│ deploy (manual   │◀───│ Same benchmark    │
+   │ <model> tags │    │ pending_review)  │    │ gate as SFT       │
+   └──────────────┘    └──────────────────┘    └───────────────────┘
+```
+
+```toml
+# ~/.nova_ai/config.toml — appended to [learning.training]
+dpo_enabled = true           # master switch for the DPO lane
+dpo_min_pairs = 20           # minimum preference pairs before a run starts
+dpo_tag_prefix = "nova-dpo"  # Ollama tag prefix for DPO deploys
+```
+
+```bash
+# See what preference data you have
+nova conversation pairs
+
+# Train + deploy the DPO adapter (same gates as SFT)
+nova train run --lane dpo
+```
+
+Lane behavior mirrors SFT exactly: pairs are capped at `max_pairs`, the benchmark gate and `pending_review` still apply, adapters save under `adapters/<run_id>/dpo/`, runs record `lane = "dpo"`, and scheduled runs pick the lane from the task's `lane` metadata. TRL is an optional dependency — `pip install 'nova-ai[dpo-training]'` — and the CLI refuses a DPO run with a clear message when `[learning.training] dpo_enabled` is off.
+
 ## Where it plugs into spec-search
 
 The `LoraFinetuneApplier` (`src/nova_ai/learning/spec_search/execute/appliers/lora.py`) implements the `lora_finetune` edit op, so the teacher can propose weight updates when diagnosis shows a skill gap that prompt edits can't fix. In TIERED/MANUAL autonomy it routes to review like any MANUAL-tier edit; with `auto_apply` it trains and activates the adapter directly. The old `LoraStubApplier` remains as the torch-free fallback that refuses the op with a clear message.
@@ -114,3 +148,10 @@ The `LoraFinetuneApplier` (`src/nova_ai/learning/spec_search/execute/appliers/lo
 ## Requirements
 
 Training requires `torch`, `transformers`, and `peft` (install with `pip install torch transformers peft`). Everything else — mining, export, run history, deployment plumbing — works without them; the CLI reports a clear install hint if torch is missing at train time.
+
+## See also
+
+- [Conversation Forking](conversation-forking.md) — where the DPO preference pairs come from.
+- [Model Proving Ground](proving-ground.md) — prove a freshly trained adapter against the base before adopting it.
+- [Memory Consolidation](memory-consolidation.md) — the other offline loop that distills your history.
+- [Skill Foundry](skill-foundry.md) — the sibling "learn from traces" pipeline for tool workflows.

nova_ai_pro-1.2.3.dev85/docs/learning/skill-foundry.md

@@ -0,0 +1,117 @@
+---
+title: Skill Foundry
+description: Show NOVA a task twice — it forges the skill, proves it on your past runs, and installs it only when you say so
+---
+
+# Skill Foundry: your repeated workflows become skills
+
+Watch any operator long enough and you'll see it: the same three tool calls, in the same order, on slightly different inputs — search, then summarize, then file it away. The Skill Foundry notices. It mines your traces for **repeated multi-step tool sequences**, asks your local model to write a skill manifest chaining those tools, verifies the candidate against your own past runs in a three-gate gauntlet, and — only when you approve — installs it as a first-class skill.
+
+**The pitch: show NOVA a task three times — it writes the skill and proves it before you ever run it.**
+
+## The forge
+
+```
+   ┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ Your traces  │───▶│ PatternMiner     │───▶│ SkillSynthesizer  │
+   │ (TOOL_CALL   │    │ same sequence    │    │ local LLM writes  │
+   │  steps)      │    │ ≥ 3x, feedback   │    │ skill.toml against│
+   └──────────────┘    │ ≥ 0.7            │    │ the real catalog  │
+                       └──────────────────┘    └─────────┬─────────┘
+                                                         ▼
+   ┌──────────────┐    ┌──────────────────┐    ┌───────────────────┐
+   │ Installed    │◀───│ nova forge adopt │◀───│ Gauntlet          │
+   │ skill lives  │    │ (the only        │    │ static → replay → │
+   │ in generated/│    │  mutation)       │    │ judge             │
+   └──────────────┘    └──────────────────┘    └───────────────────┘
+```
+
+1. **Mine** — `PatternMiner` extracts ordered tool sequences from `TOOL_CALL` trace steps. Traces are grouped by exact sequence; a pattern qualifies with `min_pattern_count` repetitions and average feedback at least `min_feedback`. Single-tool traces are ignored — one-call "skills" are just tools.
+2. **Synthesize** — `SkillSynthesizer` prompts the local model with the observed sequence, the **real tool catalog** (names, descriptions, parameter schemas from the `ToolRegistry`), and worked examples with the actual recorded arguments. The output must parse through the stock `load_skill` and its step tools must match the observed order — anything else gets one retry, then rejection.
+3. **Gauntlet** — three sequential gates, each reported by name:
+   - **static** — name/description sanity, capability validation, no dangerous capabilities, and every step targets a tool that actually exists.
+   - **replay** — each mined example runs through `SkillExecutor` against your real tools; code/shell-shaped steps are forced through the **subprocess sandbox** with `sandbox_timeout`.
+   - **judge** — the LLM compares replay output with the trace's known-good result (first line YES/NO, same convention as the proving ground).
+4. **Adopt** — candidates wait in `passed` state. `nova forge adopt` writes `~/.nova_ai/skills/generated/<name>/skill.toml` with a provenance block (run id, pattern count, gauntlet report). `nova forge revert <name>` deletes it. Discovery is automatic — adopted skills are ordinary skills.
+
+## Quickstart
+
+```toml
+# ~/.nova_ai/config.toml
+[learning.skillforge]
+enabled = true
+```
+
+```bash
+# Mine + synthesize + gauntlet (background by default, --foreground to watch)
+nova forge run --foreground
+
+# Inspect candidates and their gauntlet reports
+nova forge status        # latest run, gate-by-gate
+nova forge list          # all candidates
+
+# Your call — install it or reject it
+nova forge adopt forge_20260903_ab12cd34
+nova forge reject forge_20260903_ef56ab78
+
+# Undo any time
+nova forge revert search-and-summarize
+```
+
+## Running it on a schedule
+
+```bash
+nova scheduler create "forge skills" --cron "0 5 * * *" \
+  --metadata '{"kind": "skillforge"}'
+```
+
+The scheduled run behaves exactly like a foreground run and logs `[skillforge] run forge_…: completed (patterns=N, passed=N)` to the task's run log.
+
+## Safety model
+
+Generated skills are **step pipelines over audited tools** — there is no arbitrary shell, no new code paths, no tool the registry doesn't already know:
+
+1. **No invention** — every step must name a registered tool; the static gate rejects unknown tools before anything executes.
+2. **No dangerous capabilities** — a candidate requiring `shell:execute`, `network:listen`, or `filesystem:write` is refused at the static gate.
+3. **Sandboxed replay** — code/shell-shaped steps run through `run_sandboxed` (clean env, process-tree kill, output truncation, timeout).
+4. **Manual by default** — `auto_adopt = false`: a passed candidate sits in the store until `nova forge adopt`. `auto_adopt = true` exists for hands-off setups, but the gauntlet still runs first.
+5. **Reversible** — `nova forge revert <name>` deletes the skill directory instantly. Adopted skills are plain files in `generated/`.
+
+## Config reference
+
+```toml
+[learning.skillforge]
+enabled = false              # master switch
+auto_trigger = false         # forge automatically when patterns accrue
+auto_adopt = false           # install passing skills without `nova forge adopt`
+min_pattern_count = 3        # same tool-sequence must appear this often
+min_feedback = 0.7           # average trace feedback required to mine a pattern
+max_candidates_per_run = 3   # cap on skills synthesized per run
+sandbox_timeout = 30.0       # seconds per sandboxed replay step
+judge_model = ""             # "" uses intelligence.default_model
+```
+
+## Artifacts
+
+| Path | Contents |
+|------|----------|
+| `~/.nova_ai/learning/skillforge/runs.db` | Run + candidate history (`nova forge list`) |
+| `~/.nova_ai/learning/skillforge/last_run.log` | Background run output |
+| `~/.nova_ai/skills/generated/<name>/skill.toml` | Adopted skills (auto-discovered) |
+
+## CLI reference
+
+| Command | What it does |
+|---------|-------------|
+| `nova forge run [--foreground]` | Mine patterns and forge candidates |
+| `nova forge status` | Latest run + gate-by-gate gauntlet report |
+| `nova forge list [-n N]` | Candidate history |
+| `nova forge adopt RUN_ID` | Install a passed candidate |
+| `nova forge reject RUN_ID` | Mark a candidate rejected |
+| `nova forge revert SKILL_NAME` | Uninstall an adopted skill |
+
+## See also
+
+- [Model Proving Ground](proving-ground.md) — the same gauntlet discipline, applied to models instead of skills.
+- [Memory Consolidation](memory-consolidation.md) — the other consumer of your trace history.
+- [Fleet Oracle](fleet-oracle.md) — pool anonymized performance data so others can learn from your hardware, too.

{nova_ai_pro-1.2.3.dev78 → nova_ai_pro-1.2.3.dev85}/docs/user-guide/cli.md

@@ -586,3 +586,25 @@ Remove a query class from the adoption map (rollback).
 ### `nova prove watch [--prove]`
 
 Check for newly pulled models; with `--prove`, run the gauntlet for each.
+
+---
+
+## `nova oracle`
+
+The Fleet Oracle: opt-in anonymized performance reports pooled via a git dataset, queried locally. See [Fleet Oracle](../learning/fleet-oracle.md) for the privacy model (a fixed field list — nothing else ever leaves the machine).
+
+### `nova oracle export [-o PATH]`
+
+Build the anonymized report from local telemetry and preview it (or write it to a file). This is the exact payload sharing would publish.
+
+### `nova oracle push`
+
+Push the report to `learning.fleet.dataset_repo`. Refuses unless `learning.fleet.share_reports = true` (default off).
+
+### `nova oracle ask "QUESTION"`
+
+Answer from the pooled dataset locally, e.g. `nova oracle ask "best 8B model for code on a 4090?"` — keyword-bucketed, no LLM, table shows the machines behind the answer.
+
+### `nova oracle status`
+
+Fleet config, sharing state, and the local dataset copy size.

{nova_ai_pro-1.2.3.dev78 → nova_ai_pro-1.2.3.dev85}/docs/user-guide/memory.md

@@ -324,6 +324,26 @@ Use it to inform your response, citing sources where applicable:
 
 ---
 
+## Core Memory (distilled facts)
+
+Beyond raw document retrieval, NOVA can consolidate your conversations into a compact **core memory** — a short list of durable facts ("prefers dark mode", "deploys on Fridays are forbidden") that is prepended to every query alongside retrieved context. This runs as a background "sleep cycle" and is off by default:
+
+```toml
+# ~/.nova_ai/config.toml
+[learning.consolidation]
+enabled = true
+```
+
+```bash
+nova memory consolidate run --foreground   # run one cycle now
+nova memory consolidate facts              # see what NOVA learned
+nova memory consolidate forget FACT_ID     # remove a wrong fact
+```
+
+See [Memory Consolidation](../learning/memory-consolidation.md) for the full pipeline (clustering, fact distillation, contradiction resolution, decay).
+
+---
+
 ## CLI Usage
 
 ```bash

{nova_ai_pro-1.2.3.dev78 → nova_ai_pro-1.2.3.dev85}/docs/user-guide/telemetry.md

@@ -421,3 +421,9 @@ TraceAnalyzer / TelemetryAggregator  -->  Learning System
 ```
 
 Both systems operate transparently -- no manual instrumentation is needed when using the CLI or SDK, as they automatically set up the event bus and telemetry store.
+
+---
+
+## Sharing aggregates: the Fleet Oracle
+
+The per-model aggregates shown here are also the input to the [Fleet Oracle](../learning/fleet-oracle.md): with `learning.fleet.share_reports = true`, `nova oracle push` publishes a fixed-field, k-anonymized summary (hardware shape + per-model latency/throughput/energy averages — never prompts, content, or paths) to a shared git dataset, and `nova oracle ask` answers "best model for my hardware?" from the pooled fleet data locally. Sharing is off by default.