ndi-cli 0.7.0__tar.gz → 0.9.0__tar.gz

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ndi-cli
-Version: 0.7.0
+Version: 0.9.0
 Summary: NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools
 Keywords: ndi,cli,document-intelligence,coding-agents
 Author: Nace AI
@@ -50,13 +50,14 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi extract SOURCE -s SCHEMA` | Structured extract (`--validate` checks a schema with no job) |
 | `ndi split SOURCE --class id:label` | Logical sections |
 | `ndi classify SOURCE --class id:label` | Labels (refuses `jobid://`) |
-| `ndi ground SOURCE --target id=TEXT` | Locate quoted text |
+| `ndi ground SOURCE --target id=TEXT` | Locate quoted text (standalone quotes only; after search, poll `grounding_job_ids`) |
 | `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
 | `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
-| `ndi files upload\|list\|get\|delete` | Workspace files (`--ingest` uploads then queues ingestion) |
+| `ndi files upload\|list\|get\|delete` | Workspace files (a directory walks nested files; `--ingest` then queues ingestion) |
 | `ndi ingest` | Queue ingestion |
-| `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search |
-| `ndi je-testing QUERY` | Journal-entry testing over a ledger package (`--path` to scope it, `--effort` for the level) |
+| `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search; then `ndi job` on each printed `grounding_job_ids` entry |
+| `ndi filtered-search QUERY` | Corpus filter/rank/count over the metadata catalog (`--cursor` pages an earlier run) |
+| `ndi je-testing QUERY` | Journal-entry testing over a ledger package (`--path` to scope it, `--reasoning-effort` for the thinking budget) |
 | `ndi folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |
 
 ## Sources
@@ -73,8 +74,15 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 
 ```bash
 ndi parse a.pdf -o id | ndi extract - -s schema.json
+ndi files upload ./corpus --ingest
 ```
 
+`ndi files upload DIR` keeps relative paths under `--path` (default: the
+directory name) and uploads in parallel (`-j`, default 8). Unsupported
+files (and `.DS_Store`) are skipped; a warning on stderr lists them when
+the run finishes. `--ingest` then queues ingestion in batches of 1000
+file ids. A single file still requires `--path`.
+
 ## Output
 
 Result content goes to **stdout**; status (`job <id> queued`, `saved …`) goes
@@ -82,9 +90,20 @@ to **stderr**. `-o auto|md|json|payload|id` picks the shape. `--json` is an
 alias for `-o json`. `--save PATH` / `--out-dir DIR` write files. `--async`
 submits and prints the job id.
 
+When a Parse result has external complete content, `-o auto` and `-o md` print
+the inline preview. Use `-o json` or `-o payload` to inspect its disclosure and
+authenticated full-content URL. A final-size preview carries
+`content_truncated`; reduced-layout Office parsing carries `parse_fidelity`.
+Documents use `document.content_url`; workbooks use the affected
+`document.spreadsheet.sheets[].content_url`. The CLI does not download these
+URLs automatically.
+
 API failures exit 1. Usage / config errors exit 2. Schema-validation
 failures also show up to five field constraints, each limited to 500
 characters; request input and unrelated error-detail fields are omitted.
+Unsupported inputs print `error: 422 [unsupported_file_type] ...` to stderr and
+exit 1. `ndi upload` prints no handle, document operations print no job ID, and
+`ndi files upload --ingest` creates no workspace file or ingestion job.
 
 See the [CLI guide](https://docs.ndi.nace.ai/guides/cli) for the full command
 reference. `SKILL.md` is the agent-facing guide to the six workspace tools.

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/README.md

@@ -26,13 +26,14 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 | `ndi extract SOURCE -s SCHEMA` | Structured extract (`--validate` checks a schema with no job) |
 | `ndi split SOURCE --class id:label` | Logical sections |
 | `ndi classify SOURCE --class id:label` | Labels (refuses `jobid://`) |
-| `ndi ground SOURCE --target id=TEXT` | Locate quoted text |
+| `ndi ground SOURCE --target id=TEXT` | Locate quoted text (standalone quotes only; after search, poll `grounding_job_ids`) |
 | `ndi job ID` / `ndi jobs` / `ndi cancel ID` | Inspect or cancel jobs |
 | `ndi workspace create\|list\|get\|stats\|delete\|use` | Workspace lifecycle |
-| `ndi files upload\|list\|get\|delete` | Workspace files (`--ingest` uploads then queues ingestion) |
+| `ndi files upload\|list\|get\|delete` | Workspace files (a directory walks nested files; `--ingest` then queues ingestion) |
 | `ndi ingest` | Queue ingestion |
-| `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search |
-| `ndi je-testing QUERY` | Journal-entry testing over a ledger package (`--path` to scope it, `--effort` for the level) |
+| `ndi deep-search QUERY` / `ndi fact-search QUERY` | Agentic / single-shot search; then `ndi job` on each printed `grounding_job_ids` entry |
+| `ndi filtered-search QUERY` | Corpus filter/rank/count over the metadata catalog (`--cursor` pages an earlier run) |
+| `ndi je-testing QUERY` | Journal-entry testing over a ledger package (`--path` to scope it, `--reasoning-effort` for the thinking budget) |
 | `ndi folder-metadata` / `file-metadata` / `read-file` / `ask-file` / `run-sql` / `hybrid-search` | Read-only workspace tools (the sandbox surface) |
 
 ## Sources
@@ -49,8 +50,15 @@ config location. Workspace-scoped verbs also take `--workspace ID`.
 
 ```bash
 ndi parse a.pdf -o id | ndi extract - -s schema.json
+ndi files upload ./corpus --ingest
 ```
 
+`ndi files upload DIR` keeps relative paths under `--path` (default: the
+directory name) and uploads in parallel (`-j`, default 8). Unsupported
+files (and `.DS_Store`) are skipped; a warning on stderr lists them when
+the run finishes. `--ingest` then queues ingestion in batches of 1000
+file ids. A single file still requires `--path`.
+
 ## Output
 
 Result content goes to **stdout**; status (`job <id> queued`, `saved …`) goes
@@ -58,9 +66,20 @@ to **stderr**. `-o auto|md|json|payload|id` picks the shape. `--json` is an
 alias for `-o json`. `--save PATH` / `--out-dir DIR` write files. `--async`
 submits and prints the job id.
 
+When a Parse result has external complete content, `-o auto` and `-o md` print
+the inline preview. Use `-o json` or `-o payload` to inspect its disclosure and
+authenticated full-content URL. A final-size preview carries
+`content_truncated`; reduced-layout Office parsing carries `parse_fidelity`.
+Documents use `document.content_url`; workbooks use the affected
+`document.spreadsheet.sheets[].content_url`. The CLI does not download these
+URLs automatically.
+
 API failures exit 1. Usage / config errors exit 2. Schema-validation
 failures also show up to five field constraints, each limited to 500
 characters; request input and unrelated error-detail fields are omitted.
+Unsupported inputs print `error: 422 [unsupported_file_type] ...` to stderr and
+exit 1. `ndi upload` prints no handle, document operations print no job ID, and
+`ndi files upload --ingest` creates no workspace file or ingestion job.
 
 See the [CLI guide](https://docs.ndi.nace.ai/guides/cli) for the full command
 reference. `SKILL.md` is the agent-facing guide to the six workspace tools.

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.7.0"
+version = "0.9.0"
 description = "NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools"
 readme = "README.md"
 license = "MIT"

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ndi-cli"
-version = "0.7.0"
+version = "0.9.0"
 description = "NDI platform CLI: document operations, jobs, workspaces, and the agent workspace tools"
 authors = [
     { name = "Nace AI", email = "engineering@nace.ai" }

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/src/ndi_cli/__init__.py

@@ -6,4 +6,4 @@ methods. The six workspace tools (``folder-metadata``, ``file-metadata``,
 in-sandbox surface.
 """
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/src/ndi_cli/_jobs.py

@@ -36,18 +36,17 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     cancel.set_defaults(run=_run_cancel, family="job", needs_workspace=False, needs_client=True)
 
 
-def wait_and_report(
+def wait_job(
     client: NdiClient,
     job: Job,
     args: argparse.Namespace,
     *,
-    auto: Callable[[Job], str],
-    stem: str,
-) -> int:
+    print_timeout_id: bool = True,
+) -> tuple[Job | None, int]:
+    """Wait for ``job``; status lines go to stderr. Does not render the result."""
     print(f"job {job.job_id} {job.status}", file=sys.stderr)
     if getattr(args, "async_submit", False):
-        print(job.job_id)
-        return 0
+        return job, 0
     try:
         if job.is_terminal:
             check_terminal(job, raise_on_failure=True)
@@ -56,12 +55,30 @@ def wait_and_report(
     except JobFailedError as exc:
         code = f" [{exc.job.error.code}]" if exc.job.error and exc.job.error.code else ""
         print(f"error:{code} {exc}", file=sys.stderr)
-        return 1
+        return exc.job, 1
     except JobTimeoutError as exc:
         print(f"error: {exc}", file=sys.stderr)
-        print(exc.job.job_id)
-        return 1
+        if print_timeout_id:
+            print(exc.job.job_id)
+        return exc.job, 1
     print(f"job {job.job_id} {job.status}", file=sys.stderr)
+    return job, 0
+
+
+def wait_and_report(
+    client: NdiClient,
+    job: Job,
+    args: argparse.Namespace,
+    *,
+    auto: Callable[[Job], str],
+    stem: str,
+) -> int:
+    job, code = wait_job(client, job, args)
+    if code != 0 or job is None:
+        return code or 1
+    if getattr(args, "async_submit", False):
+        print(job.job_id)
+        return 0
     return render_job(job, args, auto=auto, stem=stem)
 
 

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/src/ndi_cli/_render.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import json
 import sys
+import uuid
 
 import html
 import re
@@ -21,6 +22,7 @@ from ndi_sdk.models.jobs import (
     ClassifyResult,
     DeepSearchV2Result,
     ExtractResult,
+    FilteredSearchResult,
     GroundResult,
     IngestionResult,
     IntelligentSearchResult,
@@ -657,9 +659,21 @@ def ingestion_job(job: Job) -> str:
 def search_job(job: Job) -> str:
     result = job.result
     if isinstance(result, DeepSearchV2Result):
-        return _search_result(result.answer, result.clarification, result.evidences, receipts=len(result.sql_receipts))
+        return _search_result(
+            result.answer,
+            result.clarification,
+            result.evidences,
+            receipts=len(result.sql_receipts),
+            grounding_job_ids=result.grounding_job_ids,
+        )
     if isinstance(result, IntelligentSearchResult):
-        return _search_result(result.answer, result.clarification, result.evidences, receipts=0)
+        return _search_result(
+            result.answer,
+            result.clarification,
+            result.evidences,
+            receipts=0,
+            grounding_job_ids=result.grounding_job_ids,
+        )
     return job_line(job)
 
 
@@ -703,10 +717,155 @@ def je_testing_job(job: Job) -> str:
         lines.append(f"quality: {result.quality.status}")
     if result.exhausted:
         lines.append("exhausted: step budget ran out before the procedure finished")
+    lines.extend(_grounding_job_lines(result.grounding_job_ids))
     return "\n".join(lines)
 
 
-def _search_result(answer: str | None, clarification: str | None, evidences: list, *, receipts: int) -> str:
+#: What a cell's non-``found`` status means, glossed for a reader who has only
+#: this text. A field nothing could be read from is not an absent one, and
+#: neither is one that resisted normalizing — keeping them distinct is what
+#: makes a thin row interpretable without opening the JSON.
+_CELL_STATUS = {
+    "not_found": "examined; field absent",
+    "ambiguous": "present, not normalizable",
+    "unexamined": "extraction could not say",
+}
+
+
+def _cell_value(cell) -> str:
+    value = cell.value
+    if value is None:
+        return _CELL_STATUS.get(cell.status, cell.status)
+    match value.kind:
+        case "money":
+            # Amounts keep their own currency here because the server never
+            # converts one either; comparing across currencies is unsupported,
+            # so dropping the code would invent a comparison.
+            assumed = " (currency assumed)" if value.currency_source == "assumed" else ""
+            return f"{value.currency} {value.amount}{assumed}"
+        case "text":
+            return _clip(value.text)
+        case "date":
+            return value.date
+        case "number":
+            return value.number
+        case "boolean":
+            return "true" if value.value else "false"
+    return value.kind
+
+
+def _page_range(row) -> str:
+    if row.page_start is None:
+        return ""
+    if row.page_end is not None and row.page_end != row.page_start:
+        return f" (pages {row.page_start}-{row.page_end})"
+    return f" (page {row.page_start})"
+
+
+def _filtered_rows(result: FilteredSearchResult) -> list[str]:
+    """The rows, carrying the columns their membership hinges on.
+
+    A count-style question confirms ``total_matches`` and returns no rows at
+    all, so an empty listing is an answer rather than a gap — it prints nothing
+    instead of an empty header.
+    """
+    if not result.rows:
+        return []
+    # The server marks which columns its published query filtered or ranked on,
+    # and those are the values every row's membership depends on; `requested` is
+    # what the reader asked to see. Everything else is context, left for --json.
+    hinges = [column.field for column in result.columns if column.filtered]
+    shown = hinges + [column.field for column in result.columns if column.requested and column.field not in hinges]
+    lines = [f"rows ({len(result.rows)}):"]
+    for row in result.rows:
+        where = f" [{row.component}]" if row.component else ""
+        lines.append(f"  {row.source_path}{where}{_page_range(row)}")
+        for field in shown or list(dict.fromkeys(cell.field for cell in row.cells)):
+            # A repeated column carries one cell per item, so join them rather
+            # than showing the first and implying the field held one value.
+            values = [_cell_value(cell) for cell in row.cells if cell.field == field]
+            if values:
+                lines.append(f"    {field}: {'; '.join(values)}")
+    return lines
+
+
+def _filtered_caveats(result: FilteredSearchResult) -> list[str]:
+    lines: list[str] = []
+    if not result.exhaustive:
+        lines.append("not exhaustive: the matches are valid, but total_matches is a floor and not a census")
+    if result.truncated:
+        lines.append("truncated: the published query matched more than this page carries")
+    if result.catalog_drifted:
+        lines.append("catalog drifted: the underlying data changed since the query first ran")
+    # `exhaustive` is scope-wide and almost always false, so it cannot say *what*
+    # was incomplete. Only a resolved value satisfies a predicate, so a field the
+    # extraction could not read drops its components silently — a correct query
+    # coming back thin for a reason unrelated to the question.
+    for entry in result.field_readability:
+        read = f"{entry.readable} of {entry.in_scope} values read"
+        if entry.readable == 0:
+            lines.append(f"unreadable: {entry.field} — {read}; a thin result here reflects that, not an absence")
+        else:
+            lines.append(f"partly readable: {entry.field} — {read}")
+    check = result.content_verification
+    if check and check.unverified_candidates:
+        lines.append(
+            f"content check: {check.unverified_candidates} of {check.candidates} candidates unverified "
+            f"for {_clip(check.condition, 120)!r} — unknown is not a non-match"
+        )
+    lines.extend(_coverage_lines(result.coverage))
+    if result.exhausted:
+        lines.append("exhausted: step budget ran out before the query finished")
+    return lines
+
+
+def filtered_search_job(job: Job) -> str:
+    """The totals, then the rows behind them — a catalog answer read at a glance.
+
+    A filter/rank/count question is answered by a number, so this leads with the
+    counts and prints the published query under them: the figure and the
+    statement it came out of travel together, the way a JET figure names its
+    receipt. Rows carry the columns the matches hinge on; ``-o json`` has every
+    cell, citation and column the catalog returned.
+    """
+    result = job.result
+    if not isinstance(result, FilteredSearchResult):
+        return job_line(job)
+    lines: list[str] = []
+    if result.interpretation:
+        lines.append(f"interpretation: {_clip(result.interpretation)}")
+    files = f" ({result.total_files} files)" if result.total_files is not None else ""
+    confidence = f" | confidence: {result.confidence}" if result.confidence else ""
+    lines.append(f"matches: {result.total_matches}{files}{confidence}")
+    if result.applied_query:
+        lines.append(f"query: {_clip(result.applied_query, 300)}")
+    lines.extend(_filtered_rows(result))
+    lines.extend(_filtered_caveats(result))
+    if result.next_cursor:
+        lines.append(f"next: {result.next_cursor}")
+    return "\n".join(lines)
+
+
+def _grounding_job_lines(ids: list[uuid.UUID] | None) -> list[str]:
+    """Tell the reader which Ground jobs to poll after this search result."""
+    if ids is None:
+        return []
+    if not ids:
+        return ["grounding_job_ids: none planned"]
+    lines = ["grounding_job_ids (poll each with ndi job <id>):"]
+    for item in ids:
+        lines.append(f"  {item}")
+    return lines
+
+
+def _search_result(
+    answer: str | None,
+    clarification: str | None,
+    evidences: list,
+    *,
+    receipts: int,
+    grounding_job_ids: list[uuid.UUID] | None = None,
+) -> str:
     lines: list[str] = []
     if clarification:
         lines.append(f"clarification: {clarification}")
@@ -720,4 +879,5 @@ def _search_result(answer: str | None, clarification: str | None, evidences: lis
             lines.append(f"   {evidence.quote}")
     if receipts:
         lines.append(f"receipts: {receipts}")
+    lines.extend(_grounding_job_lines(grounding_job_ids))
     return "\n".join(lines)

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/src/ndi_cli/_sources.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import re
 import sys
 import uuid
+from dataclasses import dataclass
 from pathlib import Path
 
 from ndi_sdk.client import NdiClient
@@ -49,6 +50,38 @@ SUPPORTED_SUFFIXES = frozenset(
         ".mov",
     }
 )
+# Workspace file upload admits more suffixes than document-ops parse: HTML,
+# plaintext, markdown, email, extra media, and the JSON family that ingest
+# routes even when the console picker omits them.
+WORKSPACE_UPLOAD_SUFFIXES = SUPPORTED_SUFFIXES | {
+    ".html",
+    ".htm",
+    ".txt",
+    ".log",
+    ".md",
+    ".mdx",
+    ".eml",
+    ".msg",
+    ".oft",
+    ".xml",
+    ".docm",
+    ".bmp",
+    ".flac",
+    ".ogg",
+    ".oga",
+    ".mpga",
+    ".avi",
+    ".mkv",
+}
+_SKIP_NAMES = frozenset({".ds_store"})
+
+
+@dataclass(frozen=True)
+class WorkspaceUploadSelection:
+    """Local files a workspace folder upload will send, versus ones it skips."""
+
+    accepted: list[Path]
+    skipped: list[Path]
 
 
 class SourceError(ValueError):
@@ -76,6 +109,42 @@ def collect_specs(spec: str) -> list[str]:
     return [spec]
 
 
+def collect_workspace_uploads(root: Path) -> WorkspaceUploadSelection:
+    """Split a directory into uploadable files and ones the workspace API will refuse."""
+    children = sorted((child for child in root.rglob("*") if child.is_file()), key=lambda path: str(path))
+    accepted: list[Path] = []
+    skipped: list[Path] = []
+    for child in children:
+        if child.name.lower() in _SKIP_NAMES or child.suffix.lower() not in WORKSPACE_UPLOAD_SUFFIXES:
+            skipped.append(child)
+        else:
+            accepted.append(child)
+    return WorkspaceUploadSelection(accepted=accepted, skipped=skipped)
+
+
+def workspace_dest_path(relative: Path, *, prefix: str | None) -> str:
+    """Join a workspace prefix with a path relative to the uploaded directory."""
+    rel = relative.as_posix().lstrip("/")
+    if not prefix or prefix.strip("/") in ("", "."):
+        return rel
+    return f"{prefix.strip('/')}/{rel}"
+
+
+def folder_upload_prefix(root: Path, path_arg: str | None) -> str:
+    """Workspace destination prefix for a directory upload.
+
+    ``--path`` wins. Otherwise the directory's name. ``.`` / ``..`` have no
+    usable ``Path.name``, so those resolve to the real folder name instead of
+    uploading into the workspace root.
+    """
+    if path_arg is not None:
+        return path_arg
+    name = root.name
+    if name in ("", ".", ".."):
+        name = root.resolve().name
+    return name
+
+
 def resolve_source(
     spec: str,
     *,

{ndi_cli-0.7.0 → ndi_cli-0.9.0}/src/ndi_cli/_workspace.py

@@ -3,17 +3,27 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
 from pathlib import Path
 
 from ndi_sdk.client import NdiClient
 from ndi_sdk.credentials import write_config
-from ndi_sdk.models.jobs import Job
+from ndi_sdk.errors import ErrorCode, JobFailedError, JobTimeoutError, NdiError, NdiStatusError
+from ndi_sdk.models.jobs import Job, UploadFileResult
+from ndi_sdk.resources.jobs import check_terminal
 
 from ndi_cli import _render
 from ndi_cli._config import ConfigError, config_path, read_config_values, resolve_settings
-from ndi_cli._jobs import wait_and_report
-from ndi_cli._output import add_job_output_args, emit_text, output_mode
+from ndi_cli._jobs import wait_and_report, wait_job
+from ndi_cli._output import add_job_output_args, emit_text, output_mode, _content_failure
+from ndi_cli._sources import collect_workspace_uploads, folder_upload_prefix, workspace_dest_path
+
+DEFAULT_UPLOAD_PARALLEL = 8
+INGEST_FILE_ID_BATCH = 1000
+_SKIP_WARNING_LIST_CAP = 20
 
 
 def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
@@ -50,11 +60,22 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     files = sub.add_parser("files", help="Upload, list, inspect, or delete workspace files.")
     fs = files.add_subparsers(dest="files_command", required=True)
 
-    f_upload = fs.add_parser("upload", parents=[common], help="Upload a file into a workspace.")
-    f_upload.add_argument("file")
-    f_upload.add_argument("--path", required=True, help="Workspace destination path.")
+    f_upload = fs.add_parser("upload", parents=[common], help="Upload a file or folder into a workspace.")
+    f_upload.add_argument("file", help="Local file, or a directory to walk recursively.")
+    f_upload.add_argument(
+        "--path",
+        default=None,
+        help="Workspace destination path (required for a file). For a directory, a prefix; default is the directory name.",
+    )
     f_upload.add_argument("--on-conflict", choices=("reject", "new_version"), default="reject")
     f_upload.add_argument("--ingest", action="store_true", help="Queue ingestion after the upload.")
+    f_upload.add_argument(
+        "-j",
+        type=int,
+        default=DEFAULT_UPLOAD_PARALLEL,
+        dest="parallel",
+        help=f"Parallel uploads for a directory (default {DEFAULT_UPLOAD_PARALLEL}).",
+    )
     add_job_output_args(f_upload)
     f_upload.set_defaults(run=_run_files_upload, family="workspace", needs_workspace=True, needs_client=True)
 
@@ -95,14 +116,30 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
     add_job_output_args(fact)
     fact.set_defaults(run=_run_fact_search, family="workspace", needs_workspace=True, needs_client=True)
 
+    filtered = sub.add_parser(
+        "filtered-search", parents=[common], help="Run a filter/rank/count query over the metadata catalog."
+    )
+    filtered.add_argument("query", nargs="?", default=None)
+    filtered.add_argument(
+        "--cursor", default=None, help="Page an earlier run: paste its result's next_cursor. A page is a new job."
+    )
+    filtered.add_argument("--prefix", default=None, dest="path_prefix")
+    filtered.add_argument("--context", default=None)
+    # No --result-unit: the server deprecates the grouping override and returns
+    # catalog entries. No --allow-clarification: a clarification is answered by a
+    # new initial query, and a shell has nowhere to keep the thread — the reason
+    # deep-search omits --session-id.
+    add_job_output_args(filtered)
+    filtered.set_defaults(run=_run_filtered_search, family="workspace", needs_workspace=True, needs_client=True)
+
     jet = sub.add_parser("je-testing", parents=[common], help="Run journal-entry testing over a ledger package.")
     jet.add_argument("query")
-    jet.add_argument("--effort", choices=("low", "medium", "high"), default=None)
+    jet.add_argument("--reasoning-effort", choices=("none", "minimal", "low", "medium", "high"), default=None)
     jet.add_argument("--prefix", default=None, dest="path_prefix")
     jet.add_argument("--path", action="append", dest="paths", default=None, help="Scope to this file; repeatable.")
     jet.add_argument("--context", default=None)
     # No --session-id, for the reason deep-search omits it: a shell has nowhere
-    # to keep a thread. Omitting --effort leaves the deployment's own floor.
+    # to keep a thread. Omitting --reasoning-effort uses the service default.
     add_job_output_args(jet)
     jet.set_defaults(run=_run_je_testing, family="workspace", needs_workspace=True, needs_client=True)
 
@@ -170,9 +207,14 @@ def _run_ws_use(args: argparse.Namespace) -> int:
 
 def _run_files_upload(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
     path = Path(args.file)
+    if path.is_dir():
+        return _run_folder_upload(client, workspace_id, args, path)
     if not path.is_file():
         print(f"error: file not found: {args.file}", file=sys.stderr)
         return 2
+    if not args.path:
+        print("error: --path is required when uploading a single file", file=sys.stderr)
+        return 2
     dest = args.path.lstrip("/")
     if args.ingest:
         result = client.upload_and_ingest(
@@ -187,6 +229,165 @@ def _run_files_upload(client: NdiClient, workspace_id: str, args: argparse.Names
     return _finish_job(client, job, args, _render.job_line, path.stem)
 
 
+@dataclass(frozen=True)
+class _UploadOutcome:
+    kind: str
+    dest: str
+    file_id: str | None = None
+    error: str | None = None
+
+
+def _run_folder_upload(client: NdiClient, workspace_id: str, args: argparse.Namespace, root: Path) -> int:
+    selection = collect_workspace_uploads(root)
+    skipped = [_rel(root, path) for path in selection.skipped]
+    if not selection.accepted:
+        _print_skip_warning(skipped)
+        print(f"error: no supported files under {args.file}", file=sys.stderr)
+        return 2
+    prefix = folder_upload_prefix(root, args.path)
+    workers = max(1, args.parallel)
+    outcomes: list[_UploadOutcome] = []
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = [
+            pool.submit(
+                _upload_one,
+                client,
+                workspace_id,
+                local,
+                workspace_dest_path(local.relative_to(root), prefix=prefix),
+                args,
+            )
+            for local in selection.accepted
+        ]
+        for future in as_completed(futures):
+            outcomes.append(future.result())
+    uploaded = [item for item in outcomes if item.kind == "ok"]
+    skipped.extend(item.dest for item in outcomes if item.kind == "skipped")
+    failed = [item for item in outcomes if item.kind == "failed"]
+    json_mode = output_mode(args) == "json"
+    if not json_mode:
+        print(f"uploaded {len(uploaded)}")
+        for item in sorted(uploaded, key=lambda row: row.dest):
+            print(f"  {item.dest}")
+        for item in failed:
+            print(f"error: {item.dest}: {item.error}", file=sys.stderr)
+    _print_skip_warning(skipped)
+    ingestions: list[Job] | None = None
+    code = 1 if failed else 0
+    if not failed and args.ingest:
+        file_ids = [item.file_id for item in uploaded if item.file_id]
+        if not file_ids:
+            if json_mode:
+                _emit_folder_upload_json(uploaded, skipped, failed, ingestions=[], args=args)
+            print("error: no uploaded file ids to ingest", file=sys.stderr)
+            return 1
+        ingestions, code = _ingest_file_ids(client, workspace_id, args, file_ids, report=not json_mode)
+    if json_mode:
+        emit_code = _emit_folder_upload_json(uploaded, skipped, failed, ingestions, args)
+        return emit_code or code
+    return code
+
+
+def _upload_one(
+    client: NdiClient,
+    workspace_id: str,
+    local: Path,
+    dest: str,
+    args: argparse.Namespace,
+) -> _UploadOutcome:
+    try:
+        job = client.files.upload(workspace_id, local, path=dest, on_conflict=args.on_conflict)
+        if not getattr(args, "async_submit", False):
+            if job.is_terminal:
+                check_terminal(job, raise_on_failure=True)
+            else:
+                job = client.jobs.wait(job.job_id, timeout=args.timeout)
+        return _UploadOutcome(kind="ok", dest=dest, file_id=_uploaded_file_id(job))
+    except NdiStatusError as exc:
+        if exc.status_code == 422 and exc.code == ErrorCode.UNSUPPORTED_FILE_TYPE:
+            return _UploadOutcome(kind="skipped", dest=dest, error=exc.message)
+        return _UploadOutcome(kind="failed", dest=dest, error=str(exc))
+    except (NdiError, JobFailedError, JobTimeoutError) as exc:
+        return _UploadOutcome(kind="failed", dest=dest, error=str(exc))
+
+
+def _uploaded_file_id(job: Job) -> str | None:
+    result = job.result
+    if isinstance(result, UploadFileResult):
+        return str(result.file.file_id)
+    return None
+
+
+def _emit_folder_upload_json(
+    uploaded: list[_UploadOutcome],
+    skipped: list[str],
+    failed: list[_UploadOutcome],
+    ingestions: list[Job] | None,
+    args: argparse.Namespace,
+) -> int:
+    payload: dict = {
+        "uploaded": [{"path": item.dest, "file_id": item.file_id} for item in sorted(uploaded, key=lambda row: row.dest)],
+        "skipped": sorted(skipped),
+        "failed": [{"path": item.dest, "error": item.error} for item in failed],
+    }
+    if ingestions is not None:
+        payload["ingestions"] = [json.loads(job.model_dump_json(exclude_none=True)) for job in ingestions]
+    return emit_text(json.dumps(payload, indent=2), args, default_stem="upload", suffix=".json")
+
+
+def _ingest_file_ids(
+    client: NdiClient,
+    workspace_id: str,
+    args: argparse.Namespace,
+    file_ids: list[str],
+    *,
+    report: bool = True,
+) -> tuple[list[Job], int]:
+    jobs: list[Job] = []
+    code = 0
+    for start in range(0, len(file_ids), INGEST_FILE_ID_BATCH):
+        chunk = file_ids[start : start + INGEST_FILE_ID_BATCH]
+        try:
+            job = client.ingestion.ingest(workspace_id, file_ids=chunk)
+        except NdiError as exc:
+            if report:
+                raise
+            print(f"error: {exc}", file=sys.stderr)
+            return jobs, 1
+        if report:
+            chunk_code = _finish_job(client, job, args, _render.ingestion_job, "ingest")
+            if chunk_code != 0:
+                code = chunk_code
+            continue
+        waited, wait_code = wait_job(client, job, args, print_timeout_id=False)
+        if waited is not None:
+            jobs.append(waited)
+            code = code or wait_code or _content_failure(waited)
+        elif wait_code:
+            code = wait_code
+    return jobs, code
+
+
+def _print_skip_warning(skipped: list[str]) -> None:
+    if not skipped:
+        return
+    ordered = sorted(skipped)
+    print(f"warning: skipped {len(ordered)} unsupported file(s):", file=sys.stderr)
+    shown = ordered[:_SKIP_WARNING_LIST_CAP]
+    for name in shown:
+        print(f"  {name}", file=sys.stderr)
+    remaining = len(ordered) - len(shown)
+    if remaining:
+        print(f"  ... and {remaining} more", file=sys.stderr)
+
+
+def _rel(root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return str(path)
+
+
 def _run_files_list(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
     page = client.files.list(workspace_id, path_prefix=args.path_prefix, ingestion_status=args.statuses)
     return _dump_or_text(page, args, text=_render.file_page(page), stem="files")
@@ -237,12 +438,37 @@ def _run_fact_search(client: NdiClient, workspace_id: str, args: argparse.Namesp
     return _finish_job(client, job, args, _render.search_job, "fact-search")
 
 
+def _run_filtered_search(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
+    if args.query and args.cursor:
+        print("error: pass a query or --cursor, not both", file=sys.stderr)
+        return 2
+    if not args.query and not args.cursor:
+        print("error: pass a query, or --cursor to page an earlier run", file=sys.stderr)
+        return 2
+    if args.cursor:
+        # A page re-executes the parent's own stored query, so the scoping flags
+        # cannot apply to it. Accepting and dropping them would quietly answer a
+        # different question than the one typed.
+        if args.path_prefix or args.context:
+            print("error: --prefix and --context belong to the initial query, not a page", file=sys.stderr)
+            return 2
+        job = client.search.filtered_page(workspace_id, cursor=args.cursor)
+    else:
+        job = client.search.filtered(
+            workspace_id,
+            query=args.query,
+            context=args.context,
+            path_prefix=args.path_prefix,
+        )
+    return _finish_job(client, job, args, _render.filtered_search_job, "filtered-search")
+
+
 def _run_je_testing(client: NdiClient, workspace_id: str, args: argparse.Namespace) -> int:
     job = client.search.je_testing(
         workspace_id,
         query=args.query,
         context=args.context,
-        effort=args.effort,
+        reasoning_effort=args.reasoning_effort,
         path_prefix=args.path_prefix,
         paths=args.paths,
     )