knowledge-one-view-cli/references/script-catalog.md

# Script Catalog

Read this file when you need the exact CLI surface of the bundled scripts without rediscovering flags from source.

Read this file for flag names, parameter conflicts, execution modes, and helper-script contracts. Skip it for routine asks that already map cleanly to a known intent or view.

## Quick Navigation

- Discovery policy: [Discovery Rule](#discovery-rule)
- Shortest path by ask type: [Minimal-Step Decision Table](#minimal-step-decision-table)
- Annual June-to-May week lookup: [Week Shortcuts](#week-shortcuts)
- Main fetch command: [Script: `fetch-sales-intelligence.mjs`](#script-fetch-sales-intelligencemjs)
- Browser refresh helper: [Script: `refresh-auth-state.mjs`](#script-refresh-auth-statemjs)
- Direct auth helper: [Script: `refresh-auth-direct.mjs`](#script-refresh-auth-directmjs)
- Quote-safe SQL helper: [Script: `run-sales-intelligence-sql.mjs`](#script-run-sales-intelligence-sqlmjs)

For manager, hierarchy, architect-productivity, or business-parameter context, read [initial-context-catalog.md](initial-context-catalog.md) first. That skill-level catalog front-loads verified manager emails, hierarchy heuristics, and common query translations so the agent can execute faster before touching the generated CLI catalog.

## Discovery Rule

- Prefer [initial-context-catalog.md](initial-context-catalog.md) first for manager or hierarchy asks.
- Prefer `node scripts/fetch-sales-intelligence.mjs --catalog` first for CLI and data-contract discovery.
- The catalog now returns `views`, `intents`, `entities`, `fields`, `macros`, `parameters`, and `scripts`.
- For focused inspection, use `--list-parameters`, `--describe-parameter`, `--list-scripts`, and `--describe-script`.
- Treat `--catalog` as a one-shot resolver, not the first step in every request.
- If the ask already maps to a known intent, view, or query pattern, execute directly and skip discovery.
- After `--catalog`, go straight to the execution command. Avoid chaining `--list-*` calls unless one exact contract detail is still missing.

## Operational Keepers

These are the local catalog items worth keeping highly visible because they reduce trial-and-error during real backend execution:

- Discovery helpers: `--catalog`, `--list-parameters`, `--describe-parameter`, `--list-scripts`, `--describe-script`.
- Workspace/runtime path controls: `--runtime-home`, `--state-path`, `--meta-path`, `--output-file`.
- Backend targeting: `--base-url`, plus auth refresh `--url`.
- Browser-auth recovery: `--profile-dir`, `--chrome-path`, `--timeout-ms`.
- Direct-auth recovery: `--username`, `--factor`.

Role-shaped placeholder emails used below are illustrative only. Keep verified hierarchy anchors in `initial-context-catalog.md`, but keep routine usage examples generic.

## Minimal-Step Decision Table

| Ask shape | Shortest default |
|---|---|
| Recurring business request | `--intent ...` |
| Known row extract | `--view ...` |
| Ad hoc aliases + filters + grouping | `--query ...` |
| Need exact Oracle expression | `--sql ...` |
| Need contract discovery | `--catalog` once |
| Need one specific flag or script | `--describe-parameter ...` or `--describe-script ...` |

## Week Shortcuts

Use these as fixed lookups for June-to-May cycle asks:

| Token | Meaning |
|---|---|
| `W1` / `week 1` | Starts on June 1 of the cycle start year |
| `W2` / `week 2` | Starts 7 days after `W1` |
| `W43` / `week 43` | Continues counting across January without resetting |
| `W53` / `week 53` | Final partial week ending on the last day of May |

CLI flags:

- `--week <token>` accepts `1..53`, `w1..w53`, or `week 1..week 53`
- `--week-year <YYYY>` selects the cycle start year for that June-to-May map
- For the explicit default-cycle table, read [Week Reference](#week-reference)

# Week Reference

Use this file for asks that mention `week`, `wk`, or `w1`..`w53`.

Week numbering is anchored on `June 1` and runs continuously until the last day of the following `May`.

Interpretation rules:

- `week-year` means the cycle start year.
- `week-year 2025` means the cycle `2025-06-01` through `2026-05-31`.
- If the user does not specify a year, default to the current June-cycle.
- Do not recalculate the default cycle in normal execution. Use the explicit table below.

## Default Cycle Lookup

Current default cycle for this workspace date context:

- `week-year 2025`
- cycle start: `2025-06-01`
- cycle end: `2026-05-31`

| Week | Start | End |
|---|---|---|
| W1 | 2025-06-01 | 2025-06-07 |
| W2 | 2025-06-08 | 2025-06-14 |
| W3 | 2025-06-15 | 2025-06-21 |
| W4 | 2025-06-22 | 2025-06-28 |
| W5 | 2025-06-29 | 2025-07-05 |
| W6 | 2025-07-06 | 2025-07-12 |
| W7 | 2025-07-13 | 2025-07-19 |
| W8 | 2025-07-20 | 2025-07-26 |
| W9 | 2025-07-27 | 2025-08-02 |
| W10 | 2025-08-03 | 2025-08-09 |
| W11 | 2025-08-10 | 2025-08-16 |
| W12 | 2025-08-17 | 2025-08-23 |
| W13 | 2025-08-24 | 2025-08-30 |
| W14 | 2025-08-31 | 2025-09-06 |
| W15 | 2025-09-07 | 2025-09-13 |
| W16 | 2025-09-14 | 2025-09-20 |
| W17 | 2025-09-21 | 2025-09-27 |
| W18 | 2025-09-28 | 2025-10-04 |
| W19 | 2025-10-05 | 2025-10-11 |
| W20 | 2025-10-12 | 2025-10-18 |
| W21 | 2025-10-19 | 2025-10-25 |
| W22 | 2025-10-26 | 2025-11-01 |
| W23 | 2025-11-02 | 2025-11-08 |
| W24 | 2025-11-09 | 2025-11-15 |
| W25 | 2025-11-16 | 2025-11-22 |
| W26 | 2025-11-23 | 2025-11-29 |
| W27 | 2025-11-30 | 2025-12-06 |
| W28 | 2025-12-07 | 2025-12-13 |
| W29 | 2025-12-14 | 2025-12-20 |
| W30 | 2025-12-21 | 2025-12-27 |
| W31 | 2025-12-28 | 2026-01-03 |
| W32 | 2026-01-04 | 2026-01-10 |
| W33 | 2026-01-11 | 2026-01-17 |
| W34 | 2026-01-18 | 2026-01-24 |
| W35 | 2026-01-25 | 2026-01-31 |
| W36 | 2026-02-01 | 2026-02-07 |
| W37 | 2026-02-08 | 2026-02-14 |
| W38 | 2026-02-15 | 2026-02-21 |
| W39 | 2026-02-22 | 2026-02-28 |
| W40 | 2026-03-01 | 2026-03-07 |
| W41 | 2026-03-08 | 2026-03-14 |
| W42 | 2026-03-15 | 2026-03-21 |
| W43 | 2026-03-22 | 2026-03-28 |
| W44 | 2026-03-29 | 2026-04-04 |
| W45 | 2026-04-05 | 2026-04-11 |
| W46 | 2026-04-12 | 2026-04-18 |
| W47 | 2026-04-19 | 2026-04-25 |
| W48 | 2026-04-26 | 2026-05-02 |
| W49 | 2026-05-03 | 2026-05-09 |
| W50 | 2026-05-10 | 2026-05-16 |
| W51 | 2026-05-17 | 2026-05-23 |
| W52 | 2026-05-24 | 2026-05-30 |
| W53 | 2026-05-31 | 2026-05-31 |

Examples:

- `week 1` -> `2025-06-01` to `2025-06-07`
- `recursos do resource.manager em pipe na week 43` -> use `--intent opportunities-by-manager-close-window --manager-email resource.manager@oracle.com --week w43`


## Script: `fetch-sales-intelligence.mjs`

Primary backend retrieval entrypoint for Oracle DV.

### Discovery flags

| Flag | Type | Description |
|---|---|---|
| `--catalog` | flag | Return the full local catalog, including script and parameter metadata. |
| `--list-views` | flag | List built-in views. |
| `--describe-view <view>` | string | Describe one built-in view. |
| `--list-intents` | flag | List recurring business intents. |
| `--describe-intent <intent>` | string | Describe one intent. |
| `--list-entities` | flag | List entities and the views that expose them. |
| `--list-fields` | flag | List local field aliases. |
| `--describe-field <alias>` | string | Describe one field alias. |
| `--list-parameters` | flag | List the parameter catalog. |
| `--describe-parameter <name-or-flag>` | string | Describe one parameter. Accepts `resource` or `--resource`. |
| `--list-scripts` | flag | List runnable scripts in the skill. |
| `--describe-script <script>` | string | Describe one bundled script. |
| `--help` | flag | Show usage. |

### Execution selectors

Choose exactly one execution mode:

| Flag | Type | Description |
|---|---|---|
| `--view <view>` | string | Run one built-in view. |
| `--intent <intent>` | string | Run one higher-level shortcut. |
| `--query` | flag | Enable declarative query mode. Requires `--select` and/or `--measure`. |
| `--sql "<logical sql>"` | string | Run custom Oracle logical SQL. |

Conflicts:

- Do not combine `--view`, `--intent`, `--query`, and `--sql`.
- `--render-sql` may be combined with `--query` or `--sql`, but not by itself.

PowerShell note:

- Prefer `--query` over `--sql` when the ask can be expressed with aliases, filters, grouping, and ordering.
- If custom SQL is still required and the logical SQL is quote-heavy, use `run-sales-intelligence-sql.mjs` with `--sql-file` or `--stdin` instead of passing a long `--sql` string directly through PowerShell.

### Global execution flags

| Flag | Type | Default | Description |
|---|---|---:|---|
| `--check-auth` | flag | `false` | Validate the saved Oracle DV session. |
| `--limit <rows>` | number | `5000` | Max rows requested from Oracle DV. |
| `--scope auto\|org-wide\|my-team` | enum | `auto` | Controls source scope. `auto` is org-wide-first for org-wide-capable XSA datasets and my-team-only for `DV - SE Team` fields. |
| `--fiscal-year FY26` | string | live session | Override fiscal year for views that need one. |
| `--runtime-home <dir>` | path | `<workspace>/knowledge-one-view-cli/runtime` | Override the workspace runtime root. |
| `--state-path <file>` | path | `<workspace>/knowledge-one-view-cli/runtime/auth-state.json` | Override auth-state location. Reads can still fall back to legacy `~/.codex/oracle-sales-intelligence-direct/auth-state.json` if the new workspace runtime is still empty. |
| `--meta-path <file>` | path | `<workspace>/knowledge-one-view-cli/runtime/session-meta.json` | Override session-meta location. Reads can still fall back to legacy `~/.codex/oracle-sales-intelligence-direct/session-meta.json` if the new workspace runtime is still empty. |
| `--base-url <url>` | string | `https://salesintelligence-dv.oracle.com` | Override DV base URL. |
| `--no-cache` | flag | `false` | Disable cache-based reuse for the run. |
| `--output-file <file>` | path | none | Also write JSON output to a file. Relative paths without a directory go under `<workspace>/knowledge-one-view-cli/output/`, except temporary/intermediate names (`tmp-*`, `temp-*`, `scratch-*`, `intermediate-*`, `render-output-*`, `*.tmp.*`, `.tmp`, `.temp`) that are routed to `<workspace>/knowledge-one-view-cli/tmp/`; other relative paths are resolved under the workspace skill folder. |
| `--render-sql` | flag | `false` | Render final SQL locally without backend execution. |

Environment fallbacks:

- `ORACLE_SI_RUNTIME_HOME`
- `ORACLE_SI_STATE_PATH`
- `ORACLE_SI_META_PATH`
- `ORACLE_SI_BASE_URL`

Auth behavior note:

- For normal execution modes other than `--check-auth`, the fetch script can automatically launch `refresh-auth-state.mjs`, wait for Oracle browser login, persist the refreshed session, and retry the backend request when auth artifacts are missing or the backend redirects to sign-in.
- `--check-auth` remains diagnostic-only and reports validity without opening the browser automatically.

### `--list-fields` filters

These apply only with `--list-fields`.

| Flag | Type | Description |
|---|---|---|
| `--entity <entity>` | string | Filter fields to one entity, such as `Opportunity`. |
| `--role <role>` | string | Filter fields by role, such as `select`, `filter`, `aggregate`, or `order`. |
| `--search <text>` | string | Search alias, entity, expression, and description. |

### Query mode flags

These apply only with `--query`.

| Flag | Type | Description |
|---|---|---|
| `--select fieldA,fieldB` | csv | Row-level field aliases. |
| `--measure aggregate:field[:alias]` | csv | Aggregate outputs, for example `sum:bookingValue:totalBooking`. |
| `--where "<predicate>"` | string | Row filter clause. Field aliases are resolved automatically. |
| `--group-by fieldA,fieldB` | csv | Explicit grouping outputs or field aliases. |
| `--having "<predicate>"` | string | Post-aggregation filter clause. |
| `--order-by field:asc|desc` | csv | Output ordering. |
| `--distinct` | flag | Emit `SELECT DISTINCT`. |
| `--scope auto\|org-wide\|my-team` | enum | Source-scope policy. In `auto`, query mode infers XSA org-wide for commercial aliases and `DV - SE Team` my-team-only for SR/session aliases. |

Org-wide commercial value aliases:

- In `--scope auto` and `--scope org-wide`, query-mode resolves `bookingValue`, `workloadAmount`, and `opportunityValue` to the org-wide `Knowledge DV - Opportunities - V2` `Pipeline` column.
- Use `pipelineAmount` when you want the backing field name to be explicit in the output.
- In `--scope my-team`, `bookingValue` and `workloadAmount` keep the `DV - SE Team` opportunity aliases.

### Date-window flags

Used by `opportunities-close-window`, the close-window intents, and the commercial `sa-attach-*` views.

| Flag | Type | Description |
|---|---|---|
| `--date YYYY-MM-DD` | string | Exact close date. |
| `--month YYYY-MM|current-month` | string | Whole calendar month. Also accepts `current-month`. |
| `--quarter FY26-Q4|Q4 FY26|current-quarter` | string | Whole fiscal quarter. Also accepts `current-quarter`. |
| `--week <1..53|w1..w53|week 1..week 53|current-week>` | string | Annual week lookup anchored on June 1. Also accepts `current-week`. |
| `--week-year <YYYY>` | number | Cycle start year used with `--week`. Defaults to the current June-cycle start year. |
| `--from-date <date>` | string | Start date. Accepts `YYYY-MM-DD`, `today`, `+7d`, `-3d`, or `today+7d`. |
| `--to-date <date>` | string | End date. Same accepted formats as `--from-date`. |
| `--opty-status Open,Won,Closed` | csv | Optional opportunity-status filter. |
| `--cluster <cluster>` | string | Optional commercial cluster filter for close-window opportunity intents. |

Rule:

- Use exactly one of `--date`, `--month`, `--quarter`, `--week`, or the pair `--from-date` plus `--to-date`.
- On `opportunities-close-window`, close-window intents, and `sa-attach-*` commercial views, these flags are applied to `Revenue Line Close Date`.
- `opportunities-close-date`, `opportunities-close-month`, `opportunities-close-quarter`, `opportunities-current-team-close-window`, `opportunities-by-resource-close-window`, and `opportunities-by-manager-close-window` honor an explicit `--cluster <cluster>` on the commercial `Knowledge DV - Opportunities - V2` window. If `--cluster` is omitted, these close-window opportunity intents preserve the existing unfiltered geography behavior rather than applying the SA Attach default cluster.

### Resource / SR flags

Used by `srs-by-resource-email`, `srs-by-resource`, and the explicit opportunity coverage intents.

| Flag | Type | Default | Description |
|---|---|---:|---|
| `--resource-email <user@oracle.com>` | string | none | Explicit Oracle email for SR matching. |
| `--resource <uid-or-email>` | string | none | Short uid or full email. Uid is normalized to `@oracle.com`. |
| `--manager-email <user@oracle.com>` | string | none | Explicit manager email for hierarchy-scoped opportunity coverage lookups. |
| `--manager-email-list emailA,emailB` | csv | none | Comma-separated manager emails for the org-wide workload-by-manager-resource intent. |
| `--match-role team|lead` | enum | `team` | Match `SR Team Level 1..4` or `Lead Email`. |
| `--sr-status Open,Closed` | csv | none | Optional SR status filter. |

Coverage result contract:

- Coverage intents preserve the full org-wide commercial window when one component is narrower than the commercial source.
- `opportunities-current-team-close-window` emits `mixed-consistent`: opportunities/workloads are org-wide, resource fields are only from the current team, and rows without a match keep empty resource fields.
- `opportunities-by-resource-close-window` and `opportunities-by-manager-close-window` use org-wide Presales Involvement Aux linkage by default, so explicit resource/manager coverage can see beyond the executing user's team.
- `workloads-by-manager-resource-close-window` emits `org-wide`: workload rows and manager/resource allocation both come from org-wide Knowledge DV sources. It honors explicit `--cluster <cluster>` on the workload commercial window and defaults to Brazil when omitted. It does not enrich SRs unless the user explicitly asks for SR details.
- When present, `scope.components` is the authoritative source-by-source disclosure for downstream wording.
- The emitted `apiMetrics.totalRowsPulledFromApi` reports the raw Oracle DV rows returned by the backend for the invocation. It does not include rows resolved only from local cache or local metadata files.

### Opportunity Coverage Intents

Use these when the ask is explicitly about opportunities tied to a person or manager in a close-date window.

| Intent | Best use |
|---|---|
| `opportunities-current-team-close-window` | Current-session team coverage path when the ask really means "my team" or current-team involvement for the executing user. Keeps the org-wide opportunity/workload rows and enriches only the current-team resource fields. |
| `opportunities-by-resource-close-window` | Explicit resource-scoped opportunity coverage in a close-date window. Keeps org-wide opportunity/workload rows and matches the named resource through org-wide `Knowledge DV - Presales Involvement Aux - V1` coverage. |
| `opportunities-by-manager-close-window` | Explicit manager-scoped opportunity coverage in a close-date window. Keeps org-wide opportunity/workload rows and matches the manager hierarchy through org-wide `Knowledge DV - Presales Involvement Aux - V1` coverage. |
| `workloads-by-manager-resource-close-window` | Org-wide workload revenue lines in a close-date window, filtered to opportunities that have Presales Involvement Aux rows under one or more explicit managers. Uses `Knowledge DV - Opportunities - V2` for workload rows and `Knowledge DV - Presales Involvement Aux - V1` for org-wide manager/resource allocation. |

Week-based example for manager coverage:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --intent opportunities-by-manager-close-window `
  --manager-email resource.manager@oracle.com `
  --week w2 `
  --week-year 2026
```

Cluster-filtered manager coverage example:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --intent opportunities-by-manager-close-window `
  --manager-email resource.manager@oracle.com `
  --month 2026-05 `
  --cluster Mexico
```

Close-window example for org-wide workloads by manager/resource:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --intent workloads-by-manager-resource-close-window `
  --manager-email-list resource.manager.a@oracle.com,resource.manager.b@oracle.com `
  --from-date today `
  --to-date +7d `
  --cluster Mexico
```

Result contract note for `workloads-by-manager-resource-close-window`:

- `managerEmails` keeps the matched manager list from Presales Involvement Aux.
- `resourceEmails` keeps the matched allocated resource list from Presales Involvement Aux.
- `resourceDetails` adds one object per resource with `resourceEmail` and `companionEmails` for the other allocated resources on the same workload row. SR detail fields are omitted in this intent because the default ask is involvement/allocation, not SR detail.

### Current Workload Intents

Use these when the ask is about how workload pipeline looks now for one seller or for sellers under one manager-of-owner.

| Intent | Best use |
|---|---|
| `workloads-by-owner-current` | Current-state workload rows for one explicit territory owner. Defaults to `current-quarter`, `Cloud Infrastructure - Workloads`, and `WORKLOAD`. |
| `workloads-by-owner-manager-current` | Current-state workload rows for owners under one explicit manager-of-owner. Defaults to `current-quarter`, `Cloud Infrastructure - Workloads`, and `WORKLOAD`. |

Both current workload intents use SA Attach commercial filters, so `--cluster <cluster>` is supported and defaults to Brazil when omitted.

Examples:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --intent workloads-by-owner-current `
  --owner-email territory.owner@oracle.com `
  --forecast-type Forecast,Upside
```

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --intent workloads-by-owner-manager-current `
  --owner-manager-email territory.manager@oracle.com `
  --quarter current-quarter `
  --forecast-type Forecast
```

### Focused Owner And Resource Close-Window Intents

Use these when the user names one business anchor and an explicit date, week, month, quarter, or relative close-date window.

| Intent | Anchor | Best use |
|---|---|---|
| `opportunities-by-owner-close-window` | `--owner-email` | Opportunities/workloads for one territory owner. |
| `opportunities-by-owner-manager-close-window` | `--owner-manager-email` | Opportunities/workloads for owners under one territory-owner manager. |
| `workloads-by-resource-close-window` | `--resource` | Workload revenue lines where the named resource appears in Presales Involvement Aux. |
| `workloads-by-owner-close-window` | `--owner-email` | Workload revenue lines for one territory owner. |
| `workloads-by-owner-manager-close-window` | `--owner-manager-email` | Workload revenue lines for owners under one territory-owner manager. |

All five support `--date`, `--month`, `--quarter`, `--week`, `--week-year`, `--from-date`, `--to-date`, `--cluster`, and `--limit`. Workload intents also support `--forecast-type`; opportunity intents support `--opty-status`. Use `--cluster` as the available geography filter; do not add or use a separate `--country` flag.

### SA Attach flags

Used by `sa-attach-*` views except `sa-attach-hours-by-opportunity` and `sa-attach-presales-coverage`.

| Flag | Type | Default |
|---|---|---|
| `--cluster <cluster>` | string | `Brazil` |
| `--solution valueA,valueB` | csv | `Cloud Infrastructure - Workloads,Hardware - Bookings,On-Premise Technology - Bookings` |
| `--revenue-line-status Open,Won,Won Pending` | csv | view default |
| `--executive-product-lob valueA,valueB` | csv | `Cloud Infrastructure,Hardware,License` |
| `--revenue-type-group NEW,EXPANSION,WORKLOAD` | csv | `NEW,EXPANSION,WORKLOAD` |
| `--sales-credit-type <type>` | string | `QUOTA` |
| `--min-opportunity-probability <number>` | number | `0` |
| `--owner-email <user@oracle.com>` | string | none |
| `--owner-manager-email <user@oracle.com>` | string | none |
| `--forecast-type Forecast,Upside,Won` | csv | all forecast types |

Notes:

- `--owner-email` matches the direct territory owner on `Level 7 Territory Owner E-mail`.
- `--owner-manager-email` matches upper owner hierarchy levels `2..6`.
- `--forecast-type` filters `Revenue Line Forecast Type Group`.
- When a date window is present, commercial SA Attach SQL now filters by `Revenue Line Close Date` directly instead of depending on a separate fiscal-year resolver.
- `opportunities-default`, `workloads-by-owner-current`, and `workloads-by-owner-manager-current` use these SA Attach filters; `--cluster` defaults to Brazil for those intents.
- DV - SE Team and session/effort/SR intents such as `srs-by-resource`, `sr-details`, `current-fiscal-year`, `data-quality-session-context`, `effort-by-se-team`, `effort-task-type-summary`, and `won-and-open-by-se-opty` do not support the commercial `Cluster` filter.

## Script: `refresh-auth-state.mjs`

Optional browser-based development helper. Opens Chrome, waits for a valid Oracle DV page, and writes fresh session files. Daily use should prefer `refresh-auth-direct.mjs`.

| Flag | Type | Default | Description |
|---|---|---:|---|
| `--runtime-home <dir>` | path | `<workspace>/knowledge-one-view-cli/runtime` | Override the workspace runtime root. |
| `--state-path <file>` | path | `<workspace>/knowledge-one-view-cli/runtime/auth-state.json` | Override auth-state output path. |
| `--meta-path <file>` | path | `<workspace>/knowledge-one-view-cli/runtime/session-meta.json` | Override session-meta output path. |
| `--profile-dir <dir>` | path | `<workspace>/knowledge-one-view-cli/runtime/chrome-profile` | Override Chrome profile directory. |
| `--chrome-path <file>` | path | auto-detected by platform | Override Chrome executable. |
| `--url <url>` | string | workbook URL | Override target Oracle DV workbook URL. |
| `--timeout-ms <ms>` | number | `600000` | Max wait for authenticated Oracle DV page. |
| `--help` | flag | `false` | Show usage. |

Environment fallbacks:

- `ORACLE_SI_RUNTIME_HOME`
- `ORACLE_SI_STATE_PATH`
- `ORACLE_SI_META_PATH`
- `ORACLE_SI_PROFILE_DIR`
- `ORACLE_SI_CHROME_PATH`
- `ORACLE_SI_TARGET_URL`

## Script: `refresh-auth-direct.mjs`

Direct Oracle sign-in flow without opening Chrome. Useful when browser auth is unavailable or you want explicit MFA control.

| Flag | Type | Default | Description |
|---|---|---:|---|
| `--runtime-home <dir>` | path | `<workspace>/knowledge-one-view-cli/runtime` | Override the workspace runtime root. |
| `--state-path <file>` | path | `<workspace>/knowledge-one-view-cli/runtime/auth-state.json` | Override auth-state output path. |
| `--meta-path <file>` | path | `<workspace>/knowledge-one-view-cli/runtime/session-meta.json` | Override session-meta output path. |
| `--username <email>` | string | prompted | Username for the direct sign-in flow. Also accepts `ORACLE_SI_USERNAME`. |
| `--factor <name>` | enum | none | Preferred MFA factor. Supported values: `PUSH`, `SMS`, `EMAIL`, `PHONE_CALL`, `TOTP`, `BYPASSCODE`, `PASSWORD`, `FIDO_PASSKEY`. |
| `--url <url>` | string | workbook URL | Override target Oracle DV workbook URL. |
| `--help` | flag | `false` | Show usage. |

Environment fallbacks:

- `ORACLE_SI_RUNTIME_HOME`
- `ORACLE_SI_STATE_PATH`
- `ORACLE_SI_META_PATH`
- `ORACLE_SI_USERNAME`
- `ORACLE_SI_TARGET_URL`

## Script: `run-sales-intelligence-sql.mjs`

Wrapper for `fetch-sales-intelligence.mjs` that preserves complex logical SQL on Windows shells by reading the SQL from a file or stdin, then forwarding the remaining arguments unchanged.

| Flag | Type | Default | Description |
|---|---|---:|---|
| `--sql-file <file>` | path | none | Read logical SQL from a file and pass it to `fetch-sales-intelligence.mjs --sql`. |
| `--stdin` | flag | `false` | Read logical SQL from stdin and pass it to `fetch-sales-intelligence.mjs --sql`. |
| `--help` | flag | `false` | Show usage. |

Pass-through behavior:

- Any other flags are passed straight through to `fetch-sales-intelligence.mjs`.
- Typical pass-through flags include `--limit`, `--render-sql`, `--output-file`, `--state-path`, `--meta-path`, `--base-url`, and `--no-cache`.

Examples:

```powershell
node .\scripts\run-sales-intelligence-sql.mjs `
  --sql-file .\query.sql `
  --limit 200
```

```powershell
Get-Content .\query.sql | node .\scripts\run-sales-intelligence-sql.mjs `
  --stdin `
  --render-sql
```