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
• Shortest path by ask type: Minimal-Step Decision Table
• Annual June-to-May week lookup: Week Shortcuts
• Main fetch command: Script: fetch-sales-intelligence.mjs
• Browser refresh helper: Script: refresh-auth-state.mjs
• Direct auth helper: Script: refresh-auth-direct.mjs
• Quote-safe SQL helper: Script: run-sales-intelligence-sql.mjs

For manager, hierarchy, architect-productivity, or business-parameter context, read 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 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

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
--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
`--quarter FY26-Q4	Q4 FY26	current-quarter`
`--week <1..53	w1..w53	week 1..week 53
--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
--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:

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:

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:

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:

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

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:

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

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