omnius 1.0.807 → 1.0.808

package/README.md

@@ -133,6 +133,11 @@ the local discover → exact expansion → explicit web-tool workflow.
 
 ## Common Workflows
 
+For large PDF collections, Omnius retains originals in a durable scoped index
+and processes ordering, manipulation, summary and extraction in resumable steps.
+See the [PDF collections guide](docs/guides/pdf-collections.md) for coverage,
+source provenance, numeric checks and complete delivery of large results.
+
 ```bash
 omnius "inspect this repo and summarize the main entrypoints"
 omnius serve

package/dist/api/py-embed.js

@@ -294593,9 +294593,127 @@ init_vision();
 init_system_deps();
 init_vision();
 
+// packages/execution/dist/tools/pdf-corpus-archive.js
+init_process_async();
+
 // packages/execution/dist/tools/ocr-pdf.js
 init_process_async();
 
+// packages/execution/dist/tools/pdf-transform.js
+init_process_async();
+var BUFFER_BYTES = 128 * 1024;
+var MAX_RECORD_BYTES = 64 * 1024;
+
+// packages/execution/dist/tools/source-corpus.js
+var SEGMENT_CHARS = 64 * 1024;
+var RECORD_BYTES = 64 * 1024;
+var ACTIONS = /* @__PURE__ */ new Set(["ingest", "inventory", "search", "read", "begin", "process", "status"]);
+var SOURCE_CORPUS_TOOL_DEFINITION = {
+  name: "source_corpus",
+  aliases: ["pdf_corpus"],
+  description: "Acquire and process a scoped PDF corpus without a total document/page-count cap. ingest uses an immutable JSONL manifest, one {ref,sha256} per source, and returns a durable import ID; repeat it to resume bounded batches. Local directory acquisition requires an explicit host policy and resumes bounded traversal/hash/manifest work with ingest_id. It captures an observed, version-fenced filesystem selection, not an atomic live-tree snapshot, and excludes only this workspace's owned .omnius state tree. inventory/search are cursor-paged; read returns exact channel-labelled segments with character offsets. begin preserves the full processing request and selected source versions; process checkpoints complete native pages and resumes after cancellation/restart. Source bytes, full native text and bbox are archived before bounded views. Explicit filters.channel='ocr_text' schedules resumable CPU OCR; rendered pages, engine/language, full OCR text and TSV are preserved separately. For OCR summaries/extractions use corpus_work filters.channel='ocr_text', complete anchored work, export, and corpus_export_review before delivery; source_answer_review only accepts native facts. Native or OCR engine completion does not prove visual understanding, summaries or final delivery.",
+  parameters: { type: "object", properties: {
+    action: { type: "string", enum: [...ACTIONS] },
+    corpus_id: { type: "string" },
+    manifest: { type: "string", description: "Host-authorized JSONL file or alias; one {ref,sha256} record per PDF." },
+    manifest_sha256: { type: "string" },
+    directory: { type: "string", description: "Explicit local-admin directory enumeration only." },
+    ingest_id: { type: "string", description: "Resume directory acquisition or the immutable import without resupplying its directory/manifest. Use a new ID for a deliberately changed directory selection." },
+    source_budget: { type: "integer", minimum: 1, maximum: 64 },
+    operation_id: { type: "string" },
+    request: { type: "string", description: "Complete extraction processing request; not authority to replace the user's goal." },
+    page_budget: { type: "integer", minimum: 1, maximum: 64 },
+    page_size: { type: "integer", minimum: 1, maximum: 128 },
+    cursor: { type: "string" },
+    query: { type: "string" },
+    filters: { type: "object" },
+    direction: { type: "string", enum: ["asc", "desc"] },
+    page_id: { type: "string" },
+    ocr_language: { type: "string", description: "Explicit OCR operation language, e.g. eng or eng+deu. Immutable after begin; uses installed Tesseract languages." },
+    char_offset: { type: "integer", minimum: 0 },
+    max_chars: { type: "integer", minimum: 2, maximum: SEGMENT_CHARS }
+  }, required: ["action", "corpus_id"], additionalProperties: false }
+};
+
+// packages/execution/dist/tools/corpus-work.js
+var ACTIONS2 = ["begin", "next", "read", "commit", "status", "complete", "cancel", "export", "aggregate", "order"];
+var CORPUS_WORK_TOOL_DEFINITION = {
+  name: "corpus_work",
+  aliases: ["pdf_corpus_work"],
+  description: "Durable model-driven summary or extraction over a scoped corpus. Native text is default; explicitly select filters.channel='ocr_text' for previously processed OCR evidence. begin preserves the FULL request and immutable selection. next gives bounded leased claims; read exposes each complete input through resumable exact character ranges. commit requires every input fully delivered through a successful host model request and exact quote anchors for every input. A read result prepares an exact range; same-response read+commit cannot establish model exposure. Full derived content is archived, never substituted for originals. Summary parents use host-issued bounded child membership and require complete child reads. Repeat next until leaves and reduction finish. Processing coverage is actor-attested, not proof of factual correctness, visual understanding or final delivery. Optional anchored decimal/count records support exact deterministic aggregates; record selection remains actor-attested. Exact anchored typed fields support SQL ordering before pagination through order, after processing completes. Text uses explicit binary collation; decimal is exact, dates calendar, clocks require declared fixed/source offsets. Missing and multiple values require explicit policies; field meaning and selection remain actor-attested. export resumably streams all derived leaf records and the summary root to JSONL. Repeat the exact export while completeExport=false; partial work has no finished artifact. byte_budget bounds each call, not the final output. Public OCR results require corpus_export_review prepare/process/finalize on the returned retained artifactPath; source_answer_review does not ground OCR inline prose. There is no total corpus or output count cap.",
+  parameters: { type: "object", properties: {
+    action: { type: "string", enum: [...ACTIONS2] },
+    corpus_id: { type: "string" },
+    operation_id: { type: "string" },
+    mode: { type: "string", enum: ["summary", "extraction"] },
+    request: { type: "string" },
+    filters: { type: "object" },
+    query: { type: "string" },
+    direction: { type: "string", enum: ["asc", "desc"] },
+    fan_in: { type: "integer", minimum: 2, maximum: 64, description: "Per-parent child allocation, not total corpus limit." },
+    byte_budget: { type: "integer", minimum: 1, maximum: 67108864, description: "Per-call export write/fixity byte budget; repeat export to finish arbitrarily large output." },
+    page_size: { type: "integer", minimum: 1, maximum: 32 },
+    claim_id: { type: "string" },
+    input_id: { type: "string" },
+    char_offset: { type: "integer", minimum: 0 },
+    max_chars: { type: "integer", minimum: 2, maximum: 65536 },
+    content: { type: "string", description: "Complete nonempty model-derived output for this claim." },
+    anchors: { type: "array", minItems: 1, items: { type: "object", properties: {
+      input_id: { type: "string" },
+      char_start: { type: "integer", minimum: 0 },
+      char_end: { type: "integer", minimum: 0 },
+      quote: { type: "string" }
+    }, required: ["input_id", "char_start", "char_end", "quote"], additionalProperties: false } },
+    fields: { type: "array", items: { type: "object", properties: {
+      field: { type: "string" },
+      kind: { type: "string", enum: ["text", "decimal", "date", "time", "datetime"] },
+      anchor: { type: "integer", minimum: 0 },
+      literal: { type: "string", description: "Entire exact literal in the indicated source anchor." },
+      timezone: { type: "string", description: "Dates: calendar. Clocks: source_offset when the literal has Z/offset; otherwise UTC or a fixed +/-HH:MM offset. No inferred timezone." }
+    }, required: ["field", "kind", "anchor", "literal"], additionalProperties: false } },
+    order_spec: { type: "object", properties: {
+      field: { type: "string" },
+      kind: { type: "string", enum: ["text", "decimal", "date", "time", "datetime"] },
+      unit: { type: "string", enum: ["source", "page"] },
+      direction: { type: "string", enum: ["asc", "desc"] },
+      missing: { type: "string", enum: ["first", "last", "exclude", "error"] },
+      multiple: { type: "string", enum: ["min", "max", "error"] },
+      collation: { type: "string", enum: ["binary"] },
+      timezone: { type: "string", enum: ["calendar", "recorded_offset"] },
+      timeSemantics: { type: "string", enum: ["utc_clock"] },
+      where: { type: "object", properties: { equals: { type: "string" }, from: { type: "string" }, through: { type: "string" } }, additionalProperties: false }
+    }, required: ["field", "kind", "unit", "direction", "missing", "multiple"], additionalProperties: false },
+    cursor: { type: "string" },
+    numbers: { type: "array", items: { type: "object", properties: {
+      field: { type: "string" },
+      kind: { type: "string", enum: ["decimal", "count"] },
+      anchor: { type: "integer", minimum: 0 },
+      literal: { type: "string" }
+    }, required: ["field", "kind", "anchor"], additionalProperties: false } },
+    field: { type: "string" }
+  }, required: ["action", "corpus_id", "operation_id"], additionalProperties: false }
+};
+
+// packages/execution/dist/tools/pdf-corpus-transform.js
+init_process_async();
+var LINE_BYTES = 64 * 1024;
+var ACTIONS3 = /* @__PURE__ */ new Set(["begin", "process", "status"]);
+var PDF_CORPUS_TRANSFORM_TOOL_DEFINITION = {
+  name: "pdf_corpus_transform",
+  aliases: ["pdf_corpus_compose"],
+  description: "Resumable original-page PDF merge, split and reorder over an acquired source_corpus. begin accepts an immutable JSONL recipe with one {sourceId,sourceSha256,page} per output page; order and repetitions are exact. process commits bounded partial PDFs and a durable merge tree; repeat the same operation_id after cancellation/update/restart. Source references must already belong to this host-scoped corpus. No text/OCR extraction is required for page copying. Returns a canonical PDF and streamed flattened original-page lineage with exact hashes; document metadata/forms/signatures are not preserved. No total PDF/page-count cap; each physical merge is atomic and may require a longer host work deadline for very large containers.",
+  parameters: { type: "object", properties: {
+    action: { type: "string", enum: [...ACTIONS3] },
+    corpus_id: { type: "string" },
+    operation_id: { type: "string" },
+    operation: { type: "string", enum: ["merge", "split", "reorder"] },
+    request: { type: "string", description: "Complete caller-declared transformation request; does not replace host goal authority." },
+    manifest: { type: "string" },
+    manifest_sha256: { type: "string" },
+    work_budget: { type: "integer", minimum: 1, maximum: 64, description: "Bounded recipe import or leaf/merge work units for this invocation." }
+  }, required: ["action", "corpus_id", "operation_id"], additionalProperties: false }
+};
+
 // packages/execution/dist/tools/pdf-visual-markdown.js
 var MAX_IMAGE_BYTES = 8 * 1024 * 1024;
 

package/dist/index.js

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/index.js
-size: 39849803 bytes
-sha256: 1e4dc06c6231b25e6176245614d6b3b3fe397fcc40fad72792c34bbd6b9ac772
+size: 41387219 bytes
+sha256: 2ab731ca98384df639ae734c17d520296d44e53de1f181b94719d3755b39acf1

package/dist/library.js

@@ -47751,6 +47751,20 @@ var init_immutableEvidenceStore = __esm({
   }
 });
 
+// packages/memory/dist/artifactReviewSourceIndex.js
+var init_artifactReviewSourceIndex = __esm({
+  "packages/memory/dist/artifactReviewSourceIndex.js"() {
+    "use strict";
+  }
+});
+
+// packages/memory/dist/sourceCorpusStore.js
+var init_sourceCorpusStore = __esm({
+  "packages/memory/dist/sourceCorpusStore.js"() {
+    "use strict";
+  }
+});
+
 // packages/memory/dist/structureAwareChunker.js
 var init_structureAwareChunker = __esm({
   "packages/memory/dist/structureAwareChunker.js"() {
@@ -49093,6 +49107,8 @@ var init_dist = __esm({
     init_db();
     init_contextMemoryLedger();
     init_immutableEvidenceStore();
+    init_artifactReviewSourceIndex();
+    init_sourceCorpusStore();
     init_structureAwareChunker();
     init_evidenceIngestion();
     init_structuredMemoryStore();
@@ -51865,10 +51881,19 @@ var init_vision_action_loop = __esm({
   }
 });
 
+// packages/execution/dist/tools/pdf-corpus-archive.js
+var init_pdf_corpus_archive = __esm({
+  "packages/execution/dist/tools/pdf-corpus-archive.js"() {
+    "use strict";
+    init_process_async();
+  }
+});
+
 // packages/execution/dist/tools/ocr-pdf.js
 var init_ocr_pdf = __esm({
   "packages/execution/dist/tools/ocr-pdf.js"() {
     "use strict";
+    init_pdf_corpus_archive();
     init_process_async();
     init_pdf_document();
   }
@@ -51882,6 +51907,243 @@ var init_pdf_to_text = __esm({
   }
 });
 
+// packages/execution/dist/tools/pdf-transform.js
+var BUFFER_BYTES, MAX_RECORD_BYTES;
+var init_pdf_transform = __esm({
+  "packages/execution/dist/tools/pdf-transform.js"() {
+    "use strict";
+    init_process_async();
+    BUFFER_BYTES = 128 * 1024;
+    MAX_RECORD_BYTES = 64 * 1024;
+  }
+});
+
+// packages/execution/dist/tools/source-corpus-ocr.js
+var init_source_corpus_ocr = __esm({
+  "packages/execution/dist/tools/source-corpus-ocr.js"() {
+    "use strict";
+    init_dist();
+    init_pdf_corpus_archive();
+  }
+});
+
+// packages/execution/dist/tools/corpus-directory-manifest.js
+var init_corpus_directory_manifest = __esm({
+  "packages/execution/dist/tools/corpus-directory-manifest.js"() {
+    "use strict";
+    init_pdf_corpus_archive();
+  }
+});
+
+// packages/execution/dist/tools/source-corpus.js
+var SEGMENT_CHARS, RECORD_BYTES, ACTIONS, SOURCE_CORPUS_TOOL_DEFINITION;
+var init_source_corpus = __esm({
+  "packages/execution/dist/tools/source-corpus.js"() {
+    "use strict";
+    init_dist();
+    init_pdf_corpus_archive();
+    init_source_corpus_ocr();
+    init_corpus_directory_manifest();
+    SEGMENT_CHARS = 64 * 1024;
+    RECORD_BYTES = 64 * 1024;
+    ACTIONS = /* @__PURE__ */ new Set(["ingest", "inventory", "search", "read", "begin", "process", "status"]);
+    SOURCE_CORPUS_TOOL_DEFINITION = {
+      name: "source_corpus",
+      aliases: ["pdf_corpus"],
+      description: "Acquire and process a scoped PDF corpus without a total document/page-count cap. ingest uses an immutable JSONL manifest, one {ref,sha256} per source, and returns a durable import ID; repeat it to resume bounded batches. Local directory acquisition requires an explicit host policy and resumes bounded traversal/hash/manifest work with ingest_id. It captures an observed, version-fenced filesystem selection, not an atomic live-tree snapshot, and excludes only this workspace's owned .omnius state tree. inventory/search are cursor-paged; read returns exact channel-labelled segments with character offsets. begin preserves the full processing request and selected source versions; process checkpoints complete native pages and resumes after cancellation/restart. Source bytes, full native text and bbox are archived before bounded views. Explicit filters.channel='ocr_text' schedules resumable CPU OCR; rendered pages, engine/language, full OCR text and TSV are preserved separately. For OCR summaries/extractions use corpus_work filters.channel='ocr_text', complete anchored work, export, and corpus_export_review before delivery; source_answer_review only accepts native facts. Native or OCR engine completion does not prove visual understanding, summaries or final delivery.",
+      parameters: { type: "object", properties: {
+        action: { type: "string", enum: [...ACTIONS] },
+        corpus_id: { type: "string" },
+        manifest: { type: "string", description: "Host-authorized JSONL file or alias; one {ref,sha256} record per PDF." },
+        manifest_sha256: { type: "string" },
+        directory: { type: "string", description: "Explicit local-admin directory enumeration only." },
+        ingest_id: { type: "string", description: "Resume directory acquisition or the immutable import without resupplying its directory/manifest. Use a new ID for a deliberately changed directory selection." },
+        source_budget: { type: "integer", minimum: 1, maximum: 64 },
+        operation_id: { type: "string" },
+        request: { type: "string", description: "Complete extraction processing request; not authority to replace the user's goal." },
+        page_budget: { type: "integer", minimum: 1, maximum: 64 },
+        page_size: { type: "integer", minimum: 1, maximum: 128 },
+        cursor: { type: "string" },
+        query: { type: "string" },
+        filters: { type: "object" },
+        direction: { type: "string", enum: ["asc", "desc"] },
+        page_id: { type: "string" },
+        ocr_language: { type: "string", description: "Explicit OCR operation language, e.g. eng or eng+deu. Immutable after begin; uses installed Tesseract languages." },
+        char_offset: { type: "integer", minimum: 0 },
+        max_chars: { type: "integer", minimum: 2, maximum: SEGMENT_CHARS }
+      }, required: ["action", "corpus_id"], additionalProperties: false }
+    };
+  }
+});
+
+// packages/execution/dist/tools/corpus-population.js
+var init_corpus_population = __esm({
+  "packages/execution/dist/tools/corpus-population.js"() {
+    "use strict";
+  }
+});
+
+// packages/execution/dist/tools/source-corpus-workspace.js
+var init_source_corpus_workspace = __esm({
+  "packages/execution/dist/tools/source-corpus-workspace.js"() {
+    "use strict";
+    init_dist();
+    init_source_corpus();
+    init_corpus_population();
+  }
+});
+
+// packages/execution/dist/tools/corpus-derived-order.js
+var init_corpus_derived_order = __esm({
+  "packages/execution/dist/tools/corpus-derived-order.js"() {
+    "use strict";
+  }
+});
+
+// packages/execution/dist/tools/corpus-work.js
+var ACTIONS2, CORPUS_WORK_TOOL_DEFINITION;
+var init_corpus_work = __esm({
+  "packages/execution/dist/tools/corpus-work.js"() {
+    "use strict";
+    init_dist();
+    init_pdf_corpus_archive();
+    init_corpus_derived_order();
+    ACTIONS2 = ["begin", "next", "read", "commit", "status", "complete", "cancel", "export", "aggregate", "order"];
+    CORPUS_WORK_TOOL_DEFINITION = {
+      name: "corpus_work",
+      aliases: ["pdf_corpus_work"],
+      description: "Durable model-driven summary or extraction over a scoped corpus. Native text is default; explicitly select filters.channel='ocr_text' for previously processed OCR evidence. begin preserves the FULL request and immutable selection. next gives bounded leased claims; read exposes each complete input through resumable exact character ranges. commit requires every input fully delivered through a successful host model request and exact quote anchors for every input. A read result prepares an exact range; same-response read+commit cannot establish model exposure. Full derived content is archived, never substituted for originals. Summary parents use host-issued bounded child membership and require complete child reads. Repeat next until leaves and reduction finish. Processing coverage is actor-attested, not proof of factual correctness, visual understanding or final delivery. Optional anchored decimal/count records support exact deterministic aggregates; record selection remains actor-attested. Exact anchored typed fields support SQL ordering before pagination through order, after processing completes. Text uses explicit binary collation; decimal is exact, dates calendar, clocks require declared fixed/source offsets. Missing and multiple values require explicit policies; field meaning and selection remain actor-attested. export resumably streams all derived leaf records and the summary root to JSONL. Repeat the exact export while completeExport=false; partial work has no finished artifact. byte_budget bounds each call, not the final output. Public OCR results require corpus_export_review prepare/process/finalize on the returned retained artifactPath; source_answer_review does not ground OCR inline prose. There is no total corpus or output count cap.",
+      parameters: { type: "object", properties: {
+        action: { type: "string", enum: [...ACTIONS2] },
+        corpus_id: { type: "string" },
+        operation_id: { type: "string" },
+        mode: { type: "string", enum: ["summary", "extraction"] },
+        request: { type: "string" },
+        filters: { type: "object" },
+        query: { type: "string" },
+        direction: { type: "string", enum: ["asc", "desc"] },
+        fan_in: { type: "integer", minimum: 2, maximum: 64, description: "Per-parent child allocation, not total corpus limit." },
+        byte_budget: { type: "integer", minimum: 1, maximum: 67108864, description: "Per-call export write/fixity byte budget; repeat export to finish arbitrarily large output." },
+        page_size: { type: "integer", minimum: 1, maximum: 32 },
+        claim_id: { type: "string" },
+        input_id: { type: "string" },
+        char_offset: { type: "integer", minimum: 0 },
+        max_chars: { type: "integer", minimum: 2, maximum: 65536 },
+        content: { type: "string", description: "Complete nonempty model-derived output for this claim." },
+        anchors: { type: "array", minItems: 1, items: { type: "object", properties: {
+          input_id: { type: "string" },
+          char_start: { type: "integer", minimum: 0 },
+          char_end: { type: "integer", minimum: 0 },
+          quote: { type: "string" }
+        }, required: ["input_id", "char_start", "char_end", "quote"], additionalProperties: false } },
+        fields: { type: "array", items: { type: "object", properties: {
+          field: { type: "string" },
+          kind: { type: "string", enum: ["text", "decimal", "date", "time", "datetime"] },
+          anchor: { type: "integer", minimum: 0 },
+          literal: { type: "string", description: "Entire exact literal in the indicated source anchor." },
+          timezone: { type: "string", description: "Dates: calendar. Clocks: source_offset when the literal has Z/offset; otherwise UTC or a fixed +/-HH:MM offset. No inferred timezone." }
+        }, required: ["field", "kind", "anchor", "literal"], additionalProperties: false } },
+        order_spec: { type: "object", properties: {
+          field: { type: "string" },
+          kind: { type: "string", enum: ["text", "decimal", "date", "time", "datetime"] },
+          unit: { type: "string", enum: ["source", "page"] },
+          direction: { type: "string", enum: ["asc", "desc"] },
+          missing: { type: "string", enum: ["first", "last", "exclude", "error"] },
+          multiple: { type: "string", enum: ["min", "max", "error"] },
+          collation: { type: "string", enum: ["binary"] },
+          timezone: { type: "string", enum: ["calendar", "recorded_offset"] },
+          timeSemantics: { type: "string", enum: ["utc_clock"] },
+          where: { type: "object", properties: { equals: { type: "string" }, from: { type: "string" }, through: { type: "string" } }, additionalProperties: false }
+        }, required: ["field", "kind", "unit", "direction", "missing", "multiple"], additionalProperties: false },
+        cursor: { type: "string" },
+        numbers: { type: "array", items: { type: "object", properties: {
+          field: { type: "string" },
+          kind: { type: "string", enum: ["decimal", "count"] },
+          anchor: { type: "integer", minimum: 0 },
+          literal: { type: "string" }
+        }, required: ["field", "kind", "anchor"], additionalProperties: false } },
+        field: { type: "string" }
+      }, required: ["action", "corpus_id", "operation_id"], additionalProperties: false }
+    };
+  }
+});
+
+// packages/execution/dist/tools/corpus-work-workspace.js
+var init_corpus_work_workspace = __esm({
+  "packages/execution/dist/tools/corpus-work-workspace.js"() {
+    "use strict";
+    init_corpus_work();
+    init_source_corpus();
+    init_source_corpus_workspace();
+  }
+});
+
+// packages/execution/dist/tools/corpus-host-input.js
+var init_corpus_host_input = __esm({
+  "packages/execution/dist/tools/corpus-host-input.js"() {
+    "use strict";
+    init_pdf_corpus_archive();
+  }
+});
+
+// packages/execution/dist/tools/pdf-corpus-transform.js
+var LINE_BYTES, ACTIONS3, PDF_CORPUS_TRANSFORM_TOOL_DEFINITION;
+var init_pdf_corpus_transform = __esm({
+  "packages/execution/dist/tools/pdf-corpus-transform.js"() {
+    "use strict";
+    init_process_async();
+    init_pdf_corpus_archive();
+    init_pdf_transform();
+    LINE_BYTES = 64 * 1024;
+    ACTIONS3 = /* @__PURE__ */ new Set(["begin", "process", "status"]);
+    PDF_CORPUS_TRANSFORM_TOOL_DEFINITION = {
+      name: "pdf_corpus_transform",
+      aliases: ["pdf_corpus_compose"],
+      description: "Resumable original-page PDF merge, split and reorder over an acquired source_corpus. begin accepts an immutable JSONL recipe with one {sourceId,sourceSha256,page} per output page; order and repetitions are exact. process commits bounded partial PDFs and a durable merge tree; repeat the same operation_id after cancellation/update/restart. Source references must already belong to this host-scoped corpus. No text/OCR extraction is required for page copying. Returns a canonical PDF and streamed flattened original-page lineage with exact hashes; document metadata/forms/signatures are not preserved. No total PDF/page-count cap; each physical merge is atomic and may require a longer host work deadline for very large containers.",
+      parameters: { type: "object", properties: {
+        action: { type: "string", enum: [...ACTIONS3] },
+        corpus_id: { type: "string" },
+        operation_id: { type: "string" },
+        operation: { type: "string", enum: ["merge", "split", "reorder"] },
+        request: { type: "string", description: "Complete caller-declared transformation request; does not replace host goal authority." },
+        manifest: { type: "string" },
+        manifest_sha256: { type: "string" },
+        work_budget: { type: "integer", minimum: 1, maximum: 64, description: "Bounded recipe import or leaf/merge work units for this invocation." }
+      }, required: ["action", "corpus_id", "operation_id"], additionalProperties: false }
+    };
+  }
+});
+
+// packages/execution/dist/tools/pdf-corpus-recipe.js
+var init_pdf_corpus_recipe = __esm({
+  "packages/execution/dist/tools/pdf-corpus-recipe.js"() {
+    "use strict";
+    init_corpus_derived_order();
+    init_pdf_corpus_archive();
+  }
+});
+
+// packages/execution/dist/tools/pdf-corpus-transform-workspace.js
+var init_pdf_corpus_transform_workspace = __esm({
+  "packages/execution/dist/tools/pdf-corpus-transform-workspace.js"() {
+    "use strict";
+    init_corpus_work();
+    init_pdf_corpus_transform();
+    init_pdf_corpus_recipe();
+    init_source_corpus_workspace();
+  }
+});
+
+// packages/execution/dist/tools/pdf-corpus-recipe-workspace.js
+var init_pdf_corpus_recipe_workspace = __esm({
+  "packages/execution/dist/tools/pdf-corpus-recipe-workspace.js"() {
+    "use strict";
+    init_corpus_work();
+    init_pdf_corpus_recipe();
+    init_source_corpus_workspace();
+  }
+});
+
 // packages/execution/dist/tools/pdf-visual-markdown.js
 var MAX_IMAGE_BYTES;
 var init_pdf_visual_markdown = __esm({
@@ -297303,6 +297565,18 @@ var init_dist3 = __esm({
     init_vision_action_loop();
     init_ocr_pdf();
     init_pdf_to_text();
+    init_pdf_corpus_archive();
+    init_pdf_transform();
+    init_source_corpus();
+    init_source_corpus_workspace();
+    init_corpus_work();
+    init_corpus_work_workspace();
+    init_corpus_population();
+    init_corpus_host_input();
+    init_pdf_corpus_transform();
+    init_pdf_corpus_transform_workspace();
+    init_pdf_corpus_recipe();
+    init_pdf_corpus_recipe_workspace();
     init_pdf_native_tables();
     init_pdf_visual_markdown();
     init_pdf_document();
@@ -297390,6 +297664,8 @@ var init_dist3 = __esm({
     init_transcribe_python_runtime();
     init_verificationCommand();
     init_verificationInvocation();
+    init_corpus_derived_order();
+    init_ocr_pdf();
   }
 });
 
@@ -301202,6 +301478,12 @@ init_dist();
 // packages/orchestrator/dist/contextSNR.js
 init_dist();
 
+// packages/orchestrator/dist/corpus-native-source-proof-memo.js
+init_dist();
+
+// packages/orchestrator/dist/corpus-page-review-source.js
+init_dist();
+
 // packages/orchestrator/dist/contextEngine.js
 init_dist();
 

package/dist/update-worker.js

@@ -295027,9 +295027,127 @@ init_vision();
 init_system_deps();
 init_vision();
 
+// packages/execution/dist/tools/pdf-corpus-archive.js
+init_process_async();
+
 // packages/execution/dist/tools/ocr-pdf.js
 init_process_async();
 
+// packages/execution/dist/tools/pdf-transform.js
+init_process_async();
+var BUFFER_BYTES = 128 * 1024;
+var MAX_RECORD_BYTES = 64 * 1024;
+
+// packages/execution/dist/tools/source-corpus.js
+var SEGMENT_CHARS = 64 * 1024;
+var RECORD_BYTES = 64 * 1024;
+var ACTIONS = /* @__PURE__ */ new Set(["ingest", "inventory", "search", "read", "begin", "process", "status"]);
+var SOURCE_CORPUS_TOOL_DEFINITION = {
+  name: "source_corpus",
+  aliases: ["pdf_corpus"],
+  description: "Acquire and process a scoped PDF corpus without a total document/page-count cap. ingest uses an immutable JSONL manifest, one {ref,sha256} per source, and returns a durable import ID; repeat it to resume bounded batches. Local directory acquisition requires an explicit host policy and resumes bounded traversal/hash/manifest work with ingest_id. It captures an observed, version-fenced filesystem selection, not an atomic live-tree snapshot, and excludes only this workspace's owned .omnius state tree. inventory/search are cursor-paged; read returns exact channel-labelled segments with character offsets. begin preserves the full processing request and selected source versions; process checkpoints complete native pages and resumes after cancellation/restart. Source bytes, full native text and bbox are archived before bounded views. Explicit filters.channel='ocr_text' schedules resumable CPU OCR; rendered pages, engine/language, full OCR text and TSV are preserved separately. For OCR summaries/extractions use corpus_work filters.channel='ocr_text', complete anchored work, export, and corpus_export_review before delivery; source_answer_review only accepts native facts. Native or OCR engine completion does not prove visual understanding, summaries or final delivery.",
+  parameters: { type: "object", properties: {
+    action: { type: "string", enum: [...ACTIONS] },
+    corpus_id: { type: "string" },
+    manifest: { type: "string", description: "Host-authorized JSONL file or alias; one {ref,sha256} record per PDF." },
+    manifest_sha256: { type: "string" },
+    directory: { type: "string", description: "Explicit local-admin directory enumeration only." },
+    ingest_id: { type: "string", description: "Resume directory acquisition or the immutable import without resupplying its directory/manifest. Use a new ID for a deliberately changed directory selection." },
+    source_budget: { type: "integer", minimum: 1, maximum: 64 },
+    operation_id: { type: "string" },
+    request: { type: "string", description: "Complete extraction processing request; not authority to replace the user's goal." },
+    page_budget: { type: "integer", minimum: 1, maximum: 64 },
+    page_size: { type: "integer", minimum: 1, maximum: 128 },
+    cursor: { type: "string" },
+    query: { type: "string" },
+    filters: { type: "object" },
+    direction: { type: "string", enum: ["asc", "desc"] },
+    page_id: { type: "string" },
+    ocr_language: { type: "string", description: "Explicit OCR operation language, e.g. eng or eng+deu. Immutable after begin; uses installed Tesseract languages." },
+    char_offset: { type: "integer", minimum: 0 },
+    max_chars: { type: "integer", minimum: 2, maximum: SEGMENT_CHARS }
+  }, required: ["action", "corpus_id"], additionalProperties: false }
+};
+
+// packages/execution/dist/tools/corpus-work.js
+var ACTIONS2 = ["begin", "next", "read", "commit", "status", "complete", "cancel", "export", "aggregate", "order"];
+var CORPUS_WORK_TOOL_DEFINITION = {
+  name: "corpus_work",
+  aliases: ["pdf_corpus_work"],
+  description: "Durable model-driven summary or extraction over a scoped corpus. Native text is default; explicitly select filters.channel='ocr_text' for previously processed OCR evidence. begin preserves the FULL request and immutable selection. next gives bounded leased claims; read exposes each complete input through resumable exact character ranges. commit requires every input fully delivered through a successful host model request and exact quote anchors for every input. A read result prepares an exact range; same-response read+commit cannot establish model exposure. Full derived content is archived, never substituted for originals. Summary parents use host-issued bounded child membership and require complete child reads. Repeat next until leaves and reduction finish. Processing coverage is actor-attested, not proof of factual correctness, visual understanding or final delivery. Optional anchored decimal/count records support exact deterministic aggregates; record selection remains actor-attested. Exact anchored typed fields support SQL ordering before pagination through order, after processing completes. Text uses explicit binary collation; decimal is exact, dates calendar, clocks require declared fixed/source offsets. Missing and multiple values require explicit policies; field meaning and selection remain actor-attested. export resumably streams all derived leaf records and the summary root to JSONL. Repeat the exact export while completeExport=false; partial work has no finished artifact. byte_budget bounds each call, not the final output. Public OCR results require corpus_export_review prepare/process/finalize on the returned retained artifactPath; source_answer_review does not ground OCR inline prose. There is no total corpus or output count cap.",
+  parameters: { type: "object", properties: {
+    action: { type: "string", enum: [...ACTIONS2] },
+    corpus_id: { type: "string" },
+    operation_id: { type: "string" },
+    mode: { type: "string", enum: ["summary", "extraction"] },
+    request: { type: "string" },
+    filters: { type: "object" },
+    query: { type: "string" },
+    direction: { type: "string", enum: ["asc", "desc"] },
+    fan_in: { type: "integer", minimum: 2, maximum: 64, description: "Per-parent child allocation, not total corpus limit." },
+    byte_budget: { type: "integer", minimum: 1, maximum: 67108864, description: "Per-call export write/fixity byte budget; repeat export to finish arbitrarily large output." },
+    page_size: { type: "integer", minimum: 1, maximum: 32 },
+    claim_id: { type: "string" },
+    input_id: { type: "string" },
+    char_offset: { type: "integer", minimum: 0 },
+    max_chars: { type: "integer", minimum: 2, maximum: 65536 },
+    content: { type: "string", description: "Complete nonempty model-derived output for this claim." },
+    anchors: { type: "array", minItems: 1, items: { type: "object", properties: {
+      input_id: { type: "string" },
+      char_start: { type: "integer", minimum: 0 },
+      char_end: { type: "integer", minimum: 0 },
+      quote: { type: "string" }
+    }, required: ["input_id", "char_start", "char_end", "quote"], additionalProperties: false } },
+    fields: { type: "array", items: { type: "object", properties: {
+      field: { type: "string" },
+      kind: { type: "string", enum: ["text", "decimal", "date", "time", "datetime"] },
+      anchor: { type: "integer", minimum: 0 },
+      literal: { type: "string", description: "Entire exact literal in the indicated source anchor." },
+      timezone: { type: "string", description: "Dates: calendar. Clocks: source_offset when the literal has Z/offset; otherwise UTC or a fixed +/-HH:MM offset. No inferred timezone." }
+    }, required: ["field", "kind", "anchor", "literal"], additionalProperties: false } },
+    order_spec: { type: "object", properties: {
+      field: { type: "string" },
+      kind: { type: "string", enum: ["text", "decimal", "date", "time", "datetime"] },
+      unit: { type: "string", enum: ["source", "page"] },
+      direction: { type: "string", enum: ["asc", "desc"] },
+      missing: { type: "string", enum: ["first", "last", "exclude", "error"] },
+      multiple: { type: "string", enum: ["min", "max", "error"] },
+      collation: { type: "string", enum: ["binary"] },
+      timezone: { type: "string", enum: ["calendar", "recorded_offset"] },
+      timeSemantics: { type: "string", enum: ["utc_clock"] },
+      where: { type: "object", properties: { equals: { type: "string" }, from: { type: "string" }, through: { type: "string" } }, additionalProperties: false }
+    }, required: ["field", "kind", "unit", "direction", "missing", "multiple"], additionalProperties: false },
+    cursor: { type: "string" },
+    numbers: { type: "array", items: { type: "object", properties: {
+      field: { type: "string" },
+      kind: { type: "string", enum: ["decimal", "count"] },
+      anchor: { type: "integer", minimum: 0 },
+      literal: { type: "string" }
+    }, required: ["field", "kind", "anchor"], additionalProperties: false } },
+    field: { type: "string" }
+  }, required: ["action", "corpus_id", "operation_id"], additionalProperties: false }
+};
+
+// packages/execution/dist/tools/pdf-corpus-transform.js
+init_process_async();
+var LINE_BYTES = 64 * 1024;
+var ACTIONS3 = /* @__PURE__ */ new Set(["begin", "process", "status"]);
+var PDF_CORPUS_TRANSFORM_TOOL_DEFINITION = {
+  name: "pdf_corpus_transform",
+  aliases: ["pdf_corpus_compose"],
+  description: "Resumable original-page PDF merge, split and reorder over an acquired source_corpus. begin accepts an immutable JSONL recipe with one {sourceId,sourceSha256,page} per output page; order and repetitions are exact. process commits bounded partial PDFs and a durable merge tree; repeat the same operation_id after cancellation/update/restart. Source references must already belong to this host-scoped corpus. No text/OCR extraction is required for page copying. Returns a canonical PDF and streamed flattened original-page lineage with exact hashes; document metadata/forms/signatures are not preserved. No total PDF/page-count cap; each physical merge is atomic and may require a longer host work deadline for very large containers.",
+  parameters: { type: "object", properties: {
+    action: { type: "string", enum: [...ACTIONS3] },
+    corpus_id: { type: "string" },
+    operation_id: { type: "string" },
+    operation: { type: "string", enum: ["merge", "split", "reorder"] },
+    request: { type: "string", description: "Complete caller-declared transformation request; does not replace host goal authority." },
+    manifest: { type: "string" },
+    manifest_sha256: { type: "string" },
+    work_budget: { type: "integer", minimum: 1, maximum: 64, description: "Bounded recipe import or leaf/merge work units for this invocation." }
+  }, required: ["action", "corpus_id", "operation_id"], additionalProperties: false }
+};
+
 // packages/execution/dist/tools/pdf-visual-markdown.js
 var MAX_IMAGE_BYTES = 8 * 1024 * 1024;
 

package/docs/DISCOVERY.json

@@ -29211,6 +29211,37 @@
         }
       ]
     },
+    {
+      "id": "guide.corpus-ocr",
+      "kind": "guide",
+      "title": "Explicit scanned-PDF corpus OCR",
+      "summary": "The public sourcecorpus tool can process an acquired PDF population with begin using filters: {channel: \"ocrtext\"} and optional ocrlanguage (default eng). Repeated process calls resume a durable per-source page cursor. Installed CPU Poppler and Tesseract are required. The default channel remains nativetext; completing native extraction of an empty scanned pa",
+      "keywords": [
+        "corpus",
+        "ocr",
+        "md"
+      ],
+      "maturity": "stable",
+      "audiences": [
+        "user",
+        "integrator",
+        "coding-agent"
+      ],
+      "layer": "documentation",
+      "interfaces": [
+        {
+          "type": "file",
+          "target": "docs/corpus-ocr.md"
+        }
+      ],
+      "references": [
+        {
+          "type": "documentation",
+          "target": "docs/corpus-ocr.md",
+          "relation": "canonical-artifact"
+        }
+      ]
+    },
     {
       "id": "guide.dedup-false-positive-meta-analysis",
       "kind": "guide",
@@ -29931,6 +29962,38 @@
         }
       ]
     },
+    {
+      "id": "guide.guides-pdf-collections",
+      "kind": "guide",
+      "title": "Large PDF collections",
+      "summary": "Ask Omnius to process the collection in ordinary language, specifying the result you need: search, ordering, original-page manipulation, summary, or extraction. For example: “Review every supplied PDF, extract each recorded duration with its source page, order the documents by the invoice date, and deliver the complete results.” A field's meaning, units, mis",
+      "keywords": [
+        "guides",
+        "pdf",
+        "collections",
+        "md"
+      ],
+      "maturity": "stable",
+      "audiences": [
+        "user",
+        "integrator",
+        "coding-agent"
+      ],
+      "layer": "documentation",
+      "interfaces": [
+        {
+          "type": "file",
+          "target": "docs/guides/pdf-collections.md"
+        }
+      ],
+      "references": [
+        {
+          "type": "documentation",
+          "target": "docs/guides/pdf-collections.md",
+          "relation": "canonical-artifact"
+        }
+      ]
+    },
     {
       "id": "guide.guides-realtime",
       "kind": "guide",
@@ -45026,6 +45089,62 @@
         }
       ]
     },
+    {
+      "id": "tool.pdf-transform",
+      "kind": "tool",
+      "title": "Pdf Transform",
+      "summary": "pdf_transform is a directly callable Omnius tool.",
+      "aliases": [
+        "pdf_transform"
+      ],
+      "keywords": [
+        "tool",
+        "pdf",
+        "transform"
+      ],
+      "maturity": "stable",
+      "layer": "execution",
+      "audiences": [
+        "coding-agent",
+        "integrator",
+        "service-agent"
+      ],
+      "use_when": [
+        "The caller needs this isolated operation and live metadata confirms direct-call availability"
+      ],
+      "avoid_when": [
+        "The live registry reports the tool unavailable or the caller lacks its required scope"
+      ],
+      "interfaces": [
+        {
+          "type": "rest-schema",
+          "target": "/v1/tools/pdf_transform"
+        },
+        {
+          "type": "rest-call",
+          "target": "/v1/tools/pdf_transform/call"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/execution/src/tools/pdf-transform.ts",
+          "relation": "implementation"
+        }
+      ],
+      "direct_callable": true,
+      "live_metadata": "GET /v1/tools/pdf_transform",
+      "source_of_truth": [
+        "packages/execution/src/tools/pdf-transform.ts",
+        "GET /v1/tools/pdf_transform"
+      ],
+      "verification": [
+        {
+          "check": "Inspect GET /v1/tools/pdf_transform before use",
+          "expected": "Schema, security, exposure, and availability match the intended invocation"
+        }
+      ]
+    },
     {
       "id": "tool.pdf-visual-markdown",
       "kind": "tool",

package/docs/DISCOVERY.md

@@ -420,6 +420,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `guide.asd-ste100-communication-audit-uppercase` | ASD-STE100 Communication Audit | Use ASD-STE100 Issue 9 for all Omnius natural-language communication. Apply the rule to external replies and internal agent messages. Preserve exact machine content without a change. |
 | `guide.concept-relational-language` | Concept Relational Language (CRL) — Token-Efficient Concept Communication | &gt; Experimental hyper-compressed symbolic notation for mind-mapped logical flow tracking |
 | `guide.context-management-medium-models-proposal` | Context Management for Medium Models (30-40B) — Implementation Proposal | Date: 2026-04-25 Problem: Medium-tier models (~35B params) exhibit excessive repetition at ~35% context fill despite 256K context windows Root Cause: Monolithic context structure + attention degradation + tool schema bloat |
+| `guide.corpus-ocr` | Explicit scanned-PDF corpus OCR | The public sourcecorpus tool can process an acquired PDF population with begin using filters: {channel: "ocrtext"} and optional ocrlanguage (default eng). Repeated process calls resume a durable per-source page cursor. Installed CPU Poppler and Tesseract are required. The default channel remains nativetext; completing native extraction of an empty scanned pa |
 | `guide.dedup-false-positive-meta-analysis` | Meta-Analysis: False Positive Duplicate Tool Call Detection | Date: 2026-05-14 Scope: packages/orchestrator/src/agenticRunner.ts — proactivePrune() + buildResourceKey() |
 | `guide.discovery-agent-map` | Agent Map | Bundled Omnius documentation artifact: docs/discovery/agent-map.json. |
 | `guide.discovery-catalog-overrides` | Discovery Catalog Curated Source | Curated aliases, relationships, invocation modes, and conceptual entries merged into the generated catalog. |
@@ -442,6 +443,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `guide.guides-long-horizon-feature-workflow` | Long-horizon feature work | Implementation, acceptance cases and delivery records are tracked in WO-01. |
 | `guide.guides-media-generation` | Media Generation | Omnius exposes media generation through TUI commands, tools, Telegram creative workflows, and sponsor media endpoints. |
 | `guide.guides-osint-research` | Categorized OSINT research | Omnius ships a local, searchable snapshot of the OSINT4ALL Start.me page. It uses the same compact discovery pattern as AIWG skills: |
+| `guide.guides-pdf-collections` | Large PDF collections | Ask Omnius to process the collection in ordinary language, specifying the result you need: search, ordering, original-page manipulation, summary, or extraction. For example: “Review every supplied PDF, extract each recorded duration with its source page, order the documents by the invoice date, and deliver the complete results.” A field's meaning, units, mis |
 | `guide.guides-realtime` | Realtime Conversations | Realtime mode is for short, natural, back-and-forth spoken conversation behind ASR and TTS. |
 | `guide.guides-sponsor-and-cohere` | Sponsor And COHERE Mesh | Sponsor and COHERE let Omnius share inference capacity across peers. Sponsor mode is explicit provider/consumer sharing. COHERE is a distributed cognitive inference mesh. |
 | `guide.guides-system-tray` | System Tray Indicator | Omnius ships a native per-login tray indicator for Linux, macOS, and Windows on x64 hosts. It is separate from the REST daemon: closing the indicator never stops the daemon, and the daemon remains usable in headless sessions. |
@@ -830,6 +832,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `tool.osint-search` | OSINT Search | Search the bundled OSINT4ALL snapshot locally and return a bounded ranked shortlist with category, archived-health, interaction, and risk metadata; no cataloged service is contacted. |
 | `tool.osint-show` | OSINT Show | Expand one exact local OSINT resource ID into its URL, aliases, original category placements, archived health, and safe next-tool route; no cataloged service is contacted. |
 | `tool.pdf-to-text` | Pdf To Text | pdf_to_text is a directly callable Omnius tool. |
+| `tool.pdf-transform` | Pdf Transform | pdf_transform is a directly callable Omnius tool. |
 | `tool.pdf-visual-markdown` | Pdf Visual Markdown | pdf_visual_markdown is a directly callable Omnius tool. |
 | `tool.phase-recall` | Phase Recall | phase_recall is a directly callable Omnius tool. |
 | `tool.play-sound` | Play Sound | play_sound is a directly callable Omnius tool. |

package/docs/corpus-ocr.md

@@ -0,0 +1,57 @@
+# Explicit scanned-PDF corpus OCR
+
+The public `source_corpus` tool can process an acquired PDF population with
+`begin` using `filters: {channel: "ocr_text"}` and optional `ocr_language`
+(default `eng`). Repeated `process` calls resume a durable per-source page
+cursor. Installed CPU Poppler and Tesseract are required. The default channel
+remains `native_text`; completing native extraction of an empty scanned page
+does not complete its OCR extraction.
+
+Each OCR page retains the original PDF identity, rendered PNG, full Tesseract
+text and TSV geometry in durable content-addressed files, with exact hashes,
+page lineage, engine version and language. Immutable segmented evidence powers
+bounded search and read operations. OCR receipts preserve the original issuing
+owner; subsequent reads bind their exact exposed range to the current owner.
+OCR TSV geometry is separate from native PDF geometry.
+
+`corpus_work` can explicitly select the complete `ocr_text` population for
+anchored extraction or summary. A read checkpoint is prepared when text is
+returned, then confirmed only after the production runner successfully sends
+the exact protected OCR text carrier to its configured backend. Failed
+transport cannot confirm that read or authorize a derived commit. Derived
+content remains `actor_attested`, requiring independent factual review.
+
+OCR completion means the engine processed every selected page. It does not
+prove transcription accuracy or visual comprehension: `visualCoverage`
+remains `not_assessed`, and OCR does not receive native evidence authority.
+Complete OCR-derived text exports can pass the separate export reviewer after
+it reopens every original PDF, rendered page, OCR text, TSV and immutable
+source/producer/exposure record. Fresh bounded factual review sees explicit
+`ocr_text` transcription provenance and the unassessed visual limitation.
+The complete source and output unions remain required before retention and
+provider delivery. Exact numeric source-line transcription can be verified
+against OCR engine output; this does not verify that output against the image.
+
+Native table-cell, count, sum and aggregate quantity gates remain strict: OCR
+text and TSV do not confer native field or arithmetic authority. OCR-derived
+arithmetic needs a separately reviewed transcription/operand population before
+approval; matching digits or a prose verdict cannot provide it. The inline
+Telegram source-answer review path still has no OCR-specific source-index
+adapter; the verified delivery route here is the full derived text export.
+Both OCR-only and mixed native/OCR factual inline candidates are refused after
+an actual successful OCR model handoff. The barrier is durable for the admitted
+session/run/epoch; ingestion, metadata and failed transport do not create it.
+The refusal preserves existing OCR evidence and gives the exact work/export/
+review steps instead of requesting another native-empty read.
+
+After fresh `corpus_export_review` completes under the current request, use
+`task_complete` with `deliver_artifacts: true` and the exact neutral notice
+`The reviewed OCR results are attached.` The host reopens the complete export,
+its original OCR source proof and current signed semantic receipt. Completion
+still requires actual provider acknowledgement for every selected output.
+That file review does not approve unrelated inline factual prose, and the
+neutral notice alone cannot waive missing review or delivery receipts.
+
+Population traversal and page work are resumable and have no total source or
+page count ceiling. A single-page rasterization still needs physical CPU/RAM
+resources; this implementation does not tile unusually large page images.

package/docs/guides/pdf-collections.md

@@ -0,0 +1,76 @@
+# Large PDF collections
+
+Ask Omnius to process the collection in ordinary language, specifying the result
+you need: search, ordering, original-page manipulation, summary, or extraction.
+For example: “Review every supplied PDF, extract each recorded duration with its
+source page, order the documents by the invoice date, and deliver the complete
+results.” A field's meaning, units, missing-value handling, and ordering direction
+remain part of the request; a date appearing somewhere in a PDF does not by
+itself establish that it is the requested invoice date.
+
+The collection is stored outside the model context. Original PDFs, complete
+native page text, page geometry, immutable source identities and hashes remain
+available in the private source archive. SQL applies scope, version and request
+filters before sorting and paging. Retrieval can reopen exact source ranges;
+condensing a model prompt never replaces the original evidence.
+
+Search uses cursor-paged lexical matches in the authorized collection. A search
+result, including a result with no matches, does not establish that every source
+was extracted or reviewed. Exhaustive requests retain the complete selected
+population and track source coverage separately from relevance ranking.
+
+There is no application limit on the total number of PDFs, pages, selected
+records, or output files. Per-call work widths keep memory and prompts finite;
+the model's actual context window, available storage, compute and each provider's
+per-file upload limit still apply. Processing the entire collection takes work
+proportional to that collection. Targeted search and exhaustive extraction use
+different coverage requirements.
+
+| Task | Runtime tools and retained result |
+| --- | --- |
+| Ingest and search | `source_corpus` retains originals, indexes native pages, and returns scoped inventories and exact ranges. Telegram's `manifest="current_task"` selects the host-admitted attachment population. |
+| Scanned pages | Explicit `source_corpus` OCR work retains page images, full engine text, word positions and engine receipts in the separate `ocr_text` channel. Interrupted page work resumes without replacing native text. |
+| Summary and extraction | `corpus_work` preserves the complete request and selection, issues bounded input claims, records ranges that actually reached a successful model request, and commits derived records with source anchors. |
+| Field ordering | `corpus_work` stores source-anchored typed fields and orders through SQL. Exact decimal and date handling, ties, missing values and multiple values have explicit policies. Model-selected field meaning remains subject to source review. |
+| Original-page manipulation | `pdf_corpus_recipe` and `pdf_corpus_transform` plan and execute original-page ordering, merge and split operations without reconstructing PDFs from summaries. |
+| Factual acceptance | `source_answer_review` and `corpus_export_review` independently review complete selected output and source coverage. Numeric aggregates reopen every selected native input and verify exact operands and arithmetic. |
+| Large result delivery | `corpus_export_review` partition actions retain upload-sized data and reconstruction files. `partition_finalize` inherits a complete current parent review and verifies every child; actual provider receipts still establish delivery. |
+
+Processing and delivery checkpoints survive restart. Committed work and accepted
+uploads are reused under the current task; stale owner or request authority must
+be renewed. A Telegram upload quota wait retains the exact reviewed candidate
+and resumes at the provider retry time. Completion requires receipts for every
+selected output, including all reconstruction files. An extracted index, a model
+claim of completion, or an intermediate progress message does not establish that
+the final answer was delivered.
+
+Directory acquisition preserves enumeration, original-file acquisition and
+manifest-writing checkpoints. Restart verifies the previously observed directory
+and file identities before continuing; a changing directory cannot silently
+become a different collection. This is an observed, verified manifest, not an
+atomic filesystem snapshot. Export writing and fixity checks also resume within
+an individual JSONL record, so output size does not impose a total export cap.
+
+Verified durable work can continue beyond the default emergency turn budget.
+An explicit finite budget still applies. Repeating a call without advancing its
+current source-bound checkpoint earns no continuation credit; progress does not
+approve facts or fulfill the final-output and delivery requirements.
+
+After restart, the host reopens the current pending SQL job before applying its
+retry guard. An authentic job can receive one admission attempt at its existing
+producer clock, including an initialized job that has not advanced yet. Reopening
+the job creates no progress event. The consumed attempt survives restart and
+cannot be renewed by switching job IDs; actual verified work must advance the
+clock before another attempt becomes available.
+
+Native text and geometry can be incomplete or ambiguous. Unresolved extraction,
+field association or arithmetic stays explicit; visual review can resolve the
+relevant page on the configured capable backend. The research basis and
+stage-by-stage evaluation criteria are in the
+[PDF distillation synthesis](../../.aiwg/research/pdf-knowledge-distillation/synthesis.md).
+
+Numeric review distinguishes populated cells from recorded events. A nonempty
+cell can contain zero or an incomplete time placeholder; it does not necessarily
+record an event. Bounded examples expose exact distinct native spellings without
+frequencies or expected answers. The reviewer selects the meaning from the full
+request, and the host verifies arithmetic against the complete original field.

package/docs/guides/telegram.md

@@ -145,6 +145,12 @@ a lease, bounded backoff, and the returned Telegram message ID.
 | Audio | `audio_edit` | inspect, trim, concatenate, typed splice and silence, mix, normalize, fade, convert, resample | `audio_analyze` for sound/music or `transcribe_file` for speech |
 | PDF or DOCX | `document` | create from heading/paragraph/bullet/page-break blocks, inspect, hash-guarded revise | `document action='inspect'` on the exact output |
 
+Photo intake and `telegram_image_analyze` use the configured endpoint and model
+with the original image. The backend must declare image support. If that
+capability is unavailable, Omnius retains the image and reports it as unassessed.
+These paths do not automatically select another vision model. An uncaptioned
+photo retains its native media identity without inventing a caption or request.
+
 These tools do not accept shell commands, raw FFmpeg filters, ImageMagick
 expressions, raw PDF/OOXML bytes, HTML, macros, or paths outside the chat
 workspace. Image and audio edits never overwrite an artifact. Document

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "omnius",
-  "version": "1.0.807",
+  "version": "1.0.808",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.807",
+      "version": "1.0.808",
       "bundleDependencies": [
         "image-to-ascii"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnius",
-  "version": "1.0.807",
+  "version": "1.0.808",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/library.js",
@@ -168,5 +168,5 @@
     "viem": "2.47.4",
     "cli-highlight": "^2.1.11"
   },
-  "readme": "# Omnius\n\nOmnius is a local-first agentic coding runtime: terminal UI, autonomous coding loop, REST daemon, model router, memory layer, media tools, Telegram bridge, and peer-to-peer inference mesh in one CLI.\n\nIt is designed for open-weight and user-controlled models first, while still routing cleanly through Ollama, vLLM, OpenAI-compatible endpoints, OpenRouter, Groq, Chutes, sponsor peers, COHERE peers, and other configured providers.\n\n[![npm](https://img.shields.io/npm/v/omnius.svg)](https://www.npmjs.com/package/omnius)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-CC--BY--NC--4.0-blue.svg)](LICENSE)\n\n## Install\n\n```bash\nnpm install -g omnius\nomnius\n```\n\nWith no inference endpoint selected, Omnius opens a lightweight setup helper\nusing anonymous public inference from the [free inference directory](https://robit-man.github.io/inference/).\nAsk about setup or commands, or enter `/key openrouter`, `/key openai`, or\n`/key anthropic` to provide a key privately. Keys stay on your machine; the\nhelper sees opaque references, and only the selected provider receives its key\nfor a small connection test. The helper discovers models, tests the selected\nconnection, saves it, and starts Omnius. Existing configured endpoints bypass\nthis helper. Use `/setup` to reopen it or `/setup local` for local model setup.\n\nIf public inference is unavailable, the local setup tools can still connect a\nprovider-bound key. A local model download is an explicit choice.\n\nThe base install is compiler-free: a fresh machine does not need `make`, a C++\ntoolchain, or Python just to install and launch Omnius. The installer provisions\nthe AIWG companion separately without its optional native semantic-index addon,\nso an unavailable native build cannot roll back the Omnius CLI.\n\nIf npm succeeds but a new terminal reports `omnius: command not found`, inspect\nthe global prefix and add its command directory to `PATH`:\n\n```bash\nnpm prefix -g\nexport PATH=\"$(npm prefix -g)/bin:$PATH\"\nhash -r\nomnius --version\n```\n\nPersist that export in the profile used by your shell, or open a new terminal\nafter an nvm/fnm setup change. `npx omnius@latest` is an immediate fallback.\n\nRequirements:\n\n- Node.js 22 or newer\n- npm 10 or newer for published CLI use\n- pnpm 9 or newer for workspace development\n- A local model or configured remote endpoint\n\nStart the REST daemon:\n\n```bash\nomnius serve\n```\n\nThe daemon defaults to `http://127.0.0.1:11435`. Open the interactive API docs at `http://127.0.0.1:11435/docs`.\n\nRegister the native system tray indicator (Linux, macOS, and Windows x64):\n\n```bash\nomnius tray install\nomnius tray status\n```\n\nThe per-login indicator observes the daemon over loopback, checks health and npm\nupdates every 10 seconds, and provides dashboard, logs, and explicit daemon\ncontrols. Its version row is passive when current and becomes a verified global\nupdate action only when a newer exact semver is available. See the\n[system tray guide](docs/guides/system-tray.md), including Ubuntu/GNOME setup.\n\n## Agent Discovery\n\nThe npm package ships its complete documentation and a machine-readable\ncapability catalog. An agent does not need to inspect Omnius source or guess\nwhich endpoint owns a capability:\n\n```bash\nomnius discover \"bring your own inference\"\nomnius show workflow.choose-entrypoint\nomnius show layer.orchestration\nomnius show store.project\nomnius show provider.anthropic\nomnius show provider.gemini\nomnius show tool.web-search\nomnius discover \"evidence-bound decision impasse\"\nomnius show tool.adjudicate\nomnius discover \"osint research\"\nomnius show capability.osint-research\nomnius capabilities --json\n```\n\nWith the daemon running, begin at `GET /v1/discovery/bootstrap`. The same\ndiscovery cascade is available at `GET /v1/discovery`, with exact entry expansion at\n`GET /v1/discovery/{id}`. The live API contract remains available at\n`/openapi.json`, direct tool metadata at `/v1/tools`, and skills at\n`/v1/skills`.\n\nStart with [the discovery guide](docs/DISCOVERY.md) when integrating another\nagent or service, and use the [agent system map](docs/architecture/agent-system-map.md)\nto trace layers, modules, runtimes, and state ownership. Use [bring-your-own inference](docs/guides/bring-your-own-inference.md)\nfor provider protocols and keys, and [tools and web search](docs/guides/tools-and-web-search.md)\nfor the distinction between direct tools and agent-bound tools. The\n[evidence-bound adjudication guide](docs/ADJUDICATION.md) explains how a\ntop-level full agent freezes an admissible record, isolates a genuine decision\nimpasse from accumulated working context, fans review out across fresh\nevidence-scoped constituents, validates evidence citations and quorum, and\nproduces a durable verdict receipt. Top-level runtimes execute constituents in\na dedicated `full_sub_agent` process profile that cannot load tools, project\ncontext, memory, or the ambient parent environment. The process runs outside\nthe project directory. Cancellation and deadlines terminate its child processes;\nordinary child transport failure is recorded before bounded direct fallback.\nPlanner schema drift uses a deterministic question-framing fallback, and\ndurable artifact replay verifies the case, findings, verdict, and receipt\nhashes without new inference. The\n[categorized OSINT research guide](docs/guides/osint-research.md) documents\nthe local discover → exact expansion → explicit web-tool workflow.\n\n## What Omnius Does\n\n- Runs autonomous coding tasks, edits files, executes tools, tests changes, and iterates on failures.\n- Resolves genuine decision impasses in fresh evidence-scoped contexts that reduce parent-context anchoring, with host-validated citations, quorum, preserved dissent, and durable verdict receipts.\n- Provides a dense terminal UI for model selection, endpoint routing, task control, shell output, voice, sponsors, Telegram, and system telemetry.\n- Exposes a REST daemon with OpenAI/Ollama-compatible inference, agentic task execution, memory, skills, tools, MCP, events, voice, projects, and governance endpoints.\n- Routes models through local, cloud, sponsor, and peer-to-peer endpoints without assuming local Ollama is the only source.\n- Supports realtime spoken conversation for ASR/TTS clients through `/realtime` and REST `realtime: true`.\n- Supports image, video, sound, music, TTS, ASR, voice clone references, Telegram media workflows, and sponsor-provided media generation.\n- Keeps project runtime state in `.omnius/`, which is intentionally ignored by git.\n\n## Common Workflows\n\n```bash\nomnius \"inspect this repo and summarize the main entrypoints\"\nomnius serve\n```\n\n```text\n/help                 command help\n/model                select or inspect the active model\n/endpoint             select or configure local, cloud, sponsor, or peer endpoints\n/title                name the current session\n/realtime             toggle short ASR/TTS-oriented conversation mode\n/voice                choose TTS, voice-clone, voicechat, and ASR controls\n/voice asr            select, set up, activate, or test an exact ASR engine/model\n/indicator            reconcile the daemon, then start the native tray indicator\n/update check         force an update availability check\n/update quick         run the verified global update with live TUI progress\n/update full          run the full clean/build/install/restart verification flow\n/broker               inspect model broker, RAM/VRAM thresholds, and loaded models\n/sponsor              expose local or upstream capacity to peers\n/cohere               participate in distributed COHERE inference\n/telegram             configure or toggle the Telegram bridge\n/skills               list explorable skills and docs memories\n/pause                pause after the current turn boundary\n/stop                 interrupt the active run\n/resume               resume saved state\n```\n\n## Current Feature Areas\n\n| Area | What to read |\n| --- | --- |\n| Install and setup | [Install](docs/getting-started/install.md), [First run](docs/getting-started/first-run.md), [Model providers](docs/getting-started/model-providers.md) |\n| Agent discovery | [Discovery cascade](docs/DISCOVERY.md), [machine catalog](docs/DISCOVERY.json), [agent integration](docs/guides/agent-integration.md) |\n| Bring your own inference | [Provider protocols and keys](docs/guides/bring-your-own-inference.md) |\n| Tools and web search | [Tool discovery and invocation](docs/guides/tools-and-web-search.md) |\n| Evidence-bound adjudication | [Adjudication tool, panel workflow, verdict contract, and harness](docs/ADJUDICATION.md) |\n| Terminal workflows | [TUI workflows](docs/guides/tui-workflows.md), [Slash commands](docs/reference/slash-commands.md) |\n| Web dashboard | [All dashboard routes, workspaces, sessions, Voice, Generate, updates, and observability](docs/guides/dashboard.md) |\n| REST daemon | [REST reference](docs/reference/rest-api.md), [REST quickref](docs/rest/QUICKREF.md), [OpenAPI source](docs/rest/openapi-source.md) |\n| System tray | [Cross-platform tray and Ubuntu setup](docs/guides/system-tray.md) |\n| Realtime voice chat | [Realtime guide](docs/guides/realtime.md) |\n| TTS and selectable ASR | [Voice/vision REST guide](docs/rest/endpoints/voice-vision.md), [Dashboard Voice page](docs/guides/dashboard.md#voice-and-asr) |\n| Sponsor and COHERE mesh | [Sponsor and COHERE guide](docs/guides/sponsor-and-cohere.md) |\n| Telegram bridge | [Telegram guide](docs/guides/telegram.md) |\n| Media generation | [Media guide](docs/guides/media-generation.md) |\n| Operations | [Runtime hygiene](docs/operations/runtime-hygiene.md), [Security and remote access](docs/operations/security-and-remote-access.md) |\n| Service compatibility | [Runtime version gate](docs/operations/version-compatibility.md) |\n| Architecture | [Architecture overview](docs/architecture/overview.md) |\n| Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |\n\n## Web Dashboard\n\n`omnius serve` exposes a self-contained operational dashboard at\n`http://127.0.0.1:11435/`. All pages use the same compact NOCLIP-derived style\ntokens and responsive observability-card grid, while keeping workspace, model,\nsession, run, service, and update state visible instead of hiding it behind\ndecorative pages.\n\n| Route | Purpose |\n| --- | --- |\n| `/chat` (`/`) | Stateful browser and imported TUI chats, full-history hydration, live run recovery, attachments, files, plan/context, and steering check-ins |\n| `/agent` | One-shot task contracts, personas/profiles, tool/isolation controls, run records, output, and events |\n| `/voice` | Voicechat, exact TTS model/options, clone references, ASR engine/model setup and activation, real-file ASR testing, transcript, and TTS testing |\n| `/generate` | Image/video/audio/music jobs, AV analysis, model/store controls, relocation progress, and global gallery |\n| `/projects` | Scan, register, rename, activate, and remove workspaces |\n| `/dashboard` (`/jobs`) | CPU/RAM/GPU/VRAM, processes, scheduler, services, usage, and verified updates |\n| `/activity` | Live run/tool/memory/engine event observability |\n| `/discover` | Agent bootstrap, capability intent search, and exact entry expansion |\n| `/settings` (`/config`) | Models, endpoints, voice, runtime, access, keys, appearance, and services |\n\nThe clickable sidebar brand opens the registered-workspace picker. Workspace\nselection scopes preferences, files, session history, chat pins/folders/search,\nand agent defaults. Chats, TUI visual history, and one-shot agent runs are\ndistinct records: `/quit`, `/exit`, manual-save noise, empty histories, and\nduplicate TUI transcripts are rejected from the chat projection; selecting a\nvalid session loads its full history and in-flight status from the daemon.\nThe chat top bar also reports the effective API base path and authentication\nmode. Streams retain split frames, Stop terminates the daemon-owned process\nlease, and assistant-provided web/file links stay inert until the daemon\nreturns a validation receipt.\n\nThe dashboard checks for updates every 10 seconds. An update button appears only\nfor a newer exact semver and drives `POST /v1/update`, then polls the durable\ntransaction until the global npm package, resolved executable, restarted daemon,\npackage/boot hashes, and tray runtime are reconciled. See the\n[complete dashboard guide](docs/guides/dashboard.md) for state ownership,\nsecurity, page-by-page behavior, and exact REST flows.\n\n## Terminal Over SSH\n\nThe TUI paints for a local terminal, where a full-area repaint costs nothing.\nOver a network the same cadence has to share the link with your keystrokes, so\nOmnius detects a remote session (`SSH_TTY` / `SSH_CONNECTION` / `SSH_CLIENT`)\nand paces itself: decorative chrome animates slower, a wheel-scroll burst is\ncollapsed into a single repaint, unchanged footer frames are not re-sent, and\nthe mouse filter allows more time for escape sequences split across packets.\nNothing changes about how the TUI looks, and local sessions are unaffected.\n\nDetection is environment-based, so it can miss a session where those variables\ndo not reach the process — most often tmux or mosh, whose panes may inherit a\nstale environment from the server. Force the profile when that happens:\n\n```bash\nOMNIUS_TUI_PACING=remote omnius   # pace for a network link\nOMNIUS_TUI_PACING=local omnius    # force local cadence\n```\n\nIf scrolling or typing still feels heavy, `OMNIUS_TUI_PROFILE=compatible`\nadditionally drops the animated truecolor chrome, and `OMNIUS_TUI_PERF=1` logs\nany content reflow that overruns its frame budget to stderr.\n\n## Shared Media Dependencies\n\nImage, video, audio, and music generation share a **single, system-wide dependency store** instead of duplicating heavy runtimes per project or per Telegram group.\n\nEarlier builds wrote a private Python venv plus Hugging Face / Torch / pip caches under every scoped working directory (for example `…/telegram-creative/<group-id>/.omnius/image-gen/.venv`). On a busy machine the same multi-gigabyte diffusers stack and model weights were re-downloaded once per group — tens of gigabytes of pure duplication.\n\nEverything now resolves to one source of truth under `~/.omnius` (override with `OMNIUS_HOME`):\n\n| Location | Holds |\n| --- | --- |\n| `~/.omnius/runtimes/<kind>/.venv-<backend>` | One shared Python venv per kind+backend (image/video/audio) |\n| `~/.omnius/models/huggingface/{hub,transformers,diffusers}` | Shared model weights — downloaded once, reused everywhere |\n| `~/.omnius/models/{torch,cache,pip-cache}` | Shared Torch hub, XDG, and pip caches |\n| `~/.omnius/models/_meta.json` | LRU usage index for automatic disk-pressure eviction |\n| `~/.omnius/media/{images,videos,audio,music}` | Global generated-media gallery (project-independent) |\n\nProject directories keep only lightweight session artifacts; no venvs or model weights are written per project.\n\n**Migrate and dedup existing machines.** A one-time cleanup consolidates any legacy per-group caches into the unified store — unique weights are moved (never re-downloaded), duplicates and stale venvs are reclaimed:\n\n```bash\n# TUI — current project only\n/models cleanup\n# TUI — every project + nested scoped group on this machine (dry-run first)\n/models cleanup --all --dry-run\n/models cleanup --all\n```\n\n```bash\n# REST — preview, then apply\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{\"dryRun\":true}'\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{}'\n# Inspect store + reclaimable legacy caches\ncurl -s localhost:11435/v1/media/store\n```\n\n**Generate over REST.** The daemon (default `127.0.0.1:11435`, a port in the IANA dynamic/private range that avoids common system-service collisions) exposes the local generators so any user on the machine can list models, generate, and browse the global gallery without the CLI:\n\n```bash\ncurl -s localhost:11435/v1/media/models\ncurl -s -X POST localhost:11435/v1/media/image -H 'content-type: application/json' -d '{\"prompt\":\"a compact robot painter\"}'\ncurl -s -X POST localhost:11435/v1/media/music -H 'content-type: application/json' -d '{\"prompt\":\"warm lo-fi piano loop\"}'\ncurl -s localhost:11435/v1/media/gallery\n```\n\nThe same surface drives the **Generate** tab in the web UI (`http://127.0.0.1:11435`) — pick a kind (image/video/audio/music), choose a model loaded from the system, generate, and review every previously generated file in one global gallery.\n\n## Recent Highlights\n\n- The dashboard now has nine route-level operational surfaces with shared modular observability grids, a searchable workspace picker, and project-scoped navigation state.\n- Chat history unifies persisted browser sessions with quality-filtered TUI transcripts, rejects command/noise sessions such as `/quit`, hydrates full history on selection, and exposes summaries, follow-up suggestions, reactive live deltas, and canonical deletion.\n- `/indicator` reconciles daemon ownership and health before launching the tray; the tray polls every 10 seconds and turns its version row into a retryable verified-update action only when an update exists.\n- Dashboard, tray, and TUI update actions now share an exact-version global transaction with live phase/output and package, executable, daemon, hash, restart, and tray verification.\n- TTS exposes GLaDOS, Overwatch, `luxtts:announcer-testchamber03`, and configurable Voicebox models; ASR independently exposes Whisper, managed `transcribe-cli`, Nemotron readiness, and pinned Microsoft VibeVoice ASR with Jetson/ARM64 CUDA-aware setup.\n- LuxTTS auto-setup on Jetson ARM64 requires CPU ONNX Runtime at import time, validates CUDA Torch separately against the host runtime, preserves existing caches during repair, and never substitutes generic PyPI Torch or automatic sudo for an AGX Orin deployment.\n- `/realtime` and REST `realtime: true` provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.\n- Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.\n- `/sponsor` can expose text inference and media generation for image, video, sound, and music with per-modality limits.\n- Sponsor and COHERE status surfaces now use shared telemetry concepts: concurrency, request rate, daily tokens, peer usage, model usage, and remote system metrics.\n- The TUI reports token production rate as `t/s`, supports Shift+Enter multiline input, and renders dynamic shell output inside bounded Unicode cards.\n- Telegram state is scoped by user and group, supports durable reply preferences, and feeds raw platform/tool failures back into the agent loop.\n- Telegram media ingress is byte- and duration-bounded, cache-only before routing, deduplicated by Telegram file identity, and evidence-gated after admission. Speech uses scoped transcription; music/general audio uses typed semantic or explicitly acoustic-only analysis without false listening claims.\n- Telegram public creative work now includes typed PDF/DOCX creation and hash-guarded review, fixed-operation FFmpeg audio editing, and root-confined image crop/resize/mask/composite workflows. Host-signed content capabilities bind review evidence and durable Telegram delivery to the exact artifact bytes.\n- Ollama pool cleanup now accounts for process groups and orphan runner processes that can keep VRAM pinned.\n- REST documentation is available both as human docs and as Omnius-discoverable docs skills.\n\n## REST API\n\nStart the daemon (default `http://127.0.0.1:11435`; interactive docs at `/docs`, machine spec at `/openapi.json`):\n\n```bash\nomnius serve\n```\n\nFor shared deployments, gate access with scoped bearer keys (`read` < `run` < `admin`):\n\n```bash\nOMNIUS_REST_API_KEYS=\"read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops\" omnius serve\n# then: Authorization: Bearer <key>\n```\n\nThe complete supported endpoint inventory follows. The canonical machine\ncontract is generated from [`packages/cli/src/api/openapi.ts`](packages/cli/src/api/openapi.ts),\nvalidated against [`docs/reference/rest-api.md`](docs/reference/rest-api.md),\nand projected into the generated block below. `pnpm docs:check` now fails when\nany of those three surfaces drift. Browser HTML pages, Swagger static assets,\nand implementation-only compatibility bridges are intentionally outside this\nstable REST contract.\n\n<!-- BEGIN GENERATED REST INVENTORY -->\n### Docs And Compatibility Aliases\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/docs` | Swagger UI |\n| `GET` | `/api/docs` | Swagger UI alias |\n| `GET` | `/openapi.json` | OpenAPI JSON |\n| `GET` | `/openapi.yaml` | OpenAPI YAML |\n| `GET` | `/v3/api-docs` | OpenAPI alias |\n| `GET` | `/swagger.json` | Swagger-era alias |\n| `GET` | `/api-docs` | OpenAPI alias |\n| `GET` | `/swagger-ui` | Swagger UI alias |\n| `GET` | `/redoc` | ReDoc renderer |\n| `GET` | `/` | HATEOAS API root when the client does not request HTML |\n| `GET` | `/help` | Compact daemon integration help |\n| `GET` | `/v1/routes` | Flat grep-friendly daemon route summary |\n| `GET` | `/routes` | Route-summary compatibility alias |\n| `GET` | `/asyncapi.json` | AsyncAPI 2.6 voicechat WebSocket contract |\n| `GET` | `/asyncapi` | AsyncAPI compatibility alias |\n\n### Health And Observability\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/health` | Liveness probe |\n| `GET` | `/health/ready` | Backend readiness |\n| `GET` | `/health/startup` | Startup probe |\n| `GET` | `/version` | Package version and platform |\n| `GET` | `/metrics` | Prometheus metrics |\n| `GET` | `/v1/events` | Server-sent event stream |\n| `GET` | `/v1/usage` | Token usage and rate limits |\n| `GET` | `/v1/audit` | Audit log query |\n| `GET` | `/v1/cost` | Cost tracker |\n| `GET` | `/v1/system` | CPU, RAM, GPU, and system snapshot |\n\n### Discovery\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/discovery/bootstrap` | Compact agent bootstrap and start-here map |\n| `GET` | `/v1/discovery` | Search layers, workflows, runtimes, modules, stores, and capabilities |\n| `GET` | `/v1/discovery/{id}` | Expand one stable capability entry |\n\n### Inference And Chat\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/models` | Aggregated model list |\n| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |\n| `POST` | `/v1/chat` | Stateful Omnius chat |\n| `POST` | `/api/chat` | Ollama-compatible chat alias |\n| `POST` | `/v1/generate` | Ollama-compatible one-shot generation |\n| `POST` | `/api/generate` | Ollama-compatible generate alias |\n| `POST` | `/v1/embeddings` | OpenAI-compatible embeddings |\n| `POST` | `/api/embed` | Ollama-compatible embeddings alias |\n| `GET` | `/api/tags` | Ollama-compatible model tags |\n| `POST` | `/realtime` | Text-only voice-adapter reply from a transcript |\n| `POST` | `/v1/realtime` | Auth-scoped realtime adapter alias |\n| `GET` | `/v1/chat/sessions` | Workspace-scoped persisted browser chats and importable TUI sessions |\n| `GET` | `/v1/chat/sessions/{id}` | Hydrate full session history, transcript, and in-flight state |\n| `DELETE` | `/v1/chat/sessions/{id}` | Permanently delete a canonical chat or TUI history session |\n| `POST` | `/v1/chat/sessions/{id}/summarize` | Generate + cache an inference-based session title/summary |\n| `POST` | `/v1/chat/suggest-followup` | Suggest one short next-message follow-up (ghost-text input) |\n| `GET` | `/v1/chat/sessions/{id}/status` | Reactive recall: live run status + unseen deltas (`?since=<seq>`) |\n| `POST` | `/v1/chat/sessions/{id}/pause` | Pause the exact daemon-owned chat generation at a safe admission boundary |\n| `POST` | `/v1/chat/sessions/{id}/resume` | Resume the exact paused daemon-owned chat generation |\n| `POST` | `/v1/chat/sessions/{id}/stop` | Stop the daemon-owned chat process lease; idle/terminal calls are idempotent |\n| `POST` | `/v1/chat/check-in` | Steering check-in for active chat |\n| `POST` | `/v1/chat/attachments` | Upload an attachment for a stateful chat |\n| `POST` | `/v1/links/validate` | Validate an external HTTP(S) destination under the daemon egress policy |\n\n#### Session History Contract\n\n`GET /v1/chat/sessions` is a history index, not merely a list of processes that\nare currently active. It returns canonical persisted browser chats for the\nselected workspace and, by default, quality-filtered TUI visual sessions that\ncan be imported on demand. Pass `?root=/absolute/workspace` to scope the list and\n`?include_tui=0` to omit TUI history. Exit-only inputs such as `/quit` and\n`/exit`, manual-save noise, empty transcripts, and duplicate normalized TUI\nsessions are rejected by the session-quality projection rather than presented as\nchats.\n\nSelecting a row should call `GET /v1/chat/sessions/{id}`. That response hydrates\nthe complete public message history (system prompts are intentionally omitted),\nthe original TUI transcript when applicable, token counts, timestamps, source\nand project identity, and any in-flight run with a bounded partial-output tail.\nUse the `status` endpoint with `?since=<seq>` for cheap reactive polling while a\nrun is active. `DELETE /v1/chat/sessions/{id}` is an admin operation and removes\nthe canonical record; deleting only a browser-side row does not remove daemon\nhistory.\n\nPause and resume use the exact session and active external-run identity. Both\noperations require `run` scope. An idle session returns `200`. An accepted\nrequest returns `200` with the lifecycle acknowledgement, owner generation,\ncurrent phase, resumability, and pending acknowledgement count. A lifecycle\nrejection returns `409`. A live owner that does not acknowledge within the\ncontrol deadline returns `504`. Clients must not treat a local UI pause as a\ndaemon pause.\n\n`POST /realtime` and `/v1/realtime` are text-only conversation adapters. They\naccept transcript text through `message`, `text`, `recent_turn`, `asr_text`, or\n`callerText`, optionally accept adapter-local `soul_md`, and can return plain\ntext with `Accept: text/plain` or `format: \"text\"`. ASR and TTS remain separate\noperations.\n\n### Agentic Runs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `POST` | `/v1/run` | Submit agentic task |\n| `GET` | `/v1/runs` | List runs |\n| `GET` | `/v1/runs/{id}` | Get run details |\n| `GET` | `/v1/runs/{id}/output` | Read captured run output and status |\n| `DELETE` | `/v1/runs/{id}` | Abort run |\n| `POST` | `/v1/todos` | Create or update todos for current session |\n| `GET` | `/v1/todos` | List sessions with todos |\n| `GET` | `/v1/todos/{session_id}` | Get session todos |\n| `DELETE` | `/v1/todos/{session_id}` | Delete session todos |\n| `POST` | `/v1/evaluate` | Evaluate a run |\n| `POST` | `/v1/index` | Trigger repository indexing |\n\n### Configuration, Keys, Profiles, Projects\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/config` | Read daemon config |\n| `PATCH` | `/v1/config` | Update daemon config |\n| `GET` | `/v1/config/model` | Current model |\n| `PUT` | `/v1/config/model` | Switch model |\n| `POST` | `/v1/config/model/check` | Probe model readiness with non-empty text |\n| `GET` | `/v1/config/endpoint` | Current endpoint |\n| `PUT` | `/v1/config/endpoint` | Switch endpoint |\n| `POST` | `/v1/config/endpoint/test` | Probe endpoint |\n| `GET` | `/v1/config/endpoint/history` | Endpoint history |\n| `DELETE` | `/v1/config/endpoint/history` | Remove endpoint history item |\n| `POST` | `/v1/share/generate` | Generate remote-access share URL |\n| `GET` | `/v1/keys` | List runtime API keys |\n| `POST` | `/v1/keys` | Mint runtime API key |\n| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime API keys by prefix |\n| `GET` | `/v1/profiles` | List tool profiles |\n| `POST` | `/v1/profiles` | Create tool profile |\n| `GET` | `/v1/profiles/{name}` | Get profile |\n| `DELETE` | `/v1/profiles/{name}` | Delete profile |\n| `GET` | `/v1/projects` | List known projects |\n| `DELETE` | `/v1/projects` | Unregister a project |\n| `GET` | `/v1/projects/current` | Current project |\n| `POST` | `/v1/projects/switch` | Switch project |\n| `POST` | `/v1/projects/register` | Register project |\n| `POST` | `/v1/projects/rename` | Rename project |\n| `GET` | `/v1/projects/preferences` | Read project preferences |\n| `PUT` | `/v1/projects/preferences` | Patch project preferences |\n| `DELETE` | `/v1/projects/preferences` | Reset project preferences |\n| `GET` | `/v1/projects/scan` | Scan configured roots for discoverable workspaces |\n| `GET` | `/v1/admin/access` | Read the daemon network access mode |\n| `POST` | `/v1/admin/access` | Change and persist access mode from loopback only |\n\n### Skills, Commands, Tools, MCP\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/skills` | List skills |\n| `GET` | `/v1/skills/{name}` | Load skill content |\n| `GET` | `/v1/commands` | List slash commands |\n| `POST` | `/v1/commands/{cmd}` | Execute slash command |\n| `GET` | `/v1/tools` | List tools (built-in + external) |\n| `POST` | `/v1/tools/register` | Register an application-specific external tool |\n| `GET` | `/v1/tools/{name}` | Tool metadata |\n| `DELETE` | `/v1/tools/{name}` | Unregister an external tool |\n| `POST` | `/v1/tools/{name}/call` | Call tool |\n| `POST` | `/v1/tools/{name}/eval` | Evaluate an external tool against test cases |\n| `GET` | `/v1/mcps` | List MCP servers |\n| `GET` | `/v1/mcps/{name}` | MCP server details |\n| `POST` | `/v1/mcps/{name}/call` | Call MCP tool |\n| `GET` | `/v1/hooks` | Hook registry |\n| `GET` | `/v1/agents` | Agent type registry |\n| `GET` | `/v1/codegraph/snapshot` | Code graph snapshot |\n| `GET` | `/v1/codegraph/events` | Code graph SSE |\n\n#### Registering Application-Specific Tools\n\nApplications can register their own tools so Omnius agents can discover and\ninvoke them alongside built-ins. `transport.type` selects the bridge:\n\n- `http` makes Omnius POST `{name, args, session_id}` to the application's\n  `callback_url` and relay the result.\n- `mcp` proxies to a named tool on an MCP server and can auto-connect from the\n  supplied connection descriptor.\n\nRegistrations persist per workspace at `.omnius/external-tools.json`, appear in\n`GET /v1/tools`, and use the same scope and off-device security gates as built-in\ntools. Registration needs `run` scope; a non-loopback caller needs `admin`.\n\n```bash\ncurl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{\n  \"name\": \"lookup_order\",\n  \"description\": \"Look up an order by id\",\n  \"parameters\": {\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}},\"required\":[\"id\"]},\n  \"security\": {\"requires_scope\":\"run\",\"risk\":\"low\"},\n  \"transport\": {\"type\":\"http\",\"callback_url\":\"https://app.internal/tools/lookup_order\",\"auth_header\":\"Bearer …\"}\n}'\ncurl -s localhost:11435/v1/tools/lookup_order\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{\"args\":{\"id\":\"A-1001\"}}'\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{\"cases\":[{\"name\":\"known\",\"args\":{\"id\":\"A-1001\"},\"expect\":{\"success\":true}}]}'\ncurl -s -X DELETE localhost:11435/v1/tools/lookup_order\n```\n\nThe MCP equivalent uses a transport such as\n`{\"type\":\"mcp\",\"server\":\"acme\",\"tool\":\"search\",\"connect\":{\"url\":\"https://app.internal/mcp\",\"transport\":\"streamable-http\"}}`.\n\n### AIWG\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aiwg` | AIWG root and control map |\n| `GET` | `/v1/aiwg/frameworks` | List frameworks |\n| `GET` | `/v1/aiwg/frameworks/{name}` | Framework details |\n| `GET` | `/v1/aiwg/frameworks/{name}/content` | Tier-aware content |\n| `GET` | `/v1/aiwg/skills` | List AIWG skills |\n| `GET` | `/v1/aiwg/skills/{name}` | Load AIWG skill |\n| `GET` | `/v1/aiwg/agents` | List AIWG agents |\n| `GET` | `/v1/aiwg/agents/{name}` | Load AIWG agent |\n| `GET` | `/v1/aiwg/addons` | List AIWG addons |\n| `POST` | `/v1/aiwg/use` | Tier-sized activation bundle |\n| `POST` | `/v1/aiwg/expand` | Expand matching AIWG item |\n\n### Memory, Sessions, Context\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/memory` | Memory backend summary |\n| `POST` | `/v1/memory/search` | Search memory |\n| `POST` | `/v1/memory/write` | Write memory |\n| `GET` | `/v1/memory/episodes` | List episodes |\n| `GET` | `/v1/memory/failures` | List failure records |\n| `POST` | `/v1/memory/ingest` | Ingest content or files into memory |\n| `GET` | `/v1/memory/entities` | List extracted memory entities |\n| `POST` | `/v1/memory/jobs/run` | Run a named memory-maintenance job |\n| `POST` | `/v1/memory/feedback` | Record relevance or quality feedback for a memory item |\n| `POST` | `/v1/memory/speaker-identities/enroll` | Admin-only, explicit-consent speaker exemplar enrollment in one exact vector space |\n| `POST` | `/v1/memory/speaker-identities/match` | Admin-only provisional speaker candidate matching without durable assignment |\n| `GET` | `/v1/sessions` | List task sessions |\n| `GET` | `/v1/sessions/{id}` | Get session history |\n| `GET` | `/v1/context` | Current context snapshot |\n| `GET` | `/v1/context/window-dumps` | List persisted outbound model context-window dumps |\n| `GET` | `/v1/context/window-dumps/{id}` | Fetch a full outbound model context-window dump |\n| `POST` | `/v1/context/save` | Save context entry |\n| `GET` | `/v1/context/restore` | Build restore prompt |\n| `POST` | `/v1/context/compact` | Request compaction |\n\nContext-window dumps are written before backend inference for main agents, sub-agents, internal runners, and adversary audits. Query\n`GET /v1/context/window-dumps?agent_type=main` for summaries with signal/noise\nmetrics, or fetch a full payload by id. Dumps include focus-supervisor state when\na next-action contract is active. Set `OMNIUS_CONTEXT_WINDOW_DUMP_DIR` to move\nthe store, `OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1` to disable it, and\n`OMNIUS_FOCUS_SUPERVISOR=off|auto|strict` to tune focus enforcement.\n\n### Files, Web, Nexus, Ollama Pool\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/files` | List workspace directory |\n| `POST` | `/v1/files/read` | Read workspace file |\n| `GET` | `/v1/files/raw` | Stream raw workspace bytes with content type and range support |\n| `HEAD` | `/v1/files/raw` | Inspect raw-file response metadata |\n| `GET` | `/v1/web/search` | Inspect web-search availability, schema, and security policy |\n| `POST` | `/v1/web/search` | Search the web directly through the Omnius tool runtime |\n| `GET` | `/v1/web/fetch` | Inspect web-fetch availability, schema, and security policy |\n| `POST` | `/v1/web/fetch` | Fetch a URL directly through the Omnius tool runtime |\n| `GET` | `/v1/web/crawl` | Inspect web-crawl availability, schema, and security policy |\n| `POST` | `/v1/web/crawl` | Crawl a website directly through the Omnius tool runtime |\n| `GET` | `/v1/nexus/status` | Nexus peer state |\n| `GET` | `/v1/sponsors` | Sponsor directory cache |\n| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |\n| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |\n\nThe `/v1/web/*` routes are stable aliases of the shared tool registry. `GET`\nreturns the corresponding tool metadata. `POST` uses the same authentication,\nprofile, origin, timeout, output-size, audit, and network-egress policy as a\ndirect tool call. Send search requests as\n`{\"args\":{\"query\":\"...\",\"num_results\":5,\"provider\":\"duckduckgo\"}}` and\nfetch requests as `{\"args\":{\"url\":\"https://example.com\"}}`. Crawl uses the\nschema returned by its `GET` route and requires the browser dependencies that\nthe metadata reports. POST responses use the standard `ToolResult` envelope.\n\n### Voice, Audio, Vision\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/voice/state` | Voice runtime status |\n| `POST` | `/v1/voice/start` | Select an optional model, enable voice, and wait for readiness |\n| `POST` | `/v1/voice/stop` | Pause daemon voice input while leaving TTS warm |\n| `GET` | `/v1/voice/models` | TTS models |\n| `POST` | `/v1/voice/models/switch` | Switch and enable an exact TTS model by default |\n| `POST` | `/v1/voice/models/{modelId}/pull` | Install runtime prerequisites and pull one managed TTS model |\n| `POST` | `/v1/voice/models/{modelId}/deploy` | Pull and deploy one managed CUDA TTS model |\n| `GET` | `/v1/voice/supertonic-settings` | Voice tuning settings |\n| `POST` | `/v1/voice/supertonic-settings` | Update voice tuning settings |\n| `GET` | `/v1/asr/engines` | Canonical ASR engines/models, capabilities, readiness, and selection |\n| `GET` | `/v1/asr/status` · `/v1/asr/selection` | Selected engine/model and runtime status |\n| `GET` | `/v1/asr/downloads` | List persistent ASR weight download and deployment transitions |\n| `POST` | `/v1/asr/downloads` | Start or resume an ASR weight download |\n| `GET` | `/v1/asr/downloads/{engineId}/{modelId}` | Poll one ASR download and deployment transition |\n| `POST` | `/v1/asr/downloads/{engineId}/{modelId}` | Start or resume this model download |\n| `POST` | `/v1/asr/downloads/{engineId}/{modelId}/retry` | Retry or resume a failed or interrupted ASR weight download |\n| `PATCH` | `/v1/asr/selection` | Persist and activate an exact engine/model |\n| `POST` | `/v1/asr/activate` | Activate and persist an exact engine/model |\n| `POST` | `/v1/asr/engines/{engineId}/setup` | Install a managed runtime and pinned weights |\n| `POST` | `/v1/asr/engines/{engineId}/models/{modelId}/pull` | Pull one exact ASR model and validate its managed runtime |\n| `POST` | `/v1/asr/engines/{engineId}/models/{modelId}/deploy` | Pull, select, and activate one exact ASR model |\n| `POST` | `/v1/asr/transcriptions` · `/v1/asr/test` | Transcribe/test using the real selected backend |\n| `GET` | `/v1/voice/asr-models` | Compatibility registry alias |\n| `POST` | `/v1/voice/asr-models/switch` | Compatibility activation alias |\n| `POST` | `/v1/voice/tts` | Synthesize speech |\n| `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |\n| `GET` | `/v1/audio/classify/health` | Jetson CUDA/TensorRT YAMNet readiness |\n| `POST` | `/v1/audio/classify/setup` | Provision and warm the pinned JetPack TensorRT YAMNet runtime |\n| `POST` | `/v1/audio/classify` | Direct-tool compatible CUDA audio classification |\n| `GET` | `/v1/audio/embed/health` | Role-typed embedding readiness (`?kind=acoustic|speaker|semantic`) |\n| `POST` | `/v1/audio/embed/setup` | Provision/warm one role-typed embedding runtime (admin; `?kind=...`) |\n| `POST` | `/v1/audio/embed` | Managed role-typed audio embedding (`?kind=...`) |\n| `GET` | `/v1/audio/diarization/live/readiness` | Non-mutating managed Sortformer worker readiness |\n| `POST` | `/v1/audio/diarization/live/setup` | Verify and warm a local Sortformer runtime (admin) |\n| `POST` | `/v1/audio/diarization/live` | Managed live/session-local speaker-turn diarization |\n| `POST` | `/v1/audio/diarization/live/cancel` | Terminate live worker work and clear its queue |\n| `GET` | `/v1/audio/diarization/reconcile/readiness` | Non-mutating managed Community-1 worker readiness |\n| `POST` | `/v1/audio/diarization/reconcile/setup` | Verify and warm a local Community-1 runtime (admin) |\n| `POST` | `/v1/audio/diarization/reconcile` | Managed offline/dream reconciliation proposals |\n| `POST` | `/v1/audio/diarization/reconcile/cancel` | Terminate reconciliation work and clear its queue |\n| `POST` | `/v1/voice/transcribe` | Transcribe audio |\n| `POST` | `/v1/voice/asr` | Legacy transcription alias |\n| `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |\n| `POST` | `/v1/voice/transcribe/stream` | Isolated final transcription over SSE (no shared mic state or fake partials) |\n| `POST` | `/v1/voice/clone-refs` | Upload voice clone reference |\n| `GET` | `/v1/voice/clone-refs` | List clone references |\n| `POST` | `/v1/voice/clone-refs/upload` | Upload clone reference |\n| `POST` | `/v1/voice/clone-refs/from-url` | Fetch clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/activate` | Activate clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/rename` | Rename clone reference |\n| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |\n| `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |\n| `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |\n| `POST` | `/v1/vision/describe` | Vision describe placeholder |\n| `GET` | `/v1/vision/embed/readiness` | Non-mutating isolated OpenCLIP readiness |\n| `POST` | `/v1/vision/embed/setup` | Explicit isolated OpenCLIP setup (admin scope) |\n| `POST` | `/v1/vision/embed` | Create a vision embedding from media |\n| `GET` | `/v1/ocr/readiness` | Non-mutating advanced-OCR dependency and backend readiness |\n| `POST` | `/v1/ocr/setup` | Create and verify the isolated OCR venv (admin scope) |\n| `POST` | `/v1/ocr/advanced` | Agent-equivalent managed advanced OCR (alias of `/v1/tools/ocr_image_advanced/call`) |\n\n`POST /v1/voice/tts` and `/v1/audio/speech` automatically warm the daemon.\nAn explicit model must render exactly or the request fails; Omnius does not\nsilently synthesize with another voice. Responses include `X-Voice-Model`,\n`X-Voice-Backend`, and `X-Sample-Rate`. Available models include GLaDOS,\nOverwatch, `luxtts:announcer-testchamber03`, and the selected Voicebox suite.\nSet `OMNIUS_VOICEBOX_MODELS=all` for every carried-in Voicebox model, leave it\nat `stable` for the default set, or provide a comma-separated subset.\n\nASR selection is independent from TTS selection. The registry currently exposes\nOpenAI Whisper, managed `transcribe-cli`, NVIDIA Nemotron (reported unavailable\nuntil its legacy bootstrap is migrated), and Microsoft VibeVoice ASR. VibeVoice\nuses the exact pinned `microsoft/VibeVoice-ASR` checkpoint, reports setup and\nactivation separately, supports completed files up to 60 minutes with speakers,\ntimestamps, and `?context=` hotwords, and is deliberately not advertised as an\nincremental PCM backend. Its managed setup inherits the host CUDA-enabled Torch\nbuild (needed on Jetson/ARM64), never installs generic PyPI Torch, and activation\nrequires one explicit capable GPU. Discrete Linux uses `nvidia-smi` process/GPU\nevidence; Jetson/L4T uses NVIDIA's documented `tegrastats` plus CUDA Torch device\nproperties because `nvidia-smi` is unavailable there. Model weights live under\nthe unified Omnius ASR cache and are not shipped in the npm package.\n\n### Generative Media\n\nAll generation is backed by the unified `~/.omnius` model store and shared venvs (single source of truth — no per-project duplication). Generated files are consolidated into the global gallery at `~/.omnius/media/{images,videos,audio,music}`.\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/media/models` | List available image/video/audio/music models |\n| `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |\n| `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |\n| `POST` | `/v1/media/relocate` | Relocate the whole media store (weights/venvs/gallery) to a chosen folder |\n| `GET` | `/v1/media/relocate/status` | Status + progress of the media-store relocation job |\n| `POST` | `/v1/media/av/analyze` | Analyze a media file into a grounded entity/event answer (AV comprehension) |\n| `POST` | `/v1/media/image` | Generate an image |\n| `POST` | `/v1/media/video` | Generate a video |\n| `POST` | `/v1/media/audio` | Generate a sound effect |\n| `POST` | `/v1/media/music` | Generate music |\n| `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |\n| `GET` | `/v1/media/file` | Stream one generated media file |\n\nManaged TTS `pull` installs the model's runtime prerequisites and weights. It\ndoes not start inference. Managed TTS `deploy` also verifies the selected CUDA\ndevice and starts the persistent runtime. Both operations return `200` when\nready, `404` when the model has no matching managed adapter, and `500` when\ninstallation, download, CUDA preflight, or startup fails.\n\nASR download requests use `{engineId, modelId, device?}`. A collection POST\nreturns `200` when weights are ready or `202` with `statusUrl`, `retryUrl`, and\n`pollAfterMs` while work is pending. Duplicate work coalesces. Poll the model\nURL until its download is ready and its deployment is active. A missing job\nreturns `404`. Model-specific POST and retry requests return `200` when ready or\n`202` when accepted. The model `pull` and `deploy` routes accept optional\n`{device}`. Pull validates the managed runtime and CUDA placement. Deploy also\npersists the selection after readiness and returns a pollable `202` transition\nwhen activation is pending.\n\n### Engines And Scheduled Jobs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/engines` | Long-running engine status |\n| `GET` | `/v1/services` | List all active daemon-owned REST services and their routes |\n| `GET` | `/v1/services/{id}` | Get one daemon-owned REST service contract |\n| `GET` | `/v1/scheduled` | List scheduled jobs |\n| `DELETE` | `/v1/scheduled/all` | Delete all tasks, timers, cron entries, and persisted sources |\n| `GET` | `/v1/scheduled/status` | Scheduler status |\n| `POST` | `/v1/scheduled/{id}` | Enable or disable one scheduled task or user timer |\n| `DELETE` | `/v1/scheduled/{id}` | Delete one scheduled task or user timer |\n| `POST` | `/v1/scheduled/kill` | Kill scheduled job |\n| `POST` | `/v1/scheduled/fixup` | Reconcile scheduled state |\n| `GET` | `/v1/scheduled/reconcile` | Preview scheduled reconciliation |\n| `POST` | `/v1/scheduled/reconcile` | Preview or apply scheduled reconciliation |\n| `GET` | `/v1/services/systemd` | Systemd service status |\n| `POST` | `/v1/services/systemd/{unit}` | Act on one user-level systemd unit |\n| `GET` | `/v1/update` | Self-update status |\n| `POST` | `/v1/update` | Start an exact-version verified global update transaction |\n\n`GET /v1/services` is the agent-readable service inventory generated from the\nOpenAPI document. Each entry states lifecycle ownership, interactive-session\ndependency, registered routes, and a readiness or status route when one exists.\n`GET /v1/services/{id}` returns one service contract or `404` for an unknown\nservice ID. These discovery routes do not mutate services. `/listen` and\n`/hangup` control voice sessions only and do not own the REST daemon.\n\n#### Verified Global Update Transaction\n\n`POST /v1/update` is not a CLI-local package edit. It starts one durable\ntransaction that installs the requested exact npm version globally, verifies\nthe installed package and resolved `omnius` executable, restarts and verifies\nthe daemon, verifies package/hash/runtime agreement, and relaunches the tray if\nit was running. The response is `202` with operation state; poll\n`GET /v1/update` for live phase, subprocess output, verification evidence, and\nthe final success or failure. Concurrent transactions and requests with no\navailable target return `409`.\n\nThe web dashboard and native tray both use this same endpoint. Update discovery\nis shared and semver-aware, so an older cached registry result cannot downgrade\nor falsely present an update. A completed transaction means the global package,\nexecutable, daemon, and tray runtime were all reconciled—not merely that `npm`\nexited successfully.\n\n### AIMS Governance\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aims` | AIMS root and endpoint index |\n| `GET` | `/v1/aims/policies` | Policy register |\n| `PUT` | `/v1/aims/policies` | Replace policy register |\n| `GET` | `/v1/aims/roles` | Roles and responsibilities |\n| `GET` | `/v1/aims/resources` | Resource inventory |\n| `GET` | `/v1/aims/impact-assessments` | Impact assessments |\n| `POST` | `/v1/aims/impact-assessments` | File impact assessment |\n| `GET` | `/v1/aims/lifecycle` | Lifecycle state |\n| `GET` | `/v1/aims/data-quality` | Data quality controls |\n| `GET` | `/v1/aims/transparency` | Model cards and transparency |\n| `GET` | `/v1/aims/usage` | AIMS usage view |\n| `GET` | `/v1/aims/suppliers` | Supplier inventory |\n| `GET` | `/v1/aims/incidents` | Incident records |\n| `POST` | `/v1/aims/incidents` | File incident |\n| `GET` | `/v1/aims/oversight` | Human oversight gates |\n| `GET` | `/v1/aims/decisions` | Consequential decision log |\n| `GET` | `/v1/aims/config-history` | Config change history |\n\n### Browser And Compatibility Surfaces\n\nThe dashboard HTML routes (`/`, `/chat`, `/agent`, `/voice`, `/generate`,\n`/projects`, `/dashboard`, `/jobs`, `/activity`, `/discover`, `/settings`, and\n`/config`) are documented in the [dashboard guide](../guides/dashboard.md). They\nare pages, not JSON API operations; `/` returns the HATEOAS JSON root when the\nclient does not request HTML.\n\nSwagger/ReDoc trailing-slash variants, `/api/docs/*` static assets, and\n`/favicon.ico` exist for browsers. They are delivery details rather than stable\nintegration endpoints. The daemon also retains browser/legacy bridges at\n`/v1/model`, `/v1/endpoint`, `/v1/theme`, `/v1/tor/*`, `/v1/remote-proxy`, and\n`/v1/command`. New clients should prefer `/v1/config/model`,\n`/v1/config/endpoint`, `/v1/config`, and `/v1/commands/{cmd}`. Compatibility\nhandlers may accept additional HTTP verbs for old dashboard bundles; only the\nmethods in the supported inventory above are contractual.\n<!-- END GENERATED REST INVENTORY -->\n## Agent-Explorable Documentation\n\nOmnius discovers project-local docs skills from `.aiwg/addons/*/skills`. The docs bundles in this repo expose high-signal entrypoints for agents:\n\n```text\n/skills omnius docs\nskill_execute name=\"omnius-docs\"\nskill_execute name=\"omnius-rest-docs\"\nskill_extract name=\"omnius-realtime-docs\" query=\"How does realtime REST mode work?\"\n```\n\nThe intended pattern is index first, targeted document second, not loading the whole manual into the active context.\n\n## Development\n\n```bash\npnpm install\npnpm -r build\npnpm docs:check\n```\n\nFocused checks used for the docs skill surface:\n\n```bash\npnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts\npnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts\n```\n\n## Publishing\n\nPublish only from `publish/`.\n\n```bash\ncd omnius\npnpm -r clean || true\nfind . -name 'tsconfig.tsbuildinfo' -not -path '*/node_modules/*' -delete\npnpm -r build\nnode scripts/build-publish.mjs\ncd publish\nmkdir -p .npm-cache\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm pack --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\n```\n\nBefore publishing, verify `README.md`, `package.json`, `dist/index.js`, and `dist/launcher.cjs` are in the tarball, and that `package.json` includes `readmeFilename: \"README.md\"` plus a string `readme`.\n\n## License\n\nOmnius is released under [CC-BY-NC-4.0](LICENSE) for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.\n"
+  "readme": "# Omnius\n\nOmnius is a local-first agentic coding runtime: terminal UI, autonomous coding loop, REST daemon, model router, memory layer, media tools, Telegram bridge, and peer-to-peer inference mesh in one CLI.\n\nIt is designed for open-weight and user-controlled models first, while still routing cleanly through Ollama, vLLM, OpenAI-compatible endpoints, OpenRouter, Groq, Chutes, sponsor peers, COHERE peers, and other configured providers.\n\n[![npm](https://img.shields.io/npm/v/omnius.svg)](https://www.npmjs.com/package/omnius)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-CC--BY--NC--4.0-blue.svg)](LICENSE)\n\n## Install\n\n```bash\nnpm install -g omnius\nomnius\n```\n\nWith no inference endpoint selected, Omnius opens a lightweight setup helper\nusing anonymous public inference from the [free inference directory](https://robit-man.github.io/inference/).\nAsk about setup or commands, or enter `/key openrouter`, `/key openai`, or\n`/key anthropic` to provide a key privately. Keys stay on your machine; the\nhelper sees opaque references, and only the selected provider receives its key\nfor a small connection test. The helper discovers models, tests the selected\nconnection, saves it, and starts Omnius. Existing configured endpoints bypass\nthis helper. Use `/setup` to reopen it or `/setup local` for local model setup.\n\nIf public inference is unavailable, the local setup tools can still connect a\nprovider-bound key. A local model download is an explicit choice.\n\nThe base install is compiler-free: a fresh machine does not need `make`, a C++\ntoolchain, or Python just to install and launch Omnius. The installer provisions\nthe AIWG companion separately without its optional native semantic-index addon,\nso an unavailable native build cannot roll back the Omnius CLI.\n\nIf npm succeeds but a new terminal reports `omnius: command not found`, inspect\nthe global prefix and add its command directory to `PATH`:\n\n```bash\nnpm prefix -g\nexport PATH=\"$(npm prefix -g)/bin:$PATH\"\nhash -r\nomnius --version\n```\n\nPersist that export in the profile used by your shell, or open a new terminal\nafter an nvm/fnm setup change. `npx omnius@latest` is an immediate fallback.\n\nRequirements:\n\n- Node.js 22 or newer\n- npm 10 or newer for published CLI use\n- pnpm 9 or newer for workspace development\n- A local model or configured remote endpoint\n\nStart the REST daemon:\n\n```bash\nomnius serve\n```\n\nThe daemon defaults to `http://127.0.0.1:11435`. Open the interactive API docs at `http://127.0.0.1:11435/docs`.\n\nRegister the native system tray indicator (Linux, macOS, and Windows x64):\n\n```bash\nomnius tray install\nomnius tray status\n```\n\nThe per-login indicator observes the daemon over loopback, checks health and npm\nupdates every 10 seconds, and provides dashboard, logs, and explicit daemon\ncontrols. Its version row is passive when current and becomes a verified global\nupdate action only when a newer exact semver is available. See the\n[system tray guide](docs/guides/system-tray.md), including Ubuntu/GNOME setup.\n\n## Agent Discovery\n\nThe npm package ships its complete documentation and a machine-readable\ncapability catalog. An agent does not need to inspect Omnius source or guess\nwhich endpoint owns a capability:\n\n```bash\nomnius discover \"bring your own inference\"\nomnius show workflow.choose-entrypoint\nomnius show layer.orchestration\nomnius show store.project\nomnius show provider.anthropic\nomnius show provider.gemini\nomnius show tool.web-search\nomnius discover \"evidence-bound decision impasse\"\nomnius show tool.adjudicate\nomnius discover \"osint research\"\nomnius show capability.osint-research\nomnius capabilities --json\n```\n\nWith the daemon running, begin at `GET /v1/discovery/bootstrap`. The same\ndiscovery cascade is available at `GET /v1/discovery`, with exact entry expansion at\n`GET /v1/discovery/{id}`. The live API contract remains available at\n`/openapi.json`, direct tool metadata at `/v1/tools`, and skills at\n`/v1/skills`.\n\nStart with [the discovery guide](docs/DISCOVERY.md) when integrating another\nagent or service, and use the [agent system map](docs/architecture/agent-system-map.md)\nto trace layers, modules, runtimes, and state ownership. Use [bring-your-own inference](docs/guides/bring-your-own-inference.md)\nfor provider protocols and keys, and [tools and web search](docs/guides/tools-and-web-search.md)\nfor the distinction between direct tools and agent-bound tools. The\n[evidence-bound adjudication guide](docs/ADJUDICATION.md) explains how a\ntop-level full agent freezes an admissible record, isolates a genuine decision\nimpasse from accumulated working context, fans review out across fresh\nevidence-scoped constituents, validates evidence citations and quorum, and\nproduces a durable verdict receipt. Top-level runtimes execute constituents in\na dedicated `full_sub_agent` process profile that cannot load tools, project\ncontext, memory, or the ambient parent environment. The process runs outside\nthe project directory. Cancellation and deadlines terminate its child processes;\nordinary child transport failure is recorded before bounded direct fallback.\nPlanner schema drift uses a deterministic question-framing fallback, and\ndurable artifact replay verifies the case, findings, verdict, and receipt\nhashes without new inference. The\n[categorized OSINT research guide](docs/guides/osint-research.md) documents\nthe local discover → exact expansion → explicit web-tool workflow.\n\n## What Omnius Does\n\n- Runs autonomous coding tasks, edits files, executes tools, tests changes, and iterates on failures.\n- Resolves genuine decision impasses in fresh evidence-scoped contexts that reduce parent-context anchoring, with host-validated citations, quorum, preserved dissent, and durable verdict receipts.\n- Provides a dense terminal UI for model selection, endpoint routing, task control, shell output, voice, sponsors, Telegram, and system telemetry.\n- Exposes a REST daemon with OpenAI/Ollama-compatible inference, agentic task execution, memory, skills, tools, MCP, events, voice, projects, and governance endpoints.\n- Routes models through local, cloud, sponsor, and peer-to-peer endpoints without assuming local Ollama is the only source.\n- Supports realtime spoken conversation for ASR/TTS clients through `/realtime` and REST `realtime: true`.\n- Supports image, video, sound, music, TTS, ASR, voice clone references, Telegram media workflows, and sponsor-provided media generation.\n- Keeps project runtime state in `.omnius/`, which is intentionally ignored by git.\n\n## Common Workflows\n\nFor large PDF collections, Omnius retains originals in a durable scoped index\nand processes ordering, manipulation, summary and extraction in resumable steps.\nSee the [PDF collections guide](docs/guides/pdf-collections.md) for coverage,\nsource provenance, numeric checks and complete delivery of large results.\n\n```bash\nomnius \"inspect this repo and summarize the main entrypoints\"\nomnius serve\n```\n\n```text\n/help                 command help\n/model                select or inspect the active model\n/endpoint             select or configure local, cloud, sponsor, or peer endpoints\n/title                name the current session\n/realtime             toggle short ASR/TTS-oriented conversation mode\n/voice                choose TTS, voice-clone, voicechat, and ASR controls\n/voice asr            select, set up, activate, or test an exact ASR engine/model\n/indicator            reconcile the daemon, then start the native tray indicator\n/update check         force an update availability check\n/update quick         run the verified global update with live TUI progress\n/update full          run the full clean/build/install/restart verification flow\n/broker               inspect model broker, RAM/VRAM thresholds, and loaded models\n/sponsor              expose local or upstream capacity to peers\n/cohere               participate in distributed COHERE inference\n/telegram             configure or toggle the Telegram bridge\n/skills               list explorable skills and docs memories\n/pause                pause after the current turn boundary\n/stop                 interrupt the active run\n/resume               resume saved state\n```\n\n## Current Feature Areas\n\n| Area | What to read |\n| --- | --- |\n| Install and setup | [Install](docs/getting-started/install.md), [First run](docs/getting-started/first-run.md), [Model providers](docs/getting-started/model-providers.md) |\n| Agent discovery | [Discovery cascade](docs/DISCOVERY.md), [machine catalog](docs/DISCOVERY.json), [agent integration](docs/guides/agent-integration.md) |\n| Bring your own inference | [Provider protocols and keys](docs/guides/bring-your-own-inference.md) |\n| Tools and web search | [Tool discovery and invocation](docs/guides/tools-and-web-search.md) |\n| Evidence-bound adjudication | [Adjudication tool, panel workflow, verdict contract, and harness](docs/ADJUDICATION.md) |\n| Terminal workflows | [TUI workflows](docs/guides/tui-workflows.md), [Slash commands](docs/reference/slash-commands.md) |\n| Web dashboard | [All dashboard routes, workspaces, sessions, Voice, Generate, updates, and observability](docs/guides/dashboard.md) |\n| REST daemon | [REST reference](docs/reference/rest-api.md), [REST quickref](docs/rest/QUICKREF.md), [OpenAPI source](docs/rest/openapi-source.md) |\n| System tray | [Cross-platform tray and Ubuntu setup](docs/guides/system-tray.md) |\n| Realtime voice chat | [Realtime guide](docs/guides/realtime.md) |\n| TTS and selectable ASR | [Voice/vision REST guide](docs/rest/endpoints/voice-vision.md), [Dashboard Voice page](docs/guides/dashboard.md#voice-and-asr) |\n| Sponsor and COHERE mesh | [Sponsor and COHERE guide](docs/guides/sponsor-and-cohere.md) |\n| Telegram bridge | [Telegram guide](docs/guides/telegram.md) |\n| Media generation | [Media guide](docs/guides/media-generation.md) |\n| Operations | [Runtime hygiene](docs/operations/runtime-hygiene.md), [Security and remote access](docs/operations/security-and-remote-access.md) |\n| Service compatibility | [Runtime version gate](docs/operations/version-compatibility.md) |\n| Architecture | [Architecture overview](docs/architecture/overview.md) |\n| Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |\n\n## Web Dashboard\n\n`omnius serve` exposes a self-contained operational dashboard at\n`http://127.0.0.1:11435/`. All pages use the same compact NOCLIP-derived style\ntokens and responsive observability-card grid, while keeping workspace, model,\nsession, run, service, and update state visible instead of hiding it behind\ndecorative pages.\n\n| Route | Purpose |\n| --- | --- |\n| `/chat` (`/`) | Stateful browser and imported TUI chats, full-history hydration, live run recovery, attachments, files, plan/context, and steering check-ins |\n| `/agent` | One-shot task contracts, personas/profiles, tool/isolation controls, run records, output, and events |\n| `/voice` | Voicechat, exact TTS model/options, clone references, ASR engine/model setup and activation, real-file ASR testing, transcript, and TTS testing |\n| `/generate` | Image/video/audio/music jobs, AV analysis, model/store controls, relocation progress, and global gallery |\n| `/projects` | Scan, register, rename, activate, and remove workspaces |\n| `/dashboard` (`/jobs`) | CPU/RAM/GPU/VRAM, processes, scheduler, services, usage, and verified updates |\n| `/activity` | Live run/tool/memory/engine event observability |\n| `/discover` | Agent bootstrap, capability intent search, and exact entry expansion |\n| `/settings` (`/config`) | Models, endpoints, voice, runtime, access, keys, appearance, and services |\n\nThe clickable sidebar brand opens the registered-workspace picker. Workspace\nselection scopes preferences, files, session history, chat pins/folders/search,\nand agent defaults. Chats, TUI visual history, and one-shot agent runs are\ndistinct records: `/quit`, `/exit`, manual-save noise, empty histories, and\nduplicate TUI transcripts are rejected from the chat projection; selecting a\nvalid session loads its full history and in-flight status from the daemon.\nThe chat top bar also reports the effective API base path and authentication\nmode. Streams retain split frames, Stop terminates the daemon-owned process\nlease, and assistant-provided web/file links stay inert until the daemon\nreturns a validation receipt.\n\nThe dashboard checks for updates every 10 seconds. An update button appears only\nfor a newer exact semver and drives `POST /v1/update`, then polls the durable\ntransaction until the global npm package, resolved executable, restarted daemon,\npackage/boot hashes, and tray runtime are reconciled. See the\n[complete dashboard guide](docs/guides/dashboard.md) for state ownership,\nsecurity, page-by-page behavior, and exact REST flows.\n\n## Terminal Over SSH\n\nThe TUI paints for a local terminal, where a full-area repaint costs nothing.\nOver a network the same cadence has to share the link with your keystrokes, so\nOmnius detects a remote session (`SSH_TTY` / `SSH_CONNECTION` / `SSH_CLIENT`)\nand paces itself: decorative chrome animates slower, a wheel-scroll burst is\ncollapsed into a single repaint, unchanged footer frames are not re-sent, and\nthe mouse filter allows more time for escape sequences split across packets.\nNothing changes about how the TUI looks, and local sessions are unaffected.\n\nDetection is environment-based, so it can miss a session where those variables\ndo not reach the process — most often tmux or mosh, whose panes may inherit a\nstale environment from the server. Force the profile when that happens:\n\n```bash\nOMNIUS_TUI_PACING=remote omnius   # pace for a network link\nOMNIUS_TUI_PACING=local omnius    # force local cadence\n```\n\nIf scrolling or typing still feels heavy, `OMNIUS_TUI_PROFILE=compatible`\nadditionally drops the animated truecolor chrome, and `OMNIUS_TUI_PERF=1` logs\nany content reflow that overruns its frame budget to stderr.\n\n## Shared Media Dependencies\n\nImage, video, audio, and music generation share a **single, system-wide dependency store** instead of duplicating heavy runtimes per project or per Telegram group.\n\nEarlier builds wrote a private Python venv plus Hugging Face / Torch / pip caches under every scoped working directory (for example `…/telegram-creative/<group-id>/.omnius/image-gen/.venv`). On a busy machine the same multi-gigabyte diffusers stack and model weights were re-downloaded once per group — tens of gigabytes of pure duplication.\n\nEverything now resolves to one source of truth under `~/.omnius` (override with `OMNIUS_HOME`):\n\n| Location | Holds |\n| --- | --- |\n| `~/.omnius/runtimes/<kind>/.venv-<backend>` | One shared Python venv per kind+backend (image/video/audio) |\n| `~/.omnius/models/huggingface/{hub,transformers,diffusers}` | Shared model weights — downloaded once, reused everywhere |\n| `~/.omnius/models/{torch,cache,pip-cache}` | Shared Torch hub, XDG, and pip caches |\n| `~/.omnius/models/_meta.json` | LRU usage index for automatic disk-pressure eviction |\n| `~/.omnius/media/{images,videos,audio,music}` | Global generated-media gallery (project-independent) |\n\nProject directories keep only lightweight session artifacts; no venvs or model weights are written per project.\n\n**Migrate and dedup existing machines.** A one-time cleanup consolidates any legacy per-group caches into the unified store — unique weights are moved (never re-downloaded), duplicates and stale venvs are reclaimed:\n\n```bash\n# TUI — current project only\n/models cleanup\n# TUI — every project + nested scoped group on this machine (dry-run first)\n/models cleanup --all --dry-run\n/models cleanup --all\n```\n\n```bash\n# REST — preview, then apply\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{\"dryRun\":true}'\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{}'\n# Inspect store + reclaimable legacy caches\ncurl -s localhost:11435/v1/media/store\n```\n\n**Generate over REST.** The daemon (default `127.0.0.1:11435`, a port in the IANA dynamic/private range that avoids common system-service collisions) exposes the local generators so any user on the machine can list models, generate, and browse the global gallery without the CLI:\n\n```bash\ncurl -s localhost:11435/v1/media/models\ncurl -s -X POST localhost:11435/v1/media/image -H 'content-type: application/json' -d '{\"prompt\":\"a compact robot painter\"}'\ncurl -s -X POST localhost:11435/v1/media/music -H 'content-type: application/json' -d '{\"prompt\":\"warm lo-fi piano loop\"}'\ncurl -s localhost:11435/v1/media/gallery\n```\n\nThe same surface drives the **Generate** tab in the web UI (`http://127.0.0.1:11435`) — pick a kind (image/video/audio/music), choose a model loaded from the system, generate, and review every previously generated file in one global gallery.\n\n## Recent Highlights\n\n- The dashboard now has nine route-level operational surfaces with shared modular observability grids, a searchable workspace picker, and project-scoped navigation state.\n- Chat history unifies persisted browser sessions with quality-filtered TUI transcripts, rejects command/noise sessions such as `/quit`, hydrates full history on selection, and exposes summaries, follow-up suggestions, reactive live deltas, and canonical deletion.\n- `/indicator` reconciles daemon ownership and health before launching the tray; the tray polls every 10 seconds and turns its version row into a retryable verified-update action only when an update exists.\n- Dashboard, tray, and TUI update actions now share an exact-version global transaction with live phase/output and package, executable, daemon, hash, restart, and tray verification.\n- TTS exposes GLaDOS, Overwatch, `luxtts:announcer-testchamber03`, and configurable Voicebox models; ASR independently exposes Whisper, managed `transcribe-cli`, Nemotron readiness, and pinned Microsoft VibeVoice ASR with Jetson/ARM64 CUDA-aware setup.\n- LuxTTS auto-setup on Jetson ARM64 requires CPU ONNX Runtime at import time, validates CUDA Torch separately against the host runtime, preserves existing caches during repair, and never substitutes generic PyPI Torch or automatic sudo for an AGX Orin deployment.\n- `/realtime` and REST `realtime: true` provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.\n- Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.\n- `/sponsor` can expose text inference and media generation for image, video, sound, and music with per-modality limits.\n- Sponsor and COHERE status surfaces now use shared telemetry concepts: concurrency, request rate, daily tokens, peer usage, model usage, and remote system metrics.\n- The TUI reports token production rate as `t/s`, supports Shift+Enter multiline input, and renders dynamic shell output inside bounded Unicode cards.\n- Telegram state is scoped by user and group, supports durable reply preferences, and feeds raw platform/tool failures back into the agent loop.\n- Telegram media ingress is byte- and duration-bounded, cache-only before routing, deduplicated by Telegram file identity, and evidence-gated after admission. Speech uses scoped transcription; music/general audio uses typed semantic or explicitly acoustic-only analysis without false listening claims.\n- Telegram public creative work now includes typed PDF/DOCX creation and hash-guarded review, fixed-operation FFmpeg audio editing, and root-confined image crop/resize/mask/composite workflows. Host-signed content capabilities bind review evidence and durable Telegram delivery to the exact artifact bytes.\n- Ollama pool cleanup now accounts for process groups and orphan runner processes that can keep VRAM pinned.\n- REST documentation is available both as human docs and as Omnius-discoverable docs skills.\n\n## REST API\n\nStart the daemon (default `http://127.0.0.1:11435`; interactive docs at `/docs`, machine spec at `/openapi.json`):\n\n```bash\nomnius serve\n```\n\nFor shared deployments, gate access with scoped bearer keys (`read` < `run` < `admin`):\n\n```bash\nOMNIUS_REST_API_KEYS=\"read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops\" omnius serve\n# then: Authorization: Bearer <key>\n```\n\nThe complete supported endpoint inventory follows. The canonical machine\ncontract is generated from [`packages/cli/src/api/openapi.ts`](packages/cli/src/api/openapi.ts),\nvalidated against [`docs/reference/rest-api.md`](docs/reference/rest-api.md),\nand projected into the generated block below. `pnpm docs:check` now fails when\nany of those three surfaces drift. Browser HTML pages, Swagger static assets,\nand implementation-only compatibility bridges are intentionally outside this\nstable REST contract.\n\n<!-- BEGIN GENERATED REST INVENTORY -->\n### Docs And Compatibility Aliases\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/docs` | Swagger UI |\n| `GET` | `/api/docs` | Swagger UI alias |\n| `GET` | `/openapi.json` | OpenAPI JSON |\n| `GET` | `/openapi.yaml` | OpenAPI YAML |\n| `GET` | `/v3/api-docs` | OpenAPI alias |\n| `GET` | `/swagger.json` | Swagger-era alias |\n| `GET` | `/api-docs` | OpenAPI alias |\n| `GET` | `/swagger-ui` | Swagger UI alias |\n| `GET` | `/redoc` | ReDoc renderer |\n| `GET` | `/` | HATEOAS API root when the client does not request HTML |\n| `GET` | `/help` | Compact daemon integration help |\n| `GET` | `/v1/routes` | Flat grep-friendly daemon route summary |\n| `GET` | `/routes` | Route-summary compatibility alias |\n| `GET` | `/asyncapi.json` | AsyncAPI 2.6 voicechat WebSocket contract |\n| `GET` | `/asyncapi` | AsyncAPI compatibility alias |\n\n### Health And Observability\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/health` | Liveness probe |\n| `GET` | `/health/ready` | Backend readiness |\n| `GET` | `/health/startup` | Startup probe |\n| `GET` | `/version` | Package version and platform |\n| `GET` | `/metrics` | Prometheus metrics |\n| `GET` | `/v1/events` | Server-sent event stream |\n| `GET` | `/v1/usage` | Token usage and rate limits |\n| `GET` | `/v1/audit` | Audit log query |\n| `GET` | `/v1/cost` | Cost tracker |\n| `GET` | `/v1/system` | CPU, RAM, GPU, and system snapshot |\n\n### Discovery\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/discovery/bootstrap` | Compact agent bootstrap and start-here map |\n| `GET` | `/v1/discovery` | Search layers, workflows, runtimes, modules, stores, and capabilities |\n| `GET` | `/v1/discovery/{id}` | Expand one stable capability entry |\n\n### Inference And Chat\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/models` | Aggregated model list |\n| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |\n| `POST` | `/v1/chat` | Stateful Omnius chat |\n| `POST` | `/api/chat` | Ollama-compatible chat alias |\n| `POST` | `/v1/generate` | Ollama-compatible one-shot generation |\n| `POST` | `/api/generate` | Ollama-compatible generate alias |\n| `POST` | `/v1/embeddings` | OpenAI-compatible embeddings |\n| `POST` | `/api/embed` | Ollama-compatible embeddings alias |\n| `GET` | `/api/tags` | Ollama-compatible model tags |\n| `POST` | `/realtime` | Text-only voice-adapter reply from a transcript |\n| `POST` | `/v1/realtime` | Auth-scoped realtime adapter alias |\n| `GET` | `/v1/chat/sessions` | Workspace-scoped persisted browser chats and importable TUI sessions |\n| `GET` | `/v1/chat/sessions/{id}` | Hydrate full session history, transcript, and in-flight state |\n| `DELETE` | `/v1/chat/sessions/{id}` | Permanently delete a canonical chat or TUI history session |\n| `POST` | `/v1/chat/sessions/{id}/summarize` | Generate + cache an inference-based session title/summary |\n| `POST` | `/v1/chat/suggest-followup` | Suggest one short next-message follow-up (ghost-text input) |\n| `GET` | `/v1/chat/sessions/{id}/status` | Reactive recall: live run status + unseen deltas (`?since=<seq>`) |\n| `POST` | `/v1/chat/sessions/{id}/pause` | Pause the exact daemon-owned chat generation at a safe admission boundary |\n| `POST` | `/v1/chat/sessions/{id}/resume` | Resume the exact paused daemon-owned chat generation |\n| `POST` | `/v1/chat/sessions/{id}/stop` | Stop the daemon-owned chat process lease; idle/terminal calls are idempotent |\n| `POST` | `/v1/chat/check-in` | Steering check-in for active chat |\n| `POST` | `/v1/chat/attachments` | Upload an attachment for a stateful chat |\n| `POST` | `/v1/links/validate` | Validate an external HTTP(S) destination under the daemon egress policy |\n\n#### Session History Contract\n\n`GET /v1/chat/sessions` is a history index, not merely a list of processes that\nare currently active. It returns canonical persisted browser chats for the\nselected workspace and, by default, quality-filtered TUI visual sessions that\ncan be imported on demand. Pass `?root=/absolute/workspace` to scope the list and\n`?include_tui=0` to omit TUI history. Exit-only inputs such as `/quit` and\n`/exit`, manual-save noise, empty transcripts, and duplicate normalized TUI\nsessions are rejected by the session-quality projection rather than presented as\nchats.\n\nSelecting a row should call `GET /v1/chat/sessions/{id}`. That response hydrates\nthe complete public message history (system prompts are intentionally omitted),\nthe original TUI transcript when applicable, token counts, timestamps, source\nand project identity, and any in-flight run with a bounded partial-output tail.\nUse the `status` endpoint with `?since=<seq>` for cheap reactive polling while a\nrun is active. `DELETE /v1/chat/sessions/{id}` is an admin operation and removes\nthe canonical record; deleting only a browser-side row does not remove daemon\nhistory.\n\nPause and resume use the exact session and active external-run identity. Both\noperations require `run` scope. An idle session returns `200`. An accepted\nrequest returns `200` with the lifecycle acknowledgement, owner generation,\ncurrent phase, resumability, and pending acknowledgement count. A lifecycle\nrejection returns `409`. A live owner that does not acknowledge within the\ncontrol deadline returns `504`. Clients must not treat a local UI pause as a\ndaemon pause.\n\n`POST /realtime` and `/v1/realtime` are text-only conversation adapters. They\naccept transcript text through `message`, `text`, `recent_turn`, `asr_text`, or\n`callerText`, optionally accept adapter-local `soul_md`, and can return plain\ntext with `Accept: text/plain` or `format: \"text\"`. ASR and TTS remain separate\noperations.\n\n### Agentic Runs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `POST` | `/v1/run` | Submit agentic task |\n| `GET` | `/v1/runs` | List runs |\n| `GET` | `/v1/runs/{id}` | Get run details |\n| `GET` | `/v1/runs/{id}/output` | Read captured run output and status |\n| `DELETE` | `/v1/runs/{id}` | Abort run |\n| `POST` | `/v1/todos` | Create or update todos for current session |\n| `GET` | `/v1/todos` | List sessions with todos |\n| `GET` | `/v1/todos/{session_id}` | Get session todos |\n| `DELETE` | `/v1/todos/{session_id}` | Delete session todos |\n| `POST` | `/v1/evaluate` | Evaluate a run |\n| `POST` | `/v1/index` | Trigger repository indexing |\n\n### Configuration, Keys, Profiles, Projects\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/config` | Read daemon config |\n| `PATCH` | `/v1/config` | Update daemon config |\n| `GET` | `/v1/config/model` | Current model |\n| `PUT` | `/v1/config/model` | Switch model |\n| `POST` | `/v1/config/model/check` | Probe model readiness with non-empty text |\n| `GET` | `/v1/config/endpoint` | Current endpoint |\n| `PUT` | `/v1/config/endpoint` | Switch endpoint |\n| `POST` | `/v1/config/endpoint/test` | Probe endpoint |\n| `GET` | `/v1/config/endpoint/history` | Endpoint history |\n| `DELETE` | `/v1/config/endpoint/history` | Remove endpoint history item |\n| `POST` | `/v1/share/generate` | Generate remote-access share URL |\n| `GET` | `/v1/keys` | List runtime API keys |\n| `POST` | `/v1/keys` | Mint runtime API key |\n| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime API keys by prefix |\n| `GET` | `/v1/profiles` | List tool profiles |\n| `POST` | `/v1/profiles` | Create tool profile |\n| `GET` | `/v1/profiles/{name}` | Get profile |\n| `DELETE` | `/v1/profiles/{name}` | Delete profile |\n| `GET` | `/v1/projects` | List known projects |\n| `DELETE` | `/v1/projects` | Unregister a project |\n| `GET` | `/v1/projects/current` | Current project |\n| `POST` | `/v1/projects/switch` | Switch project |\n| `POST` | `/v1/projects/register` | Register project |\n| `POST` | `/v1/projects/rename` | Rename project |\n| `GET` | `/v1/projects/preferences` | Read project preferences |\n| `PUT` | `/v1/projects/preferences` | Patch project preferences |\n| `DELETE` | `/v1/projects/preferences` | Reset project preferences |\n| `GET` | `/v1/projects/scan` | Scan configured roots for discoverable workspaces |\n| `GET` | `/v1/admin/access` | Read the daemon network access mode |\n| `POST` | `/v1/admin/access` | Change and persist access mode from loopback only |\n\n### Skills, Commands, Tools, MCP\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/skills` | List skills |\n| `GET` | `/v1/skills/{name}` | Load skill content |\n| `GET` | `/v1/commands` | List slash commands |\n| `POST` | `/v1/commands/{cmd}` | Execute slash command |\n| `GET` | `/v1/tools` | List tools (built-in + external) |\n| `POST` | `/v1/tools/register` | Register an application-specific external tool |\n| `GET` | `/v1/tools/{name}` | Tool metadata |\n| `DELETE` | `/v1/tools/{name}` | Unregister an external tool |\n| `POST` | `/v1/tools/{name}/call` | Call tool |\n| `POST` | `/v1/tools/{name}/eval` | Evaluate an external tool against test cases |\n| `GET` | `/v1/mcps` | List MCP servers |\n| `GET` | `/v1/mcps/{name}` | MCP server details |\n| `POST` | `/v1/mcps/{name}/call` | Call MCP tool |\n| `GET` | `/v1/hooks` | Hook registry |\n| `GET` | `/v1/agents` | Agent type registry |\n| `GET` | `/v1/codegraph/snapshot` | Code graph snapshot |\n| `GET` | `/v1/codegraph/events` | Code graph SSE |\n\n#### Registering Application-Specific Tools\n\nApplications can register their own tools so Omnius agents can discover and\ninvoke them alongside built-ins. `transport.type` selects the bridge:\n\n- `http` makes Omnius POST `{name, args, session_id}` to the application's\n  `callback_url` and relay the result.\n- `mcp` proxies to a named tool on an MCP server and can auto-connect from the\n  supplied connection descriptor.\n\nRegistrations persist per workspace at `.omnius/external-tools.json`, appear in\n`GET /v1/tools`, and use the same scope and off-device security gates as built-in\ntools. Registration needs `run` scope; a non-loopback caller needs `admin`.\n\n```bash\ncurl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{\n  \"name\": \"lookup_order\",\n  \"description\": \"Look up an order by id\",\n  \"parameters\": {\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}},\"required\":[\"id\"]},\n  \"security\": {\"requires_scope\":\"run\",\"risk\":\"low\"},\n  \"transport\": {\"type\":\"http\",\"callback_url\":\"https://app.internal/tools/lookup_order\",\"auth_header\":\"Bearer …\"}\n}'\ncurl -s localhost:11435/v1/tools/lookup_order\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{\"args\":{\"id\":\"A-1001\"}}'\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{\"cases\":[{\"name\":\"known\",\"args\":{\"id\":\"A-1001\"},\"expect\":{\"success\":true}}]}'\ncurl -s -X DELETE localhost:11435/v1/tools/lookup_order\n```\n\nThe MCP equivalent uses a transport such as\n`{\"type\":\"mcp\",\"server\":\"acme\",\"tool\":\"search\",\"connect\":{\"url\":\"https://app.internal/mcp\",\"transport\":\"streamable-http\"}}`.\n\n### AIWG\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aiwg` | AIWG root and control map |\n| `GET` | `/v1/aiwg/frameworks` | List frameworks |\n| `GET` | `/v1/aiwg/frameworks/{name}` | Framework details |\n| `GET` | `/v1/aiwg/frameworks/{name}/content` | Tier-aware content |\n| `GET` | `/v1/aiwg/skills` | List AIWG skills |\n| `GET` | `/v1/aiwg/skills/{name}` | Load AIWG skill |\n| `GET` | `/v1/aiwg/agents` | List AIWG agents |\n| `GET` | `/v1/aiwg/agents/{name}` | Load AIWG agent |\n| `GET` | `/v1/aiwg/addons` | List AIWG addons |\n| `POST` | `/v1/aiwg/use` | Tier-sized activation bundle |\n| `POST` | `/v1/aiwg/expand` | Expand matching AIWG item |\n\n### Memory, Sessions, Context\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/memory` | Memory backend summary |\n| `POST` | `/v1/memory/search` | Search memory |\n| `POST` | `/v1/memory/write` | Write memory |\n| `GET` | `/v1/memory/episodes` | List episodes |\n| `GET` | `/v1/memory/failures` | List failure records |\n| `POST` | `/v1/memory/ingest` | Ingest content or files into memory |\n| `GET` | `/v1/memory/entities` | List extracted memory entities |\n| `POST` | `/v1/memory/jobs/run` | Run a named memory-maintenance job |\n| `POST` | `/v1/memory/feedback` | Record relevance or quality feedback for a memory item |\n| `POST` | `/v1/memory/speaker-identities/enroll` | Admin-only, explicit-consent speaker exemplar enrollment in one exact vector space |\n| `POST` | `/v1/memory/speaker-identities/match` | Admin-only provisional speaker candidate matching without durable assignment |\n| `GET` | `/v1/sessions` | List task sessions |\n| `GET` | `/v1/sessions/{id}` | Get session history |\n| `GET` | `/v1/context` | Current context snapshot |\n| `GET` | `/v1/context/window-dumps` | List persisted outbound model context-window dumps |\n| `GET` | `/v1/context/window-dumps/{id}` | Fetch a full outbound model context-window dump |\n| `POST` | `/v1/context/save` | Save context entry |\n| `GET` | `/v1/context/restore` | Build restore prompt |\n| `POST` | `/v1/context/compact` | Request compaction |\n\nContext-window dumps are written before backend inference for main agents, sub-agents, internal runners, and adversary audits. Query\n`GET /v1/context/window-dumps?agent_type=main` for summaries with signal/noise\nmetrics, or fetch a full payload by id. Dumps include focus-supervisor state when\na next-action contract is active. Set `OMNIUS_CONTEXT_WINDOW_DUMP_DIR` to move\nthe store, `OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1` to disable it, and\n`OMNIUS_FOCUS_SUPERVISOR=off|auto|strict` to tune focus enforcement.\n\n### Files, Web, Nexus, Ollama Pool\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/files` | List workspace directory |\n| `POST` | `/v1/files/read` | Read workspace file |\n| `GET` | `/v1/files/raw` | Stream raw workspace bytes with content type and range support |\n| `HEAD` | `/v1/files/raw` | Inspect raw-file response metadata |\n| `GET` | `/v1/web/search` | Inspect web-search availability, schema, and security policy |\n| `POST` | `/v1/web/search` | Search the web directly through the Omnius tool runtime |\n| `GET` | `/v1/web/fetch` | Inspect web-fetch availability, schema, and security policy |\n| `POST` | `/v1/web/fetch` | Fetch a URL directly through the Omnius tool runtime |\n| `GET` | `/v1/web/crawl` | Inspect web-crawl availability, schema, and security policy |\n| `POST` | `/v1/web/crawl` | Crawl a website directly through the Omnius tool runtime |\n| `GET` | `/v1/nexus/status` | Nexus peer state |\n| `GET` | `/v1/sponsors` | Sponsor directory cache |\n| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |\n| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |\n\nThe `/v1/web/*` routes are stable aliases of the shared tool registry. `GET`\nreturns the corresponding tool metadata. `POST` uses the same authentication,\nprofile, origin, timeout, output-size, audit, and network-egress policy as a\ndirect tool call. Send search requests as\n`{\"args\":{\"query\":\"...\",\"num_results\":5,\"provider\":\"duckduckgo\"}}` and\nfetch requests as `{\"args\":{\"url\":\"https://example.com\"}}`. Crawl uses the\nschema returned by its `GET` route and requires the browser dependencies that\nthe metadata reports. POST responses use the standard `ToolResult` envelope.\n\n### Voice, Audio, Vision\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/voice/state` | Voice runtime status |\n| `POST` | `/v1/voice/start` | Select an optional model, enable voice, and wait for readiness |\n| `POST` | `/v1/voice/stop` | Pause daemon voice input while leaving TTS warm |\n| `GET` | `/v1/voice/models` | TTS models |\n| `POST` | `/v1/voice/models/switch` | Switch and enable an exact TTS model by default |\n| `POST` | `/v1/voice/models/{modelId}/pull` | Install runtime prerequisites and pull one managed TTS model |\n| `POST` | `/v1/voice/models/{modelId}/deploy` | Pull and deploy one managed CUDA TTS model |\n| `GET` | `/v1/voice/supertonic-settings` | Voice tuning settings |\n| `POST` | `/v1/voice/supertonic-settings` | Update voice tuning settings |\n| `GET` | `/v1/asr/engines` | Canonical ASR engines/models, capabilities, readiness, and selection |\n| `GET` | `/v1/asr/status` · `/v1/asr/selection` | Selected engine/model and runtime status |\n| `GET` | `/v1/asr/downloads` | List persistent ASR weight download and deployment transitions |\n| `POST` | `/v1/asr/downloads` | Start or resume an ASR weight download |\n| `GET` | `/v1/asr/downloads/{engineId}/{modelId}` | Poll one ASR download and deployment transition |\n| `POST` | `/v1/asr/downloads/{engineId}/{modelId}` | Start or resume this model download |\n| `POST` | `/v1/asr/downloads/{engineId}/{modelId}/retry` | Retry or resume a failed or interrupted ASR weight download |\n| `PATCH` | `/v1/asr/selection` | Persist and activate an exact engine/model |\n| `POST` | `/v1/asr/activate` | Activate and persist an exact engine/model |\n| `POST` | `/v1/asr/engines/{engineId}/setup` | Install a managed runtime and pinned weights |\n| `POST` | `/v1/asr/engines/{engineId}/models/{modelId}/pull` | Pull one exact ASR model and validate its managed runtime |\n| `POST` | `/v1/asr/engines/{engineId}/models/{modelId}/deploy` | Pull, select, and activate one exact ASR model |\n| `POST` | `/v1/asr/transcriptions` · `/v1/asr/test` | Transcribe/test using the real selected backend |\n| `GET` | `/v1/voice/asr-models` | Compatibility registry alias |\n| `POST` | `/v1/voice/asr-models/switch` | Compatibility activation alias |\n| `POST` | `/v1/voice/tts` | Synthesize speech |\n| `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |\n| `GET` | `/v1/audio/classify/health` | Jetson CUDA/TensorRT YAMNet readiness |\n| `POST` | `/v1/audio/classify/setup` | Provision and warm the pinned JetPack TensorRT YAMNet runtime |\n| `POST` | `/v1/audio/classify` | Direct-tool compatible CUDA audio classification |\n| `GET` | `/v1/audio/embed/health` | Role-typed embedding readiness (`?kind=acoustic|speaker|semantic`) |\n| `POST` | `/v1/audio/embed/setup` | Provision/warm one role-typed embedding runtime (admin; `?kind=...`) |\n| `POST` | `/v1/audio/embed` | Managed role-typed audio embedding (`?kind=...`) |\n| `GET` | `/v1/audio/diarization/live/readiness` | Non-mutating managed Sortformer worker readiness |\n| `POST` | `/v1/audio/diarization/live/setup` | Verify and warm a local Sortformer runtime (admin) |\n| `POST` | `/v1/audio/diarization/live` | Managed live/session-local speaker-turn diarization |\n| `POST` | `/v1/audio/diarization/live/cancel` | Terminate live worker work and clear its queue |\n| `GET` | `/v1/audio/diarization/reconcile/readiness` | Non-mutating managed Community-1 worker readiness |\n| `POST` | `/v1/audio/diarization/reconcile/setup` | Verify and warm a local Community-1 runtime (admin) |\n| `POST` | `/v1/audio/diarization/reconcile` | Managed offline/dream reconciliation proposals |\n| `POST` | `/v1/audio/diarization/reconcile/cancel` | Terminate reconciliation work and clear its queue |\n| `POST` | `/v1/voice/transcribe` | Transcribe audio |\n| `POST` | `/v1/voice/asr` | Legacy transcription alias |\n| `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |\n| `POST` | `/v1/voice/transcribe/stream` | Isolated final transcription over SSE (no shared mic state or fake partials) |\n| `POST` | `/v1/voice/clone-refs` | Upload voice clone reference |\n| `GET` | `/v1/voice/clone-refs` | List clone references |\n| `POST` | `/v1/voice/clone-refs/upload` | Upload clone reference |\n| `POST` | `/v1/voice/clone-refs/from-url` | Fetch clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/activate` | Activate clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/rename` | Rename clone reference |\n| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |\n| `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |\n| `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |\n| `POST` | `/v1/vision/describe` | Vision describe placeholder |\n| `GET` | `/v1/vision/embed/readiness` | Non-mutating isolated OpenCLIP readiness |\n| `POST` | `/v1/vision/embed/setup` | Explicit isolated OpenCLIP setup (admin scope) |\n| `POST` | `/v1/vision/embed` | Create a vision embedding from media |\n| `GET` | `/v1/ocr/readiness` | Non-mutating advanced-OCR dependency and backend readiness |\n| `POST` | `/v1/ocr/setup` | Create and verify the isolated OCR venv (admin scope) |\n| `POST` | `/v1/ocr/advanced` | Agent-equivalent managed advanced OCR (alias of `/v1/tools/ocr_image_advanced/call`) |\n\n`POST /v1/voice/tts` and `/v1/audio/speech` automatically warm the daemon.\nAn explicit model must render exactly or the request fails; Omnius does not\nsilently synthesize with another voice. Responses include `X-Voice-Model`,\n`X-Voice-Backend`, and `X-Sample-Rate`. Available models include GLaDOS,\nOverwatch, `luxtts:announcer-testchamber03`, and the selected Voicebox suite.\nSet `OMNIUS_VOICEBOX_MODELS=all` for every carried-in Voicebox model, leave it\nat `stable` for the default set, or provide a comma-separated subset.\n\nASR selection is independent from TTS selection. The registry currently exposes\nOpenAI Whisper, managed `transcribe-cli`, NVIDIA Nemotron (reported unavailable\nuntil its legacy bootstrap is migrated), and Microsoft VibeVoice ASR. VibeVoice\nuses the exact pinned `microsoft/VibeVoice-ASR` checkpoint, reports setup and\nactivation separately, supports completed files up to 60 minutes with speakers,\ntimestamps, and `?context=` hotwords, and is deliberately not advertised as an\nincremental PCM backend. Its managed setup inherits the host CUDA-enabled Torch\nbuild (needed on Jetson/ARM64), never installs generic PyPI Torch, and activation\nrequires one explicit capable GPU. Discrete Linux uses `nvidia-smi` process/GPU\nevidence; Jetson/L4T uses NVIDIA's documented `tegrastats` plus CUDA Torch device\nproperties because `nvidia-smi` is unavailable there. Model weights live under\nthe unified Omnius ASR cache and are not shipped in the npm package.\n\n### Generative Media\n\nAll generation is backed by the unified `~/.omnius` model store and shared venvs (single source of truth — no per-project duplication). Generated files are consolidated into the global gallery at `~/.omnius/media/{images,videos,audio,music}`.\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/media/models` | List available image/video/audio/music models |\n| `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |\n| `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |\n| `POST` | `/v1/media/relocate` | Relocate the whole media store (weights/venvs/gallery) to a chosen folder |\n| `GET` | `/v1/media/relocate/status` | Status + progress of the media-store relocation job |\n| `POST` | `/v1/media/av/analyze` | Analyze a media file into a grounded entity/event answer (AV comprehension) |\n| `POST` | `/v1/media/image` | Generate an image |\n| `POST` | `/v1/media/video` | Generate a video |\n| `POST` | `/v1/media/audio` | Generate a sound effect |\n| `POST` | `/v1/media/music` | Generate music |\n| `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |\n| `GET` | `/v1/media/file` | Stream one generated media file |\n\nManaged TTS `pull` installs the model's runtime prerequisites and weights. It\ndoes not start inference. Managed TTS `deploy` also verifies the selected CUDA\ndevice and starts the persistent runtime. Both operations return `200` when\nready, `404` when the model has no matching managed adapter, and `500` when\ninstallation, download, CUDA preflight, or startup fails.\n\nASR download requests use `{engineId, modelId, device?}`. A collection POST\nreturns `200` when weights are ready or `202` with `statusUrl`, `retryUrl`, and\n`pollAfterMs` while work is pending. Duplicate work coalesces. Poll the model\nURL until its download is ready and its deployment is active. A missing job\nreturns `404`. Model-specific POST and retry requests return `200` when ready or\n`202` when accepted. The model `pull` and `deploy` routes accept optional\n`{device}`. Pull validates the managed runtime and CUDA placement. Deploy also\npersists the selection after readiness and returns a pollable `202` transition\nwhen activation is pending.\n\n### Engines And Scheduled Jobs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/engines` | Long-running engine status |\n| `GET` | `/v1/services` | List all active daemon-owned REST services and their routes |\n| `GET` | `/v1/services/{id}` | Get one daemon-owned REST service contract |\n| `GET` | `/v1/scheduled` | List scheduled jobs |\n| `DELETE` | `/v1/scheduled/all` | Delete all tasks, timers, cron entries, and persisted sources |\n| `GET` | `/v1/scheduled/status` | Scheduler status |\n| `POST` | `/v1/scheduled/{id}` | Enable or disable one scheduled task or user timer |\n| `DELETE` | `/v1/scheduled/{id}` | Delete one scheduled task or user timer |\n| `POST` | `/v1/scheduled/kill` | Kill scheduled job |\n| `POST` | `/v1/scheduled/fixup` | Reconcile scheduled state |\n| `GET` | `/v1/scheduled/reconcile` | Preview scheduled reconciliation |\n| `POST` | `/v1/scheduled/reconcile` | Preview or apply scheduled reconciliation |\n| `GET` | `/v1/services/systemd` | Systemd service status |\n| `POST` | `/v1/services/systemd/{unit}` | Act on one user-level systemd unit |\n| `GET` | `/v1/update` | Self-update status |\n| `POST` | `/v1/update` | Start an exact-version verified global update transaction |\n\n`GET /v1/services` is the agent-readable service inventory generated from the\nOpenAPI document. Each entry states lifecycle ownership, interactive-session\ndependency, registered routes, and a readiness or status route when one exists.\n`GET /v1/services/{id}` returns one service contract or `404` for an unknown\nservice ID. These discovery routes do not mutate services. `/listen` and\n`/hangup` control voice sessions only and do not own the REST daemon.\n\n#### Verified Global Update Transaction\n\n`POST /v1/update` is not a CLI-local package edit. It starts one durable\ntransaction that installs the requested exact npm version globally, verifies\nthe installed package and resolved `omnius` executable, restarts and verifies\nthe daemon, verifies package/hash/runtime agreement, and relaunches the tray if\nit was running. The response is `202` with operation state; poll\n`GET /v1/update` for live phase, subprocess output, verification evidence, and\nthe final success or failure. Concurrent transactions and requests with no\navailable target return `409`.\n\nThe web dashboard and native tray both use this same endpoint. Update discovery\nis shared and semver-aware, so an older cached registry result cannot downgrade\nor falsely present an update. A completed transaction means the global package,\nexecutable, daemon, and tray runtime were all reconciled—not merely that `npm`\nexited successfully.\n\n### AIMS Governance\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aims` | AIMS root and endpoint index |\n| `GET` | `/v1/aims/policies` | Policy register |\n| `PUT` | `/v1/aims/policies` | Replace policy register |\n| `GET` | `/v1/aims/roles` | Roles and responsibilities |\n| `GET` | `/v1/aims/resources` | Resource inventory |\n| `GET` | `/v1/aims/impact-assessments` | Impact assessments |\n| `POST` | `/v1/aims/impact-assessments` | File impact assessment |\n| `GET` | `/v1/aims/lifecycle` | Lifecycle state |\n| `GET` | `/v1/aims/data-quality` | Data quality controls |\n| `GET` | `/v1/aims/transparency` | Model cards and transparency |\n| `GET` | `/v1/aims/usage` | AIMS usage view |\n| `GET` | `/v1/aims/suppliers` | Supplier inventory |\n| `GET` | `/v1/aims/incidents` | Incident records |\n| `POST` | `/v1/aims/incidents` | File incident |\n| `GET` | `/v1/aims/oversight` | Human oversight gates |\n| `GET` | `/v1/aims/decisions` | Consequential decision log |\n| `GET` | `/v1/aims/config-history` | Config change history |\n\n### Browser And Compatibility Surfaces\n\nThe dashboard HTML routes (`/`, `/chat`, `/agent`, `/voice`, `/generate`,\n`/projects`, `/dashboard`, `/jobs`, `/activity`, `/discover`, `/settings`, and\n`/config`) are documented in the [dashboard guide](../guides/dashboard.md). They\nare pages, not JSON API operations; `/` returns the HATEOAS JSON root when the\nclient does not request HTML.\n\nSwagger/ReDoc trailing-slash variants, `/api/docs/*` static assets, and\n`/favicon.ico` exist for browsers. They are delivery details rather than stable\nintegration endpoints. The daemon also retains browser/legacy bridges at\n`/v1/model`, `/v1/endpoint`, `/v1/theme`, `/v1/tor/*`, `/v1/remote-proxy`, and\n`/v1/command`. New clients should prefer `/v1/config/model`,\n`/v1/config/endpoint`, `/v1/config`, and `/v1/commands/{cmd}`. Compatibility\nhandlers may accept additional HTTP verbs for old dashboard bundles; only the\nmethods in the supported inventory above are contractual.\n<!-- END GENERATED REST INVENTORY -->\n## Agent-Explorable Documentation\n\nOmnius discovers project-local docs skills from `.aiwg/addons/*/skills`. The docs bundles in this repo expose high-signal entrypoints for agents:\n\n```text\n/skills omnius docs\nskill_execute name=\"omnius-docs\"\nskill_execute name=\"omnius-rest-docs\"\nskill_extract name=\"omnius-realtime-docs\" query=\"How does realtime REST mode work?\"\n```\n\nThe intended pattern is index first, targeted document second, not loading the whole manual into the active context.\n\n## Development\n\n```bash\npnpm install\npnpm -r build\npnpm docs:check\n```\n\nFocused checks used for the docs skill surface:\n\n```bash\npnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts\npnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts\n```\n\n## Publishing\n\nPublish only from `publish/`.\n\n```bash\ncd omnius\npnpm -r clean || true\nfind . -name 'tsconfig.tsbuildinfo' -not -path '*/node_modules/*' -delete\npnpm -r build\nnode scripts/build-publish.mjs\ncd publish\nmkdir -p .npm-cache\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm pack --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\n```\n\nBefore publishing, verify `README.md`, `package.json`, `dist/index.js`, and `dist/launcher.cjs` are in the tarball, and that `package.json` includes `readmeFilename: \"README.md\"` plus a string `readme`.\n\n## License\n\nOmnius is released under [CC-BY-NC-4.0](LICENSE) for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.\n"
 }