@tiangong-ai/cli 0.0.6 → 0.0.8

package/AGENTS.md

@@ -15,8 +15,8 @@ checkPaths:
   - .docpact/config.yaml
   - docs/agents/**
   - src/**
-lastReviewedAt: 2026-05-10
-lastReviewedCommit: f45edb6f41dd767911b3788eb8bc75e9bcb8ba33
+lastReviewedAt: 2026-05-13
+lastReviewedCommit: ab6eccece7808a07d2eb50922967c25bf356066d
 ---
 
 # Tiangong AI CLI Contract

package/README.md

@@ -43,16 +43,25 @@ TIANGONG_KB_DEFAULT_COLLECTION_NAME=
 The KB API server defaults to `https://thuenv.tiangong.world:7300` with path
 prefix `/api/v1/kb`.
 
-Upload one file:
+Run a resumable sliding-window ingest for one file or a folder:
 
 ```bash
-tiangong-ai kb ingest upload /path/to/document.pdf
+tiangong-ai kb ingest bulk /path/to/document.pdf \
+  --collection-path /course/thu_humanities \
+  --poll-interval 30 \
+  --max-polls 120
 ```
 
-Upload a folder recursively with local checkpointing:
+Run a larger folder ingest:
 
 ```bash
-tiangong-ai kb ingest upload /path/to/folder --recursive --concurrency 3 --retries 3
+tiangong-ai kb ingest bulk /path/to/folder \
+  --collection-path /course/thu_humanities \
+  --window-size 100 \
+  --top-up-max 50 \
+  --upload-concurrency 4 \
+  --poll-interval 30 \
+  --max-polls 120
 ```
 
 Bulk scan a large folder and emit a structural JSON summary:
@@ -79,7 +88,7 @@ tiangong-ai kb ingest metadata dry-run /path/to/folder \
   --json
 ```
 
-Run a resumable sliding-window bulk ingest:
+Run a resumable sliding-window bulk ingest with metadata:
 
 ```bash
 tiangong-ai kb ingest bulk /path/to/folder \
@@ -88,7 +97,8 @@ tiangong-ai kb ingest bulk /path/to/folder \
   --window-size 100 \
   --top-up-max 50 \
   --upload-concurrency 4 \
-  --poll-interval 30
+  --poll-interval 30 \
+  --max-polls 120
 ```
 
 `tiangong-ai kb ingest bulk run /path/to/folder` is accepted as an explicit
@@ -101,17 +111,19 @@ stored under the OS app-data directory:
 - Linux: `~/.local/share/tiangong-ai/kb-ingest/jobs/<job-id>.sqlite`
 - Windows: `%APPDATA%/tiangong-ai/kb-ingest/jobs/<job-id>.sqlite`
 
-Use `--state /path/to/job.sqlite` to override the checkpoint path. Bulk jobs do
-not use `.tiangong-kb-ingest-manifest.jsonl` as their checkpoint.
+Use `--state /path/to/job.sqlite` to override the checkpoint path. Use
+`--max-polls 0` only for operator runs that should wait without a client-side
+polling limit.
 
-Bulk ingest always creates 300dpi-normalized ingest copies for `.docx` files
-and creates PDF split parts when a PDF exceeds the active upload limit. Derived
-files stay under `.tiangong-kb-ingest-derived` by default, and that directory is
-excluded from future bulk scans. DOCX copies keep the original logical path for
-metadata-map evaluation, and the generated DOCX copy is uploaded even when
-normalization does not materially reduce file size. PDF split parts keep the
-original logical parent directory. Upload metadata remains the user/business
-metadata produced by the metadata map.
+Bulk ingest scans and fingerprints files first, then lazily creates derived
+files only when a row enters the active upload window. `.docx` files larger than
+10MiB are uploaded through 300dpi-normalized ingest copies; smaller `.docx`
+files upload directly unless they are empty. Oversized PDFs are split into the
+fewest uploadable PDF parts when they enter the window, and the generated part
+rows are written back to SQLite so resume can reuse them. Derived files stay
+under `.tiangong-kb-ingest-derived` by default, and that directory is excluded
+from future bulk scans. Upload metadata remains the user/business metadata
+produced by the metadata map.
 
 Manage bulk jobs:
 
@@ -143,13 +155,13 @@ tiangong-ai kb ingest status <document-id>
 ## Boundary
 
 The CLI is a thin local client. It sends bearer-token requests to the Tiangong
-KB ingest API and records local checkpoints for batch recovery. Non-bulk upload
-still uses a JSONL manifest. Bulk ingest uses SQLite and releases sliding-window
-capacity only when document status is `completed` and both `opensearchIndexed`
-and `pineconeIndexed` are true. If the status API does not return those index
-flags yet, the file remains in `waiting_for_index_flags`. The backend owns
-authorization, collection permissions, duplicate detection, NAS raw writes,
-parse queueing, and status transitions.
+KB ingest API and records SQLite checkpoints for batch recovery. Ingest uses
+the bulk runner and releases sliding-window capacity only when document status
+is `completed` and both `opensearchIndexed` and `pineconeIndexed` are true. If
+the status API does not return those index flags yet, the file remains in
+`waiting_for_index_flags`. The backend owns authorization, collection
+permissions, duplicate detection, NAS raw writes, parse queueing, and status
+transitions.
 
 ## Validation