update docs

Author: ziodave

docs/worai/commands/graph.md

@@ -7,10 +7,20 @@ title: graph
 Run graph-specific workflows.
 
 ## Usage
-- `worai graph sync --profile <name> [--debug]`
-- `worai --config <path> graph sync --profile <name> [--debug]`
+- `worai graph sync run --profile <name> [--debug]`
+- `worai --config <path> graph sync run --profile <name> [--debug]`
+- `worai graph sync create <destination> [--template <src>] [--defaults] [--data-file <path>] [--vcs-ref <ref>] [--non-interactive] [--force]`
+- `worai graph property delete <predicate> [--dry-run] [--yes] [--workers <n>] [--retries <n>] [--rate-delay <s>] [--limit <n>]`
 
 ## Notes
+- `graph sync run` executes the graph sync workflow for a profile in `worai.toml`.
+- `graph sync create` bootstraps a new graph sync project from a Copier template.
+- `graph sync create` enables Copier trusted mode by default, so template `_tasks` run automatically.
+- `graph property delete` removes one predicate from all matching entities.
+  - accepts full IRI (`https://w3id.org/seovoc/html`) or CURIE (`seovoc:html`).
+  - includes private fields by default (`X-include-Private: true`) for both matching-entity discovery and deletion PATCH requests.
+  - `--dry-run` reports matching entities without patching.
+  - without `--yes`, the command asks for confirmation before patching.
 - Supported input sources:
   - `urls` (explicit URL list)
   - `sitemap_url` (+ optional `sitemap_url_pattern`)
@@ -24,6 +34,23 @@ Run graph-specific workflows.
   - profile value overrides global value.
   - default is `false` when unset.
   - mapped to SDK setting `GOOGLE_SEARCH_CONSOLE`.
+- SDK 5 ingestion settings are forwarded when configured:
+  - `ingest.source`: `auto|urls|sitemap|sheets|local`
+  - `ingest.loader`: `auto|simple|proxy|playwright|premium_scraper|web_scrape_api|passthrough`
+  - `ingest.passthrough_when_html`: default `true`
+- Loader default behavior is `web_scrape_api`.
+  - legacy `web_page_import_mode=default` maps to `web_scrape_api`
+  - legacy `proxy` and `premium_scraper` keep the same value
+Example ingestion config:
+```toml
+[profile.acme]
+api_key = "wl_..."
+sitemap_url = "https://example.com/sitemap.xml"
+ingest.source = "sitemap"
+ingest.loader = "web_scrape_api"
+ingest.passthrough_when_html = true
+web_page_import_timeout = "60s"
+```
 - `sheets_service_account` is required only when using Google Sheets source (`sheets_url` + `sheets_name`).
 - Failure cases for `sheets_service_account` (Sheets source only):
   - value is missing or empty
@@ -41,6 +68,9 @@ sheets_service_account = "./service-account.json"
 ```
 
 ## Examples
-- `worai graph sync --profile acme`
-- `worai --config ./worai.toml graph sync --profile acme`
-- `worai graph sync --profile acme --debug`
+- `worai graph sync run --profile acme`
+- `worai --config ./worai.toml graph sync run --profile acme`
+- `worai graph sync run --profile acme --debug`
+- `worai graph sync create ./acme-graph`
+- `worai graph property delete seovoc:html --dry-run`
+- `worai graph property delete https://w3id.org/seovoc/html --yes --workers 4`

docs/worai/commands/structured-data.md

@@ -113,6 +113,9 @@ Parse all URLs from a sitemap, extract JSON-LD from each page, and export a stru
 | `--timeout` | float | `30.0` | HTTP timeout in seconds for sitemap and page fetches. |
 | `--concurrency` | string | `auto` | Worker count or `auto` to adapt to fetch/parse responses. |
 | `--source-type` | string | none | Optional source parser override (e.g., `debug-cloud`). |
+| `--ingest-source` | string | none | SDK 5 source axis: `auto`, `urls`, `sitemap`, `sheets`, `local`. |
+| `--ingest-loader` | string | none | SDK 5 loader axis: `auto`, `simple`, `proxy`, `playwright`, `premium_scraper`, `web_scrape_api`, `passthrough`. |
+| `--ingest-passthrough-when-html / --no-ingest-passthrough-when-html` | bool | config/default | Prefer passthrough when source records include embedded HTML. |
 
 ### Output columns
 - `url`
@@ -128,11 +131,32 @@ Parse all URLs from a sitemap, extract JSON-LD from each page, and export a stru
 - Fetches page content with Playwright using the shared worai default User-Agent.
 - Shows a progress bar while processing source URLs.
 - Supports adaptive concurrency via `--concurrency auto`.
+- Ingestion precedence:
+  - new ingest settings (`--ingest-*` or `ingest.*` config) win over legacy when both are set
+  - legacy remains supported when new is unset
+  - disagreements emit a structured warning event
+- Loader defaults:
+  - default and `auto` loader resolve to `web_scrape_api`
+  - passthrough takes precedence when embedded HTML exists and passthrough-when-html is enabled
+- `worai.toml` examples:
+```toml
+[ingest]
+source = "auto"
+loader = "web_scrape_api"
+passthrough_when_html = true
+```
+
+```toml
+[profile.inventory_local]
+ingest.source = "local"
+ingest.loader = "passthrough"
+ingest.passthrough_when_html = true
+```
 - Local URL list file support:
   - `.txt`: one URL per line
   - `.csv`: requires `url` column
 - When using a Google Spreadsheet as source, `--sheet-name` is required.
-- `--source-type debug-cloud` supports `.ttl` debug artifacts by reading:
+- `--source-type debug-cloud` (legacy alias of `--ingest-source local`) supports `.ttl` debug artifacts by reading:
   - URL from `http://schema.org/url`
   - HTML from `https://w3id.org/seovoc/html`
 
@@ -143,3 +167,5 @@ Parse all URLs from a sitemap, extract JSON-LD from each page, and export a stru
 - `worai structured-data inventory https://example.com/sitemap.xml --destination-sheet-id 1AbCdEfGhIjKlMnOp --destination-sheet-name Inventory`
 - `worai structured-data inventory https://example.com/sitemap.xml --output ./structured-data-inventory.csv --concurrency auto`
 - `worai structured-data inventory /path/to/debug_cloud/us --source-type debug-cloud --output ./structured-data-inventory.csv`
+- `worai structured-data inventory /path/to/debug_cloud/us --ingest-source local --ingest-loader passthrough --output ./structured-data-inventory.csv`
+- `worai structured-data inventory https://example.com/sitemap.xml --ingest-loader web_scrape_api --output ./structured-data-inventory.csv`