{"id":"20ccee04-426e-4669-86e0-0f5d30f2f5a6","slug":"nemofold","kind":"mcp","name":"NemoFold","summary":"Private, evidence-first document agent with persistent local memory, exact citations, reversible actions, and bounded Nemotron reasoning.","owner":"ellmos-ai","repoUrl":"https://github.com/ellmos-ai/NemoFold","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-30T04:56:55.000Z","addedAt":"2026-10-21T05:04:01.398Z","logoUrl":"https://avatars.githubusercontent.com/u/266164959?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","memory-knowledge","cloud-infra"],"tags":["ai-agents","document-analysis","hackathon","local-first","nebius","nemotron","nvidia","personal-ai"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T00:42:32.553Z","sample":false,"url":"https://conduits.dev/tools/nemofold","language":"Python","transports":["stdio"],"install":{"pypi":"nemofold"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# NemoFold\n\nEnglish | [Deutsch](README_de.md)\n\n[](https://youtu.be/wOToLqDBvvE)\n\n**Demo video (2:16):** https://youtu.be/wOToLqDBvvE · built for the Nebius x NVIDIA Global AI Hackathon\n\n**Judge test build:** [download it from the latest release](https://github.com/ellmos-ai/NemoFold/releases/latest), unpack the ZIP and\nfollow its `README.txt` (no account or API key needed); details in\n[Installation & Quick Start](#7-installation--quick-start).\n\n[](NOTICE)\n[](pyproject.toml)\n[](https://github.com/ellmos-ai/NemoFold/actions/workflows/ci.yml)\n[](https://github.com/ellmos-ai/NemoFold/actions/runs/38366200345)\n[-blue.svg)](.github/workflows/ci.yml)\n[%20%7C%20macOS%20(mypy)-lightgrey.svg)](.github/workflows/ci.yml)\n[](#sec-05)\n[](SECURITY.md)\n[](LICENSE)\n[](THIRD_PARTY_LICENSES.md)\n[](THIRD_PARTY_LICENSES.txt)\n[](https://github.com/ellmos-ai)\n[](https://github.com/open-bricks)\n[](llms.txt)\n\n\n\n## 1. Overview & Core Mission\n\n**Turn documents into data. NemoFold puts your knowledge to work.**\n\nNemoFold adapts to your use cases — a growing library, not fine-tuning.\n\nNemoFold is a private, evidence-first document agent. It turns explicitly approved\nfolders into a persistent working memory, keeps claims traceable to source locations,\nand makes file actions reversible.\n\nWorking tagline: **Your files. Your rules. Your agent.**\n\nThis repository is the competition implementation for the Nebius x NVIDIA Global\nAI Hackathon. The local core is deliberately usable without a cloud account. The\nNemotron-on-Nebius integration is proven by a real, sanitized Token Factory run whose\ncomplete receipt chain is committed under `examples/proven-run/` and can be re-verified\noffline (see [Section 11](#11-approved-nebius-token-factory-run)).\n\nIts document workflows are compositions of four shared primitives: schema-bound\nfield extraction, deduplication that keeps what it strikes, section-wise merging with\nvisible conflicts, and a delta against a named snapshot. Because those primitives are\nshared rather than private to one workflow, the same building blocks can be chained\nfor a case nobody has written a workflow for yet.\n\nIt adapts to your use cases in two honest ways: the Captain's Desk plans new\ncombinations of existing primitives from one plain sentence, and every prepared plan\nbecomes a reusable draft. That is the whole learning story - a growing library of\nuse cases, not a model that trains on your files. Nothing is fine-tuned, and nothing\nabout your documents leaves the host unless you approve that specific transfer.\n\nThe same core serves both ends of the range: everyday work on a laptop with a small\nlocal model, and a data analyst pointing Nemotron on Nebius Token Factory at a large\ncorpus. The evidence contract does not change between them - only the worker does.\n\n---\n\n## Quick Navigation\n| # | Section | Description |\n|:---:|:---|:---|\n| 1 | [Overview & Core Mission](#1-overview--core-mission) | Evidence-first document agent, local memory, and core value proposition |\n| 2 | [Visual Architecture & Dual Diagrams](#2-visual-architecture--dual-diagrams) | Topology flowchart & end-to-end evidence lifecycle sequence diagram |\n| 3 | [Target Personas & Discoverability](#3-target-personas--discoverability) | 4 user personas ([PERSONA-01] to [PERSONA-04]) & high-intent search queries |\n| 4 | [Comparative Matrix vs. Alternatives](#4-comparative-matrix-vs-alternatives) | 10-dimension architectural matrix against 4 industry alternatives |\n| 5 | [Governance & Runtime Invariants](#5-governance--runtime-invariants) | Core security guarantees: INV-LOCAL-01 through INV-SLA-10 |\n| 6 | [Implemented Document Workflows](#6-implemented-document-workflows) | 44 production-ready workflows built from 4 shared primitives |\n| 7 | [Installation & Quick Start](#7-installation--quick-start) | Environment setup, editable install, and CLI verification |\n| 8 | [Offline Proof & Verification](#8-offline-proof--verification) | Local synthetic corpus verification, zero cloud proof, fail-closed path |\n| 9 | [Executing Real Local Jobs](#9-executing-real-local-jobs) | Single-command workflow execution with preview and rollback |\n| 10 | [Provider Adapters, MCP & API](#10-provider-adapters-mcp--api) | Ollama, LM Studio, Claude Code, OpenAI, Anthropic & stdio MCP server |\n| 11 | [Approved Nebius Token Factory Run](#11-approved-nebius-token-factory-run) | Hackathon competition benchmark, NemoClaw package, verified tokens |\n| 12 | [Voyage Library & Captain's Desk](#12-voyage-library--captains-desk) | Plain-sentence natural intent parsing into dry-run reusable drafts |\n| 13 | [Case Chronicle Deep Analysis](#13-case-chronicle-deep-analysis) | Multi-stage chronological dossiers, incident analysis, timeline tracking |\n| 14 | [Structured Sources & Controlled Output](#14-structured-sources--controlled-output) | CSV/JSON ingestion, sanitized web boundary, Controlled Email drafting |\n| 15 | [Checking, Comparing & Composing](#15-checking-comparing--composing) | Reference check, Rater Race, Guide Compose, Wiki Export, Pattern Mining |\n| 16 | [Local Web Console & Routes](#16-local-web-console--routes) | Area routing (`/folders`, `/processes`, `/governance`, `/connections`) |\n| 17 | [Sibling Ecosystem & Integration](#17-sibling-ecosystem--integration) | Cross-reference table for 10 public sister repositories in ellmos-ai, dev-bricks and doc-bricks |\n| 18 | [Transparency, Licenses & Security Policy](#18-transparency-licenses--security-policy) | Dependency audit, zero-copyleft guarantee, 48h response target |\n\n---\n\n\n\n## 2. Visual Architecture & Dual Diagrams\n\n### System Architecture Topology\n\n```mermaid\nflowchart TB\n subgraph Intake[\"1. Ingestion & Structured Sources Layer\"]\n DOCS[\"Local Corpus
(PDF, DOCX, ODT, TXT, CSV, JSON)\"]\n MAILS[\"Mail-to-Case Intake
(Read-Only RFC-822 .eml)\"]\n WEB[\"Gated Web Sources
(Sanitized HTML, Domain Boundary)\"]\n end\n\n subgraph Memory[\"2. Local Memory & Persistent Index\"]\n FTS[\"SQLite FTS5 Full-Text Store
(BM25 Ranking, Token Offsets)\"]\n REG[\"Document Registry
(Declared Field Columns, Exact Locators)\"]\n RESOLV[\"Version Resolver
(Family Snapshot, Semantic Diffs)\"]\n end\n\n subgraph Governance[\"3. Trust Boundary & Governance Gates\"]\n ROOTS[\"Approved Roots Policy
(Fail-Closed Directory Boundaries)\"]\n GATES[\"Execution Gates
(File Actions, External Models, Budget Ceiling)\"]\n RUNAS[\"User Space Boundary
(runs as a regular user, no administrator rights)\"]\n end\n\n subgraph CoreEngine[\"4. Core Engine & Shared Primitives\"]\n DESK[\"Captain's Desk
(Natural Intent to Reusable Voyage)\"]\n PRIM1[\"Primitive 1: Field Extraction
(Schema-Bound Parsing)\"]\n PRIM2[\"Primitive 2: Fact Distill
(Deduplication with Omitted Appendix)\"]\n PRIM3[\"Primitive 3: Synopsis Merge
(Sectional Synthesis with Conflict Blocks)\"]\n PRIM4[\"Primitive 4: Snapshot Delta
(Continuous Folder Digest)\"]\n JOURNAL[\"Reversible Action Journal
(Preview, Atomic Apply, Instant Undo)\"]\n end\n\n subgraph Surfaces[\"5. Delivery, MCP & Console Surfaces\"]\n WEBAPP[\"Local Web Console
(Loopback 127.0.0.1:8765, Area Routes)\"]\n MCPSRV[\"Stdio MCP Server
(nemofold-mcp Tool Provider)\"]\n CLI[\"CLI Toolset
(Strict nemofold.job.v1 Parser)\"]\n REPORTS[\"Artifact Studio
(SHA-256 Ledger, Markdown, PDF, DOCX)\"]\n end\n\n Intake --> Memory\n Memory --> Governance\n Governance --> CoreEngine\n CoreEngine --> Surfaces\n```\n\n### Evidence-Grounded Workflow Lifecycle\n\n```mermaid\nsequenceDiagram\n autonumber\n actor User as \"Operator / Analyst\"\n participant Desk as \"Captain's Desk / CLI\"\n participant Gate as \"Privacy & Policy Gate\"\n participant Engine as \"Local Extractor & FTS5\"\n participant Verifier as \"Evidence Verifier\"\n participant Journal as \"Action Journal\"\n participant Artifacts as \"Artifact Studio\"\n\n User->>Desk: Submit natural goal or job contract (\"nemofold.job.v1\")\n Desk->>Gate: Validate approved roots, zero spend, and privacy mode\n Gate-->>Desk: Authority confirmed (Fail-Closed if path outside root)\n Desk->>Engine: Ingest corpus (PDF, DOCX, ODT, TXT, EML) & build index\n Engine-->>Verifier: Return candidate segments with exact line/page locators\n Verifier->>Verifier: Check byte-exact verbatim match against source text\n alt Citation Verified\n Verifier-->>Journal: Record cited findings with verbatim quote\n else Discrepancy or Conflict Found\n Verifier-->>Journal: Mark explicit conflict block or omission appendix\n end\n alt File Action Requested (e.g. Smart Inbox / Naming)\n Journal->>User: Render pre-flight diff preview\n User->>Journal: Confirm execution (--approve-actions)\n Journal->>Journal: Apply atomic mutation & write SHA-256 undo receipt\n end\n Journal->>Artifacts: Export structured dossier (MD, JSON, PDF, DOCX)\n Artifacts-->>User: Present verifiable report with reproducible audit ledger\n```\n\n---\n\n\n\n## 3. Target Personas & Discoverability\n\n### Target Personas\n\n- **[PERSONA-01] Legal, Compliance & Due Diligence Analysts**\n - *Context:* Reviewing voluminous corporate contracts, disclosures, M&A dataroom records, and compliance checklists.\n - *Pain Point:* Commercial cloud AI tools ingest confidential filings into remote multi-tenant servers; LLM hallucinations invent clauses without verifiable source citations.\n - *Solution:* 100% offline analysis; claims require byte-exact verbatim citations with exact line and page locators; a checkmark without a quote is rejected as an opinion.\n\n- **[PERSONA-02] Enterprise Privacy Officers & Knowledge Managers**\n - *Context:* Governing sensitive enterprise folders, internal HR records, healthcare dossiers, and intellectual property files.\n - *Pain Point:* Uncontrolled scripts accidentally overwrite or misplace files; cloud synchronization triggers GDPR/HIPAA cross-border breach liabilities.\n - *Solution:* Strict local allow-root boundary; path-free sanitized packaging; reversible file mutations with preview, resume, and instant journaled rollback.\n\n- **[PERSONA-03] Autonomous Agent & Local LLM Developers**\n - *Context:* Integrating document intelligence into offline agent architectures, local desktop tools, or MCP tool orchestrations.\n - *Pain Point:* Fragile agent frameworks leak system paths into prompts, lack reproducible execution receipts, and bundle complex cloud dependencies.\n - *Solution:* Standards-compliant stdio MCP server (`nemofold-mcp`), provider-neutral adapter core (Ollama, LM Studio, Claude Code, OpenAI), finite budget guards, and reproducible Nebius Token Factory run proofs.\n\n- **[PERSONA-04] Investigative Journalists, Researchers & Evidence Curators**\n - *Context:* Investigating massive document leaks, public records, and conflicting historical testimonies.\n - *Pain Point:* Manual cross-referencing is slow; conventional summarizers suppress dissenting voices and silently discard duplicate evidence.\n - *Solution:* 44 specialized workflows including Fact Distill (deduplicates while archiving struck occurrences in a dedicated appendix) and Synopsis Merge (highlights conflicting narratives as explicit conflict blocks).\n\n### High-Intent Search Queries\n\n| Query Phrase | Target User Intent |\n|:---|:---|\n| `private local document agent evidence citation` | Analysts searching for offline, zero-leakage document reasoning tools |\n| `open source reversible file action agent` | Developers requiring safe, journaled file organization with rollback |\n| `offline document fts search quote verification` | Knowledge workers needing SQLite FTS5 exact quote verification |\n| `mcp document server local first python` | Agent developers seeking stdio MCP servers for document search |\n| `nebius nvidia nemotron local document analysis` | Teams benchmarking Nemotron models via Nebius Token Factory |\n\n---\n\n\n\n## 4. Comparative Matrix vs. Alternatives\n\n| Evaluation Dimension | NemoFold (v0.2.1) | Cloud AI Assistants (Copilot / NotebookLM) | Desktop Search Tools (DocFetcher / Copernic) | Agent Frameworks (LangChain / LlamaIndex) | Invariant Mapping |\n|:---|:---:|:---:|:---:|:---:|:---:|\n| **1. Execution Boundary** | **Local-First by default / cloud opt-in** | Cloud Ingestion Mandatory | 100% Local | Mixed / Cloud Default | `INV-LOCAL-01` |\n| **2. Citation Rigor** | **Verbatim Byte-Exact Quote Verification** | Probabilistic Synthesis | Raw Text Snippets Only | Prompt-Dependent Hallucinations | `INV-EVID-02` |\n| **3. File Action Safety** | **Reversible Journal / Undo / Resume** | Read-Only (No File Actions) | Manual File Operations | Unchecked Shell Tool Calls | `INV-ACTION-03` |\n| **4. Approval Gates** | **Multi-Tier (Local / Remote / Spend)** | Implicit Cloud Upload | N/A (No Automation) | Often Ungated Auto-Execution | `INV-GATE-04` |\n| **5. Package Sanitization** | **Path-Free / Hash-Verified Packages** | Raw File Transmission | N/A | Variable / Host Leaks Common | `INV-ISOL-05` |\n| **6. Attack Surface** | **Loopback-Only (127.0.0.1)** | Public Multi-Tenant SaaS | Local GUI Only | Often Exposed HTTP Endpoints | `INV-PROV-06` |\n| **7. Workflow Architecture** | **4 Primitives / 44 Workflows** | Monolithic Chat Interface | Keyword Search Index | Complex Dynamic Graphs | `INV-POLICY-07` |\n| **8. Privilege Boundary** | **Regular user, no admin rights** | Browser Sandbox | Standard User Space | Often Demands Root/Sudo | `INV-RUNAS-08` |\n| **9. Auditability** | **Cryptographic SHA-256 Ledgers** | Proprietary Session Log | Minimal Plaintext Log | Transient Memory Dumps | `INV-DET-09` |\n| **10. Vulnerability SLA** | **48h Ack / 5d Triage (target)** | Enterprise Support Contract | Volunteer / Inactive | Best-Effort GitHub Issues | `INV-SLA-10` |\n\n---\n\n\n\n## 5. Governance & Runtime Invariants\n\nNemoFold enforces ten architectural invariants across all workflows, CLI commands, and MCP surfaces:\n\n| Invariant ID | Name | Architectural Guarantee | Compliance Verification |\n|:---:|:---|:---|:---:|\n| **INV-LOCAL-01** | Local-First by default; cloud transfer only on explicit approval | Original documents, absolute paths, FTS index, policies, and ledger remain strictly local on host; zero automatic telemetry. | Verified in `tests/` |\n| **INV-EVID-02** | Byte-Exact Evidence Citation | Claims accepted only when verbatim quotes match source text byte-for-byte; line and page locators preserved. | Verified in `tests/unit/test_evidence_analyst.py` |\n| **INV-ACTION-03** | Reversible Actions & Journaled Undo | File mutations require pre-flight dry-run, atomic commit, and provide full reversible undo and resume via run journal. | Verified in `tests/unit/test_journal.py` |\n| **INV-GATE-04** | Multi-Tier Explicit Approval Gates | File actions, external model transfers, cloud spend ceilings, and network exposure require explicit operator flags. | Verified in `tests/unit/test_gates.py` |\n| **INV-ISOL-05** | Path-Free Sanitized Packaging | Outbound packages strip host paths, secrets, symlinks, and unapproved files; preflight validates package before network transit. | Verified in `tests/unit/test_package_validator.py` |\n| **INV-PROV-06** | Provider-Neutral Loopback Surface | Pluggable local and remote backends; unauthenticated interfaces and Captain's Desk restricted strictly to loopback (127.0.0.1). | Verified in `tests/e2e/test_webapp.py` |\n| **INV-POLICY-07** | Composable Primitives & Voyages | 4 shared primitives compose 44 document workflows; reusable voyage drafts adapt without model fine-tuning. | Verified in `tests/unit/test_primitives.py` |\n| **INV-RUNAS-08** | Unprivileged User Mode | Runs as a regular user; requests no administrator rights; no system daemon required. | Documented in `SECURITY.md` |\n| **INV-DET-09** | Deterministic Artifacts & Ledgers | Deterministic SVG figures, structured reports, and cryptographic SHA-256 run ledgers guarantee reproducible audit trails. | Verified in `tests/unit/test_report_studio.py` |\n| **INV-SLA-10** | 48h Security & Triage SLA | Target: security vulnerability disclosures acknowledged within 48h; triage and remediation assessment within 5 business days. | Stated target in `SECURITY.md` |\n\n---\n\n\n\n\n## 6. Implemented Document Workflows\n\n`SUPPORTED_WORKFLOWS` registers 44 job contracts; in the console each one is an\n**action** (a single step), while a **workflow** is a chain of two or more actions\n([Section 16](#16-local-web-console--routes)). The founding sixteen are below;\nCase Chronicle deep analysis adds seven more ([Section 13](#13-case-chronicle-deep-analysis)),\nthe checking/comparing/composing set adds seven ([Section 15](#15-checking-comparing--composing)),\nand fourteen further gate-verified structured-source, web, export and specialist workflows\nare listed in the second table further down (16 + 7 + 7 + 14 = 44).\n\n| Workflow | Local result |\n|---|---|\n| Smart Inbox | Extension-based routing plan, all-or-nothing collision gate, journaled moves, resume and undo |\n| Naming, Format & Retention | Rule resolution, naming/retention checks, dry-run, reversible move/copy, and TXT/MD/RST conversion copies |\n| Cleanup Rules | Manual bulk routing plus readable suggestions learned only from explicit corrections; suggestions never activate themselves |\n| Mail-to-Case | Read-only local EML intake, source-grounded case dossier, manifest, and hash-recorded attachment extraction |\n| Controlled Email | Local RFC 822 draft and exact approval digest; send requests fail closed without immediate confirmation and a proven server adapter |\n| Universal Bundle | Deterministic text bundle, manifest, ZIP, hashes, and explicit unsupported/unreadable entries |\n| Continuous Folder Digest | Persistent inventory snapshots with new, changed, unchanged, and deleted source IDs |\n| Evidence Analyst | Persistent SQLite FTS index, multiple questions, exact quotes, source catalog, line/page locations, coverage and reports |\n| Version Resolver | Per-family resolution, explicit validity/date/version priority, named file-time fallback, and line comparison |\n| Contact Monitor | Source-quoted contact and responsibility candidates, named snapshot comparison, and no automatic deletion |\n| Report & Artifact Studio | A validated analysis contract rendered to Markdown, TXT, PDF, DOCX, and ODT |\n| Document Registry | Declared columns extracted from every approved document into one table; each filled cell keeps its source and line, an unanswered cell stays empty, exported as JSON, CSV and the full report family |\n| Fact Distill | Quotable sentences per source with repeated statements struck from the findings and every struck occurrence kept visible in its own appendix |\n| Synopsis Merge | Section-wise merge of several documents with a source anchor per paragraph and disagreeing labels shown as conflict blocks instead of a silent choice |\n| Daily Arrivals | Comparison against a named snapshot with name, size, time and short content per new file, the owner where the platform can name one, and a task file you install yourself |\n| NemoClaw skill package & Token Factory proof | Path-free, hashed job packages plus a fail-closed Nebius Token Factory adapter and independently verifiable result receipt; proven by a real Token Factory run committed under `examples/proven-run/` |\n\n### Gate-verified structured-source, web & specialist workflows\n\nFourteen more workflows were built against the Ellmos use-case acceptance gates\n(`G05`-`G14`, see [Section 8](#8-offline-proof--verification)) and structured/web\nsources ([Section 14](#14-structured-sources--controlled-output)); none had a\ntable row before this pass.\n\n| Workflow | Local result |\n|---|---|\n| Cost Timeline (`cost_timeline`, G05) | Recurring and irregular costs planned from declared contract fields; an amount the sources leave open stays undetermined |\n| Subscription Reconcile (`subscription_reconcile`, G06) | Deterministic match between declared subscriptions and observed message/invoice evidence; price or status mismatches and ambiguous matches block rather than guess |\n| Medication Reconcile (`medication_reconcile`, G07) | Deterministic consolidation of medication plans across reports and discharge summaries; conflicting dosages or schedules stop for confirmation instead of being decided automatically |\n| Database Reader (`database_reader`, G08) | Strict read-only access to a declared specialist SQLite database under a schema allowlist, with mutation attempts rejected |\n| Knowledge Composer (`knowledge_composer`, G09) | Grounded documents (e.g. an ASCII CV, a support worksheet) generated from local knowledge sources, keeping generated structure separate from source evidence |\n| Routine Query (`routine_query`, G10) | Read-only cadence check against a local routine/reminder database; reports the next due date and states plainly that no background scheduler is installed |\n| OCR Pipeline (`ocr_pipeline`, G11) | Scanned-page detection, per-page OCR quality verification, deterministic duplicate/delta indexing; halts for review below the quality threshold |\n| Document QA (`document_qa`, G13) | Finished-document validation (format integrity, completeness, unreplaced template placeholders, SHA-256 preservation) and sealed publication packages |\n| Dossier (`dossier`, G14) | A cited reading list on a declared subject, assembled from gated web search results; states it is a reading list, not a finding |\n| Briefing (`briefing`, G14) | Cited web findings on a declared subject structured into facts, inferences and open uncertainties; a sparse source set yields a limited briefing instead of false completeness |\n| Web Research (`web_research`) | Gated web search behind server approval, per-call approval, adapter readiness and a pseudonymization preflight; keeps only results that carry a source address |\n| Bundle Completeness Check (`bundle_completeness_check`) | Reports from coverage alone whether every approved source was read and every required part produced, without judging content |\n| Print Action (`print_action`) | Hands one named file to the OS-registered print handler and records that printing, not the run, is the user's own step |\n| Chunk Export (`chunk_export`) | Deterministic, overlapping retrieval chunks for your own RAG index, each with source, character offsets, lines and SHA-256, plus a hashed manifest; unread or empty sources stay listed, and a corpus over the declared bound is refused whole instead of exported in part |\n\nThe Blueprints tab under Processes & Workflows also holds the local **Research Notebook**\nworkspace. It keeps an investigation goal, approved roots, reusable questions/prompts,\nprovider configuration, and a trail of verified run ledgers together without storing\nAPI keys or approvals.\n\nThe shared cores are the runtime, policy/privacy gate, run ledger/recovery, evidence\nengine, provider adapter core, MCP surface, and artifact export. Local extraction\nsupports text-family files, JSON, CSV, HTML, PDF, DOCX, and ODT. Unsupported or\nunreadable files remain visible as coverage gaps.\n\nCloud spend, uploads, live NemoClaw/Nebius execution, and further Devpost changes\nremain separate human approval gates.\n\n\n\n\n\n\n## 7. Installation & Quick Start\n\nUse Python 3.11 or newer. There are two ways in; neither needs an account or an API key.\n\n**Judge test build (recommended for a first look):** download\n`nemofold-judge-testbuild-6b13d12.zip` from the [latest release](https://github.com/ellmos-ai/NemoFold/releases/latest),\nunpack it, open a terminal in the unpacked folder and run:\n\n```powershell\npython -m venv .venv\n.venv\\Scripts\\python -m pip install nemofold-0.2.1-py3-none-any.whl\n.venv\\Scripts\\python -m nemofold serve --allow-root . --base-dir .\n```\n\nThen open http://127.0.0.1:8765 for the full local console and add a working folder,\nfor example `examples/synthetic-case` (a fictional case, German). The public demo\nmode starts with\n`.venv\\Scripts\\python -m nemofold serve-demo --demo-root examples/synthetic-case`.\nThe `README.txt` in the ZIP lists every step, including the optional Nemotron run\nwith your own Nebius key.\n\n**From source:** clone this repository, then run:\n\n```powershell\npython -m venv .venv\n.venv\\Scripts\\python -m pip install -e \".[dev]\"\n.venv\\Scripts\\python -m nemofold --help\n```\n\nOn Linux/macOS use `.venv/bin/python` instead of `.venv\\Scripts\\python`.\nFor the later bare `python`/`nemofold` examples, activate this environment first\nor keep using its explicit Python executable. No cloud account, API key or paid\nmodel call is needed for the offline demo below.\n\nEvery non-demo command consumes the same strict `nemofold.job.v1` JSON contract. See\n[`schemas/nemofold-job-v1.schema.json`](schemas/nemofold-job-v1.schema.json) and the\n[`examples/jobs`](examples/jobs) directory.\n\n\n\n\n## 8. Offline Proof & Verification\n\n```powershell\n.venv\\Scripts\\python -m nemofold demo --input examples\\synthetic-home --output run-reports\\demo\n.venv\\Scripts\\python -m nemofold verify run-reports\\demo\\ledger\\demo_offline.json\n```\n\nThe report deliberately says `cloud_proof: false`. To exercise the fail-closed path:\n\n```powershell\n.venv\\Scripts\\python -m nemofold demo --input examples\\synthetic-home --output run-reports\\blocked `\n --scenario blocked-external\n```\n\nThe normal demo creates a text/manifest/ZIP bundle, folder digest, context receipts,\nSQLite FTS index, Markdown/TXT/PDF/DOCX/ODT reports, and one run ledger. It moves and\nundoes a synthetic inbox file to prove reversibility.\n\n### Technical acceptance readback (2026-10-08)\n\nThe accepted implementation is\n[`f43d669`](https://github.com/ellmos-ai/NemoFold/commit/f43d66975c241384d55afd11f25bcf929fef47c1).\nIts [hosted CI run](https://github.com/ellmos-ai/NemoFold/actions/runs/37426667693)\ncompleted on 2026-10-06 and was read back on 2026-10-08: Windows/Python 3.12\npassed all 1155 tests; Ubuntu/Python 3.11 and 3.12 each passed 1154 with one skip.\nThese numbers belong to that commit, not to an unmeasured later revision.\n\nThe 2026-10-08 local check passed Ruff, Mypy for Windows/Linux/macOS (94 source\nfiles each), compileall, JavaScript syntax and the 476-file acceptance-evidence\nverification. Source and wheel distributions built successfully. A fresh wheel\ninstallation, tested without `src` or `PYTHONPATH`, ran the CLI and offline demo;\nthe verifier accepted all ten recorded artifacts. A separate local full-suite\nattempt was stopped under confirmed host CPU saturation and is not a local\nfull-suite pass. Personal GUI acceptance remains pending.\n\nSee the [release gate](RELEASE_GATE.md) for the exact checks and product boundaries.\nThe real cloud proof remains the historical 2026-09-02 run; today's verification\ndoes not claim a new cloud call or a hosted public demo.\n\n### Final acceptance round (2026-10-12)\n\nThe personal GUI acceptance on 2026-10-12 reworked the console: the start page is\nnow the workbench, blueprints and your own use cases are separate, a folder can be\napproved for a session from the folder dialog, and Nemotron on Nebius is selectable\nas a provider. It also fixed the anonymizer, so dates reach a cloud model readable\nwhile phone, case and policy numbers stay masked. Ten independent review rounds\nby a second model (Codex, OpenAI) checked these changes. The\n[hosted CI run](https://github.com/ellmos-ai/NemoFold/actions/runs/38312717933) on [`b0e2bc3`](https://github.com/ellmos-ai/NemoFold/commit/b0e2bc3b78fc045f605df94ca34f28c7079190fe) passed: Windows/Python 3.12 all\n1175 tests; Ubuntu/Python 3.11 and 3.12 each 1173 with 2 platform-specific\nskips.\n\n### Owner's GUI acceptance completed (2026-10-13)\n\nThe owner completed the acceptance on 2026-10-13 in eight rounds of live testing\nwith his own folders. These rounds turned every runnable task into a workflow of\none or more steps in a single blueprint grid and separated the clean full console\nfrom the public demo. They added working folders that stay approved across\nrestarts, path entry and the system folder dialog, three captain modes (keywords,\na model choosing from the catalogue, a brief for a CLI agent), Artifacts as an area\nof its own, and a Connections page that reports what the computer actually shows.\nA real folder of about 8,000 files exposed a memory limit in Synopsis Merge, which\nnow refuses more than 500 documents with a sentence naming the alternatives. Codex\n(OpenAI) reviewed the two pull requests of these rounds (#6, #7) as a second model\nand merged them after its verdict MERGE-FÄHIG; its first review of #7 found a\ndouble-run bug, which was fixed before the merge. The\n[hosted CI run](https://github.com/ellmos-ai/NemoFold/actions/runs/38366200345) on\n[`6b13d12`](https://github.com/ellmos-ai/NemoFold/commit/6b13d12cdb269e8693053ed0d90d173b8a6c8123) passed:\nWindows/Python 3.12 all 1189 tests; Ubuntu/Python 3.11 and 3.12 each 1187 with 2\nplatform-specific skips.\n\n**Judge test build:** [latest release](https://github.com/ellmos-ai/NemoFold/releases/latest) - a ZIP with the wheel, start\ncommands for the full local console and the public demo, and the fictional example\ncase; unpacked and installed into a fresh environment, both paths ran.\n\n### Acceptance gate register\n\n16 of 18 internal Ellmos use-case acceptance gates (`G01`-`G18`) claim `done` in the\nshipped register, each backed by committed, re-hashable evidence: 444 files (1.8 MB)\nunder `examples/acceptance-evidence/`, 476 files checked by the command below. `G17`\nand `G18` remain `not_supported`, with their boundary reasons recorded in the register\nitself.\n\n```powershell\nnemofold acceptance-gates --evidence-root .\n```\n\nWithout `--evidence-root` the command fails closed with exit code 2\n(`done_gate_requires_evidence_root:G01`) by design: a `done` claim is unreadable\nwithout the files behind it, so it refuses to report a status it cannot verify rather\nthan trusting the register text. Regenerate the evidence after a bundle or contract\nchange with:\n\n```powershell\nnemofold acceptance-evidence --work-dir \n```\n\nThis reruns all 16 gate bundles, exports only the files each receipt references (host\npaths replaced with an `` token, hashes recomputed over the exported\nbytes) and rewrites the register; a gate whose bundle stops producing a verifiable\nreceipt loses `done` instead of keeping a stale claim.\n\n\n\n\n## 9. Executing Real Local Jobs\n\n```powershell\n$runId = \"local_analysis_1\"\npython -m nemofold preview --job examples\\jobs\\evidence-local.json `\n --allow-root $PWD --run-id $runId\npython -m nemofold run --job examples\\jobs\\evidence-local.json `\n --allow-root $PWD --run-id $runId\npython -m nemofold verify run-reports\\evidence-local\\ledger\\$runId.json\n```\n\n`preview` does not run an external model or apply file actions. For an external-model\njob it writes the exact pseudonymized context package that would be eligible to leave\nthe host and records `transfer_performed: false`. A later `run` still blocks unless a\nreal external runtime adapter and the explicit privacy/model/cost gates are present.\n\n`nemofold package` turns an `allow_once` job into a hashed, path-free local NemoClaw\ndirectory and validates it immediately. It still performs no upload and records\n`transfer_performed: false`; see [NemoClaw integration](docs/nemoclaw-integration.md).\n\n\n\n\n## 10. Provider Adapters, MCP & API\n\nNemoFold can send only its locally selected and pseudonymized evidence context to\nOllama, LM Studio, a personal Codex/Claude Code CLI, or the official OpenAI/Anthropic\nAPIs. Returned claims are accepted only when every quote is present in the outbound\ncontext for that question. Provider selection is runtime configuration; it does not\nchange the strict job contract.\n\n```powershell\npython -m nemofold providers\npython -m nemofold analyze-provider --job examples\\jobs\\evidence-local.json `\n --allow-root $PWD --run-id ollama_1 --provider ollama --model qwen3\n```\n\nThe same service is available at `POST /api/provider-analyze` and through the stdio\nMCP server:\n\n```powershell\ncodex mcp add nemofold -- python -m nemofold mcp --base-dir $PWD --allow-root $PWD\nclaude mcp add --scope user nemofold -- python -m nemofold mcp `\n --base-dir $PWD --allow-root $PWD\n```\n\nLocal providers are restricted to loopback. External adapters require `allow_once`, a\nserver-side external-model gate, and per-call transfer approval. Keys come only from\nenvironment variables. Nemotron on Nebius Token Factory is also selectable in the\nlocal console as provider `nebius`: the key comes only from `NEBIUS_API_KEY`, the\nserver must be started with `--allow-external-models --max-external-cost-usd `,\nevery run needs its own approval with privacy `allow_once`, and only pseudonymized\nexcerpts are sent. Generic provider receipts, including a console run on `nebius`,\nnever become Nebius competition proof; the next section (the separate\n`token-factory-run` path, committed under `examples/proven-run/`) remains the only\nsuch route. See\n[Provider adapters, local API, and MCP](docs/providers-and-mcp.md).\n\n\n\n## 11. Approved Nebius Token Factory Run\n\n### Model choice and what Token Factory contributes\n\nThe configured model is NVIDIA Nemotron 3 Super\n(`nvidia/nemotron-3-super-120b-a12b`), served by\n[Nebius Token Factory](https://nebius.com/services/token-factory/nemotron). It was\nchosen deliberately for this product: the weights are fully open under the NVIDIA\nOpen License (the hackathon requires an NVIDIA open-source model); its\nagentic-reasoning and instruction-following profile matches NemoFold's strict\nJSON-bound evidence contract; the long context window carries a whole bounded\nevidence package in one request; and the hybrid MoE design (about 12B active of\n120B parameters) keeps the conservative per-call cost ceiling far below the job\nbudget. The adapter enforces the `nvidia/nemotron-` prefix twice, in preflight and\nagain before transport.\n\nToken Factory contributes the one step the product cannot do locally: a strong\nhosted reasoning pass over the prepared evidence bundle. Everything else - the\noriginals, paths, index, policies, journal, and verification - stays on the local\nmachine; only pseudonymized bounded chunks cross the gate, and the sanitized result\nis bound back into the locally verified receipt chain. A real paid run is an explicit\nuser gate; it was granted once, and the resulting proof is committed below.\n\n### The proven run (2026-09-02)\n\nA real paid Token Factory run over the fictional synthetic case corpus completed with\n`status: executed` and `cloud_proof: true`. The model answered two evidence questions\n(the blue VW Golf, the confirmed alibi); every claim carries exact quotes that the\nlocal verifier matched against the pseudonymized chunks byte for byte. Usage:\n4550 prompt + 3657 completion = 8207 tokens, cost $0.0047 against a $1.00 ceiling.\n\nThe complete package — job, manifest, privacy receipt, context receipts, transfer\nattempt, and result — is committed at `examples/proven-run/` with no secrets and no\nreal personal data (the corpus is the fictional `examples/synthetic-case/`). Judges\ncan re-verify it offline, without any account:\n\n```bash\npython -m nemofold verify-result examples/proven-run\n```\n\nHonesty note: it took five attempts, and that is the point. The first four each\nfail-closed at near-zero cost — a wire-format 400 from the endpoint, the local\nverifier catching two misattributed quotes in an otherwise perfect-looking answer,\nan over-strict receipt rule of our own, and a provider usage echo with extra detail\nfields. Every rejection is a bug fix in this history, and the verifier rejecting a\nfluent model answer on quote-attribution grounds is the product's core promise\n(evidence before inference) working against a live frontier model, not a slogan.\n\nThe live adapter is a separate, irreversible transfer gate. It accepts only the\nofficial Nebius Token Factory HTTPS origin, rejects redirects, checks a conservative\ncost ceiling before the request, reads the key only from `NEBIUS_API_KEY`, and refuses\nto repeat a package that already contains `result.json` or a durable transfer attempt.\nAfter the cost gate and before it writes any receipt, it confirms the exact model ID\nagainst the live `/v1/models` catalog. That call is an authorized metadata read; it\ncarries no job content, so a retired or mistyped model ID aborts without a receipt and\nleaves the package fully runnable. A confirmed catalog records\n`model_catalog_checked: true` in the result, and the verifier rejects a result that\nclaims otherwise.\n\n```powershell\n$env:NEBIUS_API_KEY = \"\"\npython -m nemofold token-factory-preflight `\n --input-price-usd-per-million `\n --output-price-usd-per-million `\n --max-completion-tokens 8192\npython -m nemofold token-factory-run `\n --approve-live-transfer `\n --input-price-usd-per-million `\n --output-price-usd-per-million `\n --max-completion-tokens 8192 `\n --declared-nemoclaw-version \npython -m nemofold verify-result \nRemove-Item Env:\\NEBIUS_API_KEY\n```\n\nThe two rates are mandatory inputs because pricing can change; copy them from the\ncurrent provider pricing at execution time. Reasoning models spend completion\ntokens on thinking before the JSON answer, so keep `--max-completion-tokens`\ngenerous; the conservative cost gate still checks the resulting ceiling against the\njob budget before any request. The sanitized `result.json` binds the exact request,\nthe sanitized response (`response_sha256` is computed over the sanitized body, never\nover raw provider bytes), usage, rate inputs, cost, endpoint, model, timestamps, and\nmodel output to the immutable local package. It contains no Authorization header or\nAPI key. A failed provider response records `transfer_performed: true` but never\n`cloud_proof: true`. If the connection ends without a response, the pre-request\n`transfer-attempt.json` remains in place, reports an uncertain transfer state, and\nblocks an unsafe automatic retry. Recovery after any burned attempt is deliberate,\nnot destructive: build a fresh immutable package with `nemofold package` under a new\n`run_id` and run that. Existing receipts are never deleted, so the failed attempt\nstays auditable while the new package remains runnable.\n\n`token-factory-preflight` performs no network request and writes no transfer receipt.\nIt validates the immutable package, endpoint, explicit Nemotron model, JSON request,\ncurrent caller-supplied prices, conservative maximum cost, job budget, duplicate-run\nguards, and whether a session key is present. Its output always keeps\n`network_called`, `transfer_performed`, and `cloud_proof` false; a pass is readiness,\nnot execution evidence and not transfer approval. It therefore reports\n`model_catalog_checked: false`: the catalog is confirmed by `token-factory-run`, which\nis the only command allowed to touch the network.\n\nThe request uses Token Factory's documented `json_object` response mode and carries\nonly documented chat-completion parameters, because one undocumented field that the\nendpoint rejects would spend the single approved run on an HTTP 400. NemoFold includes\nits complete output schema inside the bounded user payload and validates the returned\nobject locally. It therefore does not depend on model-specific server-side JSON-schema\nenforcement to protect the evidence contract.\n\nThe NemoClaw/OpenShell runtime itself was not installed or executed for this submission. What is proven is the real Nebius Token Factory run (`examples/proven-run/`, `nemoclaw_proof: false`); the skill package in `skills/nemofold/` is ready to install.\n\nThe optional declared NemoClaw version is metadata only. The result records\n`nemoclaw_proof: false`; only a separately captured, sanitized runtime log from the\nactual sandbox may support a NemoClaw execution claim.\nThe earlier pre-release option `--nemoclaw-version` was intentionally removed because\nits name implied proof; scripts must use `--declared-nemoclaw-version` instead.\n\nAction jobs additionally require `--approve-actions`. A completed action run can be\nreversed with `nemofold undo --output --allow-root \n--approve-actions`. Failed or blocked jobs can be retried with `nemofold resume` while\npreserving the original job identity and journal.\n\n\n\n\n## 12. Voyage Library & Captain's Desk\n\nA plan you keep gets a name and is called a **use case**: an action or a workflow\nadopted from a blueprint (or planned by the captain) and bound to your own folders.\nThe console lists them under *My use cases*; the shipped starting points live under\n*Blueprints* ([Section 16](#16-local-web-console--routes)). In the text below, a\n\"voyage\" is the stored plan behind a use case. The library holds saved voyages next to\nfive blueprints that ship with NemoFold - fact digest as PDF, topic bundle with\nevidence, daily arrivals, registry table, and offer synopsis. A shipped blueprint is a\nread-only starting point that carries workflows and parameters but no path, so a\nshipped file can never name a folder on your machine and can never run by itself.\nCopying one binds it to your approved roots; from then on it is an ordinary entry you\ncan edit.\n\nEditing works two ways, and both end in something you confirm. In the detail view you\nreorder or remove steps by hand and save. Or you ask the captain - \"füge zwischen\nSchritt 2 und 3 einen Tagesbericht ein\" - and get the step list before and after as a\ndiff with an apply button. The library is written only when you apply, and a request\nthe desk cannot map is answered rather than guessed: anonymization, for example, is\npart of every step's privacy gate and not a step of its own.\n\nRunning a voyage runs its steps in order, each through the same gates and with its own\nledger, and writes one dossier that links them. A step that blocks stops the chain\nthere, so nothing downstream runs on an unfinished result. When it worked you get one\nquiet line and the detail one click away; when it did not, the steps, gates and models\nare open in front of you.\n\nA model preference can sit at three levels, and the most specific one wins: the step,\nthe chain, then the local default. A chain may instead declare that it overrides its\nlinks - that exists for privacy-critical work that must stay local whatever a step\nsays - and such a voyage is flagged in the library with a warning and the reason its\nowner gave. For a single run you can also pick one model for the whole voyage; the\noverride applies once, appears in the dossier, and leaves the stored settings alone.\n\nAbove all of that sits one rule no mode, override or setting can lift: a chain\ndeclared local-only is a cap. A more exposed setting underneath it neither wins nor\nquietly loses - it stops the chain and asks, because silently widening what sees your\ndocuments is the one failure this product cannot afford. A preference authorises\nnothing by itself either: the external gate, the per-run approval and the budget still\ndecide.\n\nThe dossier names the model that actually ran, which is not always the one that was\npreferred, and it says which of the three cases applied. Most workflows are\ndeterministic and have no reasoning worker at all, so a preference on them is kept and\nreported as not applying rather than credited with work it did not do. A local worker\non Evidence Analyst is really asked, because a local endpoint needs no per-run transfer\napproval. An external one stops the chain and points you at running that step on its\nown, because a chain run never grants a per-run transfer approval.\n\nEvery entry carries topic tags, which is how a use case finds the room it belongs in,\nand it may carry a schedule. A schedule is a stated intention and nothing more: it\nrecords when you mean to run the voyage, adds the derived `scheduled` tag so the routine\nfilter finds it, and says so about itself in the stored file. NemoFold registers no task\nwith your operating system and starts nothing on its own.\n\nSome use cases cannot be served yet. Those are still kept, marked as waiting for the\ninstrument they need, and listed apart from the runnable ones - a wish recorded is\nworth more than a wish refused, as long as nobody mistakes it for something that runs.\n\n\n### Ask the Captain's Desk\n\nThe console's overview opens with the Captain's Desk: one plain sentence in, a chain of\nprepared job drafts out. It plans and prepares; it never executes, never sends, and\nnever stores an approval. Every step it prepares is dry-run, local-only and carries a\nzero budget, whatever the request asked for.\n\nSay `Unfall mit Hyundai und schreib mir eine mail an zuständigen versicherungsberater\nfüge bild ein als entwurf` and the desk prepares Contact Monitor — because the sources\nmay already name who is responsible — followed by a Controlled Email draft with the\nsubject seeded from your sentence. What it does not know it asks: the recipient, the\nsender, and which approved file to attach, with the note that an attachment is hashed\nbut never quoted as evidence.\n\nThe desk is equally explicit about what it cannot do. Ask it to keep a bilingual\ndocument in sync and it answers that bilingual sync is a planned Document Service, not\nan active one, then prepares the closest honest approximation — a Folder Digest\nsnapshot and a Version Resolver comparison — so you still leave with something\nrunnable. Ask for repetition and you get the two truthful options: run the prepared\ndrafts again, or install a task in your own operating system that calls the CLI.\nNemoFold has no scheduler and does not start itself, so it never claims one.\n\nPrepared voyages land in the same prepared-job inbox the CLI, MCP and local API write\nto, marked `source: wizard`. A person still opens each draft in the engine room,\ncompletes what is open and runs it. The desk is a loopback-only surface: it is absent\nin the public demo and refused on a network-exposed server.\n\n\n\n\n## 13. Case Chronicle Deep Analysis\n\nFour deep-analysis cores turn a folder of statements, reports and contracts into\nstructures you can follow back to a sentence: who appears, which links are actually\nwritten down, when each person is placed, and where nothing places them at all. Seven\nworkflows compose them - Person Registry, Relation Model, Person Timeline, Coverage\nTimeline, Alibi Weave, Contradiction Synopsis and Corpus Query.\n\nNone of them draws a legal conclusion, and every report says so in its own metadata.\nWhat they produce is what the documents state, who states it, and where they are\nsilent. The interesting output is usually the silence.\n\nFour rules do most of the work, and each one is a refusal.\n\nA person exists in the registry because a document declares them under a named field,\nnever because something looked like a name. An edge exists because a sentence states\nit; two people named in one sentence is shown as exactly that and nothing more, and\nevery edge carries the sentence. A time the sources leave open stays undetermined and\nis drawn as a band, because a dot placed to make a chart look finished cannot be told\napart afterwards from a dot that was written down. And a self-report stays one line: a\nsecond line appears only where a different source says the person was present and\nplaces itself at the same place inside the tolerance window, with both sentences shown\nso you can judge that inference rather than inherit it.\n\nThe registry has an identified form, a pseudonymous form that carries no name, alias\nor quote, and a local identity map. The pseudonymous form is what may travel; the map\nis the one file that must not, and it says so about itself.\n\nFigures are deterministic SVG: the same input renders to the same bytes, which is what\nlets a run ledger hash an image and mean it. Each carries a legend in words as well as\na stroke style, so nothing depends on colour.\n\n`examples/synthetic-case/` holds twelve short fictional documents - each marked as\ninvented in its first line - with a blue VW Golf, a questionable weekend, one\ncorroborated alibi, one person nothing outside confirms, and two contradictions. Every\nCase Chronicle test runs on it, and so does the demo.\n\n\n\n\n## 14. Structured Sources & Controlled Output\n\nWave two adds three things a document workspace eventually needs, each behind the\ngate that fits it.\n\n**Structured sources.** A database row and a paragraph are the same kind of\nevidence: something a source says, at a place you can point at. SQLite, XLSX and\nCSV are rendered into deterministic labelled lines and join the corpus, where\nfield extraction, entity resolution, timelines and corroboration read them\nunchanged with the line number as the anchor. SQLite is opened read-only and\nreads only the tables a job declares; a declared table that is not in the file is\nreported rather than silently skipped.\n\n**The open web.** Searching is the first thing here that sends words to a\nstranger, so four conditions have to hold together: the server allows it, the\ncaller approved this call, the adapter reports itself ready, and the queries\nsurvive a pseudonymization preflight. A query carrying an email address, a path\nor a phone number is refused rather than rewritten - a silently edited query is\none the person never asked, and they would read the answer as if they had. Every\nresult keeps the address it came from, and a hit without one is dropped. The\nTavily key is read from the environment at call time and appears in no job,\ndraft, library entry or report. Without any of the four, the run ends blocked\nwith all the reasons named at once.\n\n**Sending.** D-035 rights now decide rather than merely being stored. draft_only\nstops at the draft, send_with_confirmation reaches the adapter only after the\nexact approval digest comes back, and send_when_ordered reaches it on the order.\nA right is a property of a message *to somebody*, so recipient classes come from\nyour contact book - and a message addressed across two classes is governed by the\nstrictest of them. One mail to a family address and a public list under the\nfamily rule is the mistake this prevents, and it is the kind nobody notices\nafterwards. A recipient nobody classified counts as the strictest case, and a job\ndeclaring no right of its own may never send whatever the class would allow.\n\nReal transmission stays off. A configured SMTP adapter still refuses on this\nbuild, because wiring a socket without a person having allowed this server is the\none step NemoFold does not take on its own, and the status names which piece is\nmissing rather than reporting a general unavailability.\n\nTwo smaller pieces round it out. delivery_rules is a policy that files artifacts\ninto declared folders, checked against the same approved roots as every other\nwrite. And printing is deliberately not done for you: handing a file to whatever\nprogram is registered for its type returns nothing a run could put in a receipt,\nso NemoFold writes the print-ready file plus the exact command and says the\nprinting is your step.\n\n\n\n## 15. Checking, Comparing & Composing\n\nWave four adds the workflows that read something *against* something else, and\nthe ones that turn a corpus into a document somebody hands over.\n\n**Reference Check** compares your documents against a declared checklist and\nquotes the line that answers each item. Present means quoted, because a\ncheckmark without a quote is an opinion; missing items are listed with the terms\nthat were looked for, so you can see whether the check searched for the right\nthing before concluding the document lacks it. It says present or absent and\nnever that a document is correct, valid, sufficient or lawful - whether a\nmissing item matters is a question for somebody qualified to answer it. Three\ngrids ship as starting points, including one that reviews a voyage plan, where\nthe usual finding is that the plan never said what it would not do.\n\n**Rater Race** codes the same material twice and shows where the two readings\npart. Two numbers, never one: percent agreement flatters any scheme where a\nsingle code dominates - two raters calling ninety per cent of items \"other\"\nagree ninety per cent of the time while telling you nothing - so Cohen's kappa\nstands beside it, and where kappa is undefined it says so instead of printing a\nnumber that would be read as a result. The disagreements are the output worth\nreading: they mark where the coding scheme is ambiguous, not where a rater was\nwrong. The cell diff exports as a workbook.\n\nThe default run is a deterministic demonstration: first-match versus\nlast-match on the same local corpus. It is **not** two independent agents.\nFor an actual two-rater comparison, supply both `coding_a` and `coding_b` as\nobjects mapping every readable source file name (or source ID) to one declared\ncode. Also supply distinct `rater_a` and `rater_b` names. Each sheet must cover\nthe same complete corpus; missing or foreign items and undeclared codes stop\nthe run. The JSON result and run metadata distinguish `deterministic_demo`\nfrom `supplied_codings`. NemoFold compares the sheets but cannot verify that\nthe two raters produced them independently; retain their separate run receipts\nfor that claim.\n\n**Guide Compose** folds a folder into one guide that stands in for its\ndocuments, with every paragraph still a quoted line naming its source and a\ncount of the repeats it folded. **Wiki Export** writes the same corpus as one\npage per document plus an index, carrying each document unchanged - a wiki whose\npages disagree with their files is worse than no wiki. **Pattern Mining** runs\nthe staged aggregation over a pile of logs and reports which lines recur, how\noften and from where; below the support threshold nothing is reported, because a\nlist where everything is a pattern is a list where nothing is. A recurring line\nis a fact about that corpus, never a rule about the world.\n\n**Document Compose** fills your own .docx template through report-forge, which\nis an optional extra: filling templates is a separate job with its own\naccumulated knowledge, so none of its code lives here and only its finish stage\nis called. Without the extra a run ends blocked with the exact install command\nrather than an import error. **Mail Merge** is the same stage once per recipient\nfrom your contact book, each document named after the person it is for.\n\n\n\n\n## 16. Local Web Console & Routes\n\n```powershell\n$env:PYTHONPATH = \"$PWD\\src\"\npython -m nemofold serve --allow-root $PWD --base-dir $PWD\n```\n\nOpen `http://127.0.0.1:8765`; the label at the top reads `FULL LOCAL CONSOLE` (the\ndemo below reads `PUBLIC DEMO · SYNTHETIC DATA ONLY`). The full console starts clean:\nno example folder and no example questions; it begins at your first working folder, or\nelse at the first folder passed with `--allow-root`. The fictional case file\n`examples/synthetic-case` and its German questions belong to the public demo\n(`--allow-root examples/synthetic-case` opens the same case in the full console). The\nconsole uses the same strict job parser and\napplication service as the CLI. It starts on loopback only, rejects cross-origin POSTs,\nand requires `--expose-network` before it will bind to a non-loopback address. Even\nthen the authority-bearing surfaces stay loopback-only: a network-exposed server\nrefuses job preview and execution, exactly like drafts, artifacts, and providers;\nhosting for other people goes through `serve-demo`. Preview is the default safe path;\naction workflows additionally require the server-side `--approve-actions` gate before\nan apply request can succeed.\n\nThe start page `/` is the **workbench**: the Captain's Desk on top, the engine room\nopen below it and the folded ship's chart at the end, nothing else (the first menu item\nis *Engine room*). The engine room shows its four areas - mission, bounded territory,\nauthority and budget, reasoning worker - as separate tinted tiles. The overview and five work areas use distinct, bookmarkable routes instead of in-page\nscroll jumps: `/`, `/folders`, `/processes`, `/artifacts`, `/governance` and\n`/connections`. Analysis and Routines used to be rooms of their own, which meant the\ndoor you came through decided what you could see. They are now the two tabs of\nProcesses & Workflows, `?tab=workflows` (My use cases) and `?tab=registry`\n(Blueprints); Artifacts is an area of its own. The old routes still lead somewhere:\n`/document-center`, `/analysis` and `/routines` redirect to their replacement,\n`/processes?tab=artifacts` to `/artifacts`, and a link that names one contract lands\nin the Blueprints tab with that contract selected.\n\nVocabulary: everything you can run is a **workflow**, with one step or several; a step\nis one of the 44 job contracts (the API field is still `workflow`). A **use case** is a\nworkflow you adopted and bound to your own folders; **blueprints** are the templates.\nThe Blueprints tab shows every blueprint as an equal tile - the shipped presets, *My\nblueprints* and the 44 one-step workflows - filtered by the same topic chips as My use\ncases. Each tile offers *Add to my use cases*; a one-step workflow can also be tried\nonce in the engine room. A blueprint can be adopted any number of times\n(copies are numbered) and renamed in the dialog; a use case can be saved as a blueprint\nof your own or removed with *Remove from my use cases*, which never touches its\nblueprint. Use-case details open as a dialog.\n\nWhat stands in front changed, not the rooms. Use-case tiles are the primary object,\nfiltered by topic tags, and a routine is simply a use case that carries a schedule and\nthe derived `scheduled` tag — choosing that filter is what turns the porthole into the\necho sounder: recent runs of the actions your routines use, manual runs of the same\naction included, since NemoFold does not tie a run to a schedule. The one-step\nworkflows sit among the blueprints, with the engine room as their editor.\n\nFolders is the home of your **working folders**: you add them once and they stay\napproved at every later start of this loopback console\n(`run-reports/web-console/working-folders.json`, `/api/working-folders`). The captain\nand the engine room offer them as one-click chips, the captain takes several folders,\nand a request that names exactly one working folder (\"Summarize the documents in\nTaxes\") runs on that folder. Folders also shows what is actually on board and *Your\nfolder workflows*. In the local console the folder dialog browses any folder on this\ncomputer, takes a typed or pasted path, or opens the system folder dialog of this\ncomputer (`/api/pick-folder`); approving a folder for the session\n(`/api/approve-root`) or keeping it as a working folder is always an explicit click,\nand reading starts only after it. The public demo and a network-exposed server refuse\nall of these, and a network-exposed server never loads working folders. The ship's\nchart at the end of the start page folds the boundary tiles, the evidence chain, the\narea map and the roadmap; it unfolds on click or Enter.\n\nThe captain plans in one of three modes, chosen per request. *Keywords* (the default)\nis a local, deterministic match of task words; a document request without one falls\nback to Evidence Analyst with the sentence itself as the question. *A model chooses*\nlets a reasoning worker read the sentence and the workflow catalogue - never a\ndocument - and pick up to six workflows; the choice is checked against the catalogue\nand the plan is built exactly as for keywords. A local Ollama or LM Studio model needs\nno approval; an external provider needs `--allow-external-models` and an approval for\nthat one request, and receives the sentence pseudonymized. *Brief for a CLI agent*\ncopies a prompt with the folders, the catalogue, the job format, the commands and the\nrules to the clipboard, for an agent such as Claude Code or Codex. The captain only\nprepares: *Prepare voyage* puts the steps into the job inbox (engine room, *Run\nidentity & prepared jobs*) and loads step 1 into the engine room below; a plan of\nseveral steps is first kept as one new workflow under My use cases, and the engine\nroom names it and runs all its steps in order on request, locally and as a dry run.\nPreparing the same plan again reuses that workflow. *+ New use case* and *+ New\nblueprint* start an entry from a name and a first step. Echo sounding - the recent\nruns of the actions folder routines use - sits on Folders; NemoFold has no scheduler\nof its own, a scheduled use case writes a task file the person installs. The public\ndemo shows only what it can serve: no captain, no working folders, no library writes\nand no policy editor, and Blueprints lists the five demo workflows to try once.\n\nThe model field of a local provider offers the models that server actually holds;\nmodels it only relays to a cloud (`:cloud`) are not offered and are refused as a local\nmodel, so \"loopback, local only\" stays true. Some local builds cannot force a JSON\nanswer; the adapter then asks once more with the schema as an instruction. The\nresearch notebook sits under the engine room as the quick investigation mode and\nships as one of My use cases. Artifacts lists every run ledger below the output scope,\nfailed and blocked runs included, with the date and time it was written. Connections\nshows what this computer shows per adapter - local server running, CLI found, key\nvariable set, never a key value - and names the 2026-09-02 proof run as the only\nNemotron proof.\n\nGovernance renders the authority this server was started with — the file-action,\nexternal-model and network gates, approved roots, budget ceiling and contracted\nworkflows. Gates are read there, never granted there: a closed gate still requires a\nrestart with the matching flag. Below them sit the two registers described in the next\nsection. Artifacts opens executed or blocked ledgers and verifies every recorded\nartifact hash. Connections is a pure status page that keeps configured adapters,\nexecuted provider runs, transfers, and cloud proof visibly separate; Connections and\nGovernance each say where a setting is changed. The console still\nholds everything it always did: explainable Cleanup Rules, read-only Mail-to-Case\nintake, Controlled Email drafts, the source-grounded Contact Monitor, deterministic\nbundle preparation, privacy preflight, Evidence Analyst, reusable prompt sets and\npersistent Research Notebooks. A model can prepare the same settings for browser review\nthrough `draft-save`, MCP, or the loopback draft API; approvals are always reset.\n\n\n\n### Rules and policies\n\nA rule is one sentence you can hold in your head — \"attachments never leave\nunconfirmed\". A policy is a rule set, closer to a small skill: several statements and,\nwhere a workflow can consume it, a machine body as well. Both live under Governance, on\nthe Rules and Policies tabs, and both carry the list of places they are bound to. That\nlist is the point: one rule bound to six voyages stays one object, so editing it edits\nall six and the rule itself shows you which six. Copying the sentence into six voyages\nis how a rule quietly stops being one rule.\n\nThe register shows what holds in general and, beneath it, where a saved voyage departs\nfrom it: a chain that overrides its links, outbound rights above the default profile, a\nstep that may send under a wider right than its chain. The departure stays at the voyage\nthat made it, because that is where you change it, and the voyage says so in words\nbefore you run it.\n\nA policy grants nothing. `cleanup_rules` is the first workflow that consumes one, and it\nfills in only what the job contract left empty — rules written into the contract keep\nwinning, and the dossier names which of the two decided. Allow roots, privacy mode,\naction mode and the per-run approvals remain the things that actually decide.\n\nControlled Email does not claim network delivery in the default runtime. It writes the\nexact draft and approval digest, then blocks a send request until the same digest is\nconfirmed and a separately proven server-side mail adapter exists. Mail-to-Case accepts\napproved local `.eml` files; it does not silently connect to a mailbox.\n\n### Run the capability-minimal synthetic demo\n\nUse the separate demo command when the console may be reachable by people who must not\nreceive local file authority:\n\n```powershell\n$env:PYTHONPATH = \"$PWD\\src\"\npython -m nemofold serve-demo --demo-root examples\\synthetic-home\n```\n\n`serve-demo` accepts only five read-only workflows over the committed synthetic corpus.\nInput and output roots, workflow parameters, privacy mode, action mode, model access and\nbudget are server-controlled. Every request receives an isolated temporary output area\nthat is removed after the sanitized response is returned. The command exposes neither\nfile-action nor external-model flags and still binds to loopback unless both a non-local\nhost and `--expose-network` are supplied. It is a capability-minimal hosting surface,\nnot proof of a Nebius, Nemotron or NemoClaw runtime call; `cloud_proof` remains false.\n\n\n\n## 17. Sibling Ecosystem & Integration\n\nNemoFold is a core document intelligence component of the `ellmos-ai` ecosystem. Sister projects live in the `ellmos-ai`, `dev-bricks` and `doc-bricks` organizations; `open-bricks` is an umbrella profile organization without code repositories. Public peer tools:\n\n| Tool / Repository | Organization | Role & Interoperability |\n|:---|:---:|:---|\n| **[bach](https://github.com/ellmos-ai/bach)** | `ellmos-ai` | Autonomous agent framework & background executive loop |\n| **[ellmos-unified-gui](https://github.com/ellmos-ai/ellmos-unified-gui)** | `ellmos-ai` | Multi-agent desktop unified graphical interface |\n| **[ellmos-controlcenter-mcp](https://github.com/ellmos-ai/ellmos-controlcenter-mcp)** | `ellmos-ai` | Central orchestration and capability-routing MCP server |\n| **[ellmos-homebase-mcp](https://github.com/ellmos-ai/ellmos-homebase-mcp)** | `ellmos-ai` | Agent persistent memory, state management, and profile store |\n| **[report-forge](https://github.com/ellmos-ai/report-forge)** | `ellmos-ai` | Headless DOCX template engine and professional report renderer |\n| **[DevCenter](https://github.com/dev-bricks/DevCenter)** | `dev-bricks` | Multi-repository workspace manager and local developer dashboard |\n| **[ticket-master](https://github.com/ellmos-ai/ticket-master)** | `ellmos-ai` | Multi-provider LLM ticket router and agent triage console |\n| **[lock-master](https://github.com/ellmos-ai/lock-master)** | `ellmos-ai` | Portable multi-agent file locks: exclusive and team locks with scopes and expiry |\n| **[system-gap-master](https://github.com/ellmos-ai/system-gap-master)** | `ellmos-ai` | Serverless sync yard for multi-machine, multi-agent setups |\n| **[CleanMarkdown](https://github.com/doc-bricks/CleanMarkdown)** | `doc-bricks` | Markdown linter, anchor normalization, and documentation formatter |\n| **[open-bricks](https://github.com/open-bricks)** | `open-bricks` | Umbrella profile organization (no code repositories) |\n\n---\n\n\n\n\n\n## 18. Transparency, Licenses & Security Policy\n\n### Trust Boundary\n\n- Original files, absolute paths, persistent index, policies, ledger, validation, and\n actions stay local.\n- Only selected chunks, questions, artificial source IDs, schema and a bounded budget\n can enter an external package.\n- The package validator rejects host paths, secrets, undeclared files, changed hashes,\n symlinks, or residual sensitive patterns—even if a manifest was re-hashed.\n- `cloud_proof: true` is invalid without a successful, schema-valid provider response\n bound to runtime evidence. The repository contains the adapter, simulated tests,\n and the [verified historical 2026-09-02 competition run](examples/proven-run/).\n Re-verifying that receipt does not imply a new cloud call.\n\n### Design, Documentation & Governance Links\n\n- [Evidence-console interface direction](docs/design-direction.md)\n- [Architecture](docs/architecture.md)\n- [Provider adapters, local API, and MCP](docs/providers-and-mcp.md)\n- [Capability-minimal demo deployment](docs/deployment.md)\n- [NemoClaw integration](docs/nemoclaw-integration.md)\n- [Product story](docs/product-story.md)\n- [Document Services roadmap](docs/document-services-roadmap.md)\n- [Three-minute jury demo](docs/jury-demo.md)\n- [Jury design set and Nautilus brand kit](docs/media/designset/README.md)\n- [Submission readiness](docs/submission-readiness.md)\n- [Competition code map](COMPETITION_CODE_MAP.md)\n- [Third-Party Software & Dependency Audit](THIRD_PARTY_LICENSES.md)\n- [Security Policy & 48h response target](SECURITY.md)\n- [Contributing Guidelines](CONTRIBUTING.md)\n- [Release Gate Checklist](RELEASE_GATE.md)\n\n---\n\n### German Statutory Notice (§ 521 BGB Gefälligkeitsrecht)\n\n> **Statutory Disclaimer (§ 521 BGB Gefälligkeitsrecht):** This open-source prototype is provided free of charge for scientific research and developer evaluation. Maintainer liability is limited to intent and gross negligence pursuant to § 521 BGB. The software does not provide legal, financial, or medical advice and does not replace qualified professional evaluation.\n"}