--- name: knowledge-one-view-cli description: Fetch Oracle Analytics LAD Knowledge One View sales data directly through Oracle DV APIs instead of scraping the browser UI. Use when Codex needs opportunity details, pipeline and close-date data, revenue-line analysis, SR details, fiscal-year or session context, or ad hoc Oracle DV queries for the Sales Intelligence Knowledge One View workbook at `salesintelligence-dv.oracle.com`. --- # Knowledge-One-View-CLI Use the direct API path first. Read only the smallest reference needed, run the shortest matching command, and open Chrome only when direct auth or workbook tracing requires it. ## Quick Navigation - Need the complete consolidated skill documentation: [docs/docs.html](docs/docs.html) - Need manager, hierarchy, architect-productivity, or team-rollup business context: [references/initial-context-catalog.md](references/initial-context-catalog.md) - Need the explicit annual `week` lookup such as `w2`, `w43`, or `week 43`: [references/script-catalog.md#week-reference](references/script-catalog.md#week-reference) - Need the exact CLI surface, flags, or script contract: [references/script-catalog.md](references/script-catalog.md) - Need traced endpoints, workbook defaults, or view reconstruction details: [references/api-map.md](references/api-map.md) - Need a migration checklist for a new computer: [portable-setup.md](portable-setup.md) ## Core Rules - Use `scripts/fetch-sales-intelligence.mjs` for normal backend reads. - Do not use REPL, browser scraping, or workbook rendering calls for routine retrieval. - Open Chrome only when direct auth is blocked or the workbook trace must be refreshed. - Prefer the fewest steps that still produce a correct answer. - Choose exactly one execution mode per fetch call: `--intent`, `--view`, `--query`, or `--sql`. - Prefer instructions already encoded in the local catalogs over re-deriving Oracle fields by hand. ## Trigger Cues Use this skill when the request is about any of these: - LAD Knowledge One View opportunity or SR data - close-date pipeline windows or month/day close-date asks - pipeline, opportunity, won, close-window, territory, or owner analysis from Knowledge DV - Opportunities - V2 - hours or hierarchy analysis from Knowledge DV - Hours - V2 - presales coverage or involvement from Knowledge DV - Presales Involvement Aux - V1 - Oracle DV fiscal-year/session variables used by the workbook - ad hoc Oracle logical SQL or alias-based query mode against the workbook data - manager hierarchy, architect productivity, or team rollups tied to these datasets ## Fast Path 1. Decide whether the ask is a manager or hierarchy ask. 2. If it is, read [references/initial-context-catalog.md](references/initial-context-catalog.md) first. 3. If the ask uses `week`, `wk`, or `w1`..`w5`, read [references/script-catalog.md#week-reference](references/script-catalog.md#week-reference) first. 4. If auth may be stale, run `--check-auth`. 5. Execute the shortest matching path immediately: - recurring business ask -> `--intent` - known extract -> `--view` - ad hoc aliases, filters, grouping, ordering -> `--query` - only if query mode cannot express it cleanly -> `--sql` 6. Read [references/script-catalog.md](references/script-catalog.md) or run `--catalog` only when one contract detail is still unknown. 7. Read [references/api-map.md](references/api-map.md) only when API behavior changed or a workbook view must be retraced. ## Preferred Execution Order ### 1. Intents Use intents first for recurring business asks. - `opportunities-default` Use as the canonical default for generic opportunity and pipeline retrieval on Knowledge DV - Opportunities - V2. - `opportunities-close-date` Use for one exact close date with `--date`. - `opportunities-close-month` Use for one calendar month with `--month`. - `opportunities-close-quarter` Use for one fiscal quarter with `--quarter`, including `current-quarter`. - `opportunities-current-team-close-window` Use for asks that really mean current-team coverage, such as allocated-resource manager, people attached through SR work, or similar team-involvement wording. This intent keeps the full org-wide opportunity/workload window and only enriches resource fields from the current team. - `opportunities-by-resource-close-window` Use when the ask names one explicit resource and you need opportunities in a close-date window tied to that person through coverage data, with commercial fields coming from Knowledge DV - Opportunities - V2. - `opportunities-by-manager-close-window` Use when the ask names one explicit manager email and you need opportunities in a close-date window tied to that hierarchy anchor, with commercial fields coming from Knowledge DV - Opportunities - V2. - `opportunities-by-owner-close-window` Use when the ask names one explicit territory owner or seller and you need opportunities in a close-date window. - `opportunities-by-owner-manager-close-window` Use when the ask names a manager of territory owners and you need opportunities in a close-date window. - `workloads-by-owner-current` Use for current-state workload asks for one explicit territory owner. It defaults to `current-quarter`, `Cloud Infrastructure - Workloads`, and `WORKLOAD`. - `workloads-by-owner-manager-current` Use for current-state workload asks for owners under one explicit manager-of-owner. It defaults to `current-quarter`, `Cloud Infrastructure - Workloads`, and `WORKLOAD`. - `workloads-by-owner-close-window` Use when the ask names one explicit territory owner or seller and asks for workloads in an explicit close-date window. - `workloads-by-owner-manager-close-window` Use when the ask names a manager of territory owners and asks for workloads in an explicit close-date window. - `workloads-by-resource-close-window` Use when the ask names one explicit allocated resource and asks for workload revenue lines in a close-date window. - `workloads-by-manager-resource-close-window` Use for org-wide workload revenue lines closing inside a direct date window when the ask is about opportunities that have allocated resources under one or more named managers. This intent gets manager/resource linkage only from `Knowledge DV - Presales Involvement Aux - V1`, gets commercial rows only from `Knowledge DV - Opportunities - V2`, filters on `Revenue Line Close Date`, and does not query `DV - SE Team` unless the user explicitly asks for SR details. - `srs-by-resource` Use for SRs by person with `--resource`. ### 2. Views Use a view when the extract shape is already known. - `opportunity-details` - `sr-details` - `opportunities-close-window` - `srs-by-resource-email` - `sa-attach-pipeline-details` - `sa-attach-open-pipeline` - `sa-attach-won-pipeline` - `sa-attach-involvement-distribution` - `sa-attach-hours-by-opportunity` - `sa-attach-presales-coverage` Read [references/script-catalog.md](references/script-catalog.md) for the full built-in script surface. ### 3. Query Mode Use `--query` for general ad hoc retrieval when the ask can be expressed as aliases plus filters, grouping, and ordering. - Prefer `--query` over `--sql` for most non-recurring asks. - Use field aliases instead of raw Oracle expressions whenever possible. - Let query mode infer the safest source from the selected aliases: commercial aliases go org-wide-first on XSA datasets, while SR/session aliases stay on `DV - SE Team`. - Use `--scope my-team` only when the user explicitly asks for the executing user's current-team view on org-wide-capable sources. ### 4. Raw SQL Use `--sql` only when `--query` cannot express the ask cleanly. - Prefer placeholders such as `{{opportunityId}}`, `{{closeDate}}`, `{{bookingValue}}`, `{{workloadAmount}}`, `{{subjectArea}}`, and `{{securityEntryPointFilter}}`. - Use `--render-sql` when you need to validate the final SQL locally without a backend call. - If quoting becomes fragile in PowerShell, use `scripts/run-sales-intelligence-sql.mjs`. ## Authentication Workflow 1. Run `--check-auth` only when the session may be stale. 2. For normal fetch calls, if the saved session files are missing or the backend redirects to Oracle sign-in, `fetch-sales-intelligence.mjs` now opens the browser refresh flow automatically, waits for login, writes fresh session files, and retries the backend request. 3. Use `scripts/refresh-auth-state.mjs` manually only when you want to pre-refresh the browser session yourself or troubleshoot the automatic flow. 4. Use `scripts/refresh-auth-direct.mjs` when browser auth is unavailable or when you explicitly want the terminal-driven MFA flow. 5. `--check-auth` stays diagnostic-only and does not open the browser automatically. ## Data-Specific Rules - For manager or hierarchy asks, start with [references/initial-context-catalog.md](references/initial-context-catalog.md) before touching the CLI catalog. - For any effort/hour allocation ask, default to 100% of recorded hours. Include customer-related work, non-customer/internal work, and Time Off unless the user explicitly asks to exclude one of those categories. - For `DV - SE Team` effort/hour reads, use `"Effort"."# Hours"` as the default total-hours measure. Use `"Effort"."# Hours (Excl. Time Off)"` only when the user explicitly asks to exclude Time Off or when a specific built-in view forces that metric; if forced, disclose the limitation. - For `Knowledge DV - Hours - V2` or other XSA hour reads, prefer the available total-hours measure that includes Time Off. If only an excluding-Time-Off alias such as `hoursExcludingTimeOff` is available, probe or use `--sql` to validate a total-hours field before falling back. - Do not filter hours to only customer, only non-customer, only opportunity-linked, only internal, or only Time Off unless the user explicitly requests that subset. - For generic opportunity and pipeline asks, prefer `opportunities-default`. - For close-date asks, prefer `opportunities-close-date`, `opportunities-close-month`, or `opportunities-close-window`. - For fiscal-quarter asks, prefer `--quarter` with `FY26-Q4`, `Q4 FY26`, or `current-quarter`. - For asks phrased as `week 1`..`week 53` or `w1`..`w53`, use the annual June-to-May week mapping in [references/script-catalog.md#week-reference](references/script-catalog.md#week-reference) and prefer `--week` plus optional `--week-year`. - Treat wording like `agora`, `atual`, `mês corrente`, `quarter atual`, and `FY corrente` as current-period shortcuts whenever the matching flag supports it. - For `opportunities-close-window`, close-window intents, and `sa-attach-*` commercial views, date-window flags now constrain `Revenue Line Close Date` directly, including `--week`, `--quarter`, and explicit `--from-date/--to-date`. - For present-state workload asks about one seller or one seller-manager, prefer `workloads-by-owner-current` or `workloads-by-owner-manager-current`. - For current-team coverage asks, prefer `opportunities-current-team-close-window`. - Treat `país` or `country` wording as `--cluster` only when the user names a supported commercial cluster. Do not invent a separate `--country` flag. - For seller or territory-owner opportunity asks with explicit dates, prefer `opportunities-by-owner-close-window`. - For seller-manager opportunity asks with explicit dates, prefer `opportunities-by-owner-manager-close-window`. - For resource workload asks with explicit dates, prefer `workloads-by-resource-close-window`. - For territory-owner workload asks with explicit dates, prefer `workloads-by-owner-close-window`; keep `workloads-by-owner-current` for current-state or current-quarter asks. - For territory-owner-manager workload asks with explicit dates, prefer `workloads-by-owner-manager-close-window`; keep `workloads-by-owner-manager-current` for current-state or current-quarter asks. - For asks like `recursos do em pipe na week 2`, prefer `opportunities-by-manager-close-window --manager-email --week w2`. - For asks like `workloads com close date nos proximos 7 dias em oportunidades com recursos abaixo de e `, prefer `workloads-by-manager-resource-close-window --manager-email-list , --from-date today --to-date +7d`. - For that workload-by-manager-resource intent, treat `resourceEmails` as the org-wide allocated resource list from Presales Involvement Aux. The default result is involvement/allocation only; do not fetch SR details unless the user explicitly asks for SRs. - When crossing SRs to workloads or opportunities, keep the `opportunityId` join as the confirmed linkage and also consider same-resource same-customer SRs without a usable `opportunityId` as internal-SR candidates. This is the current safe fallback because `Parent SR Number` is still not queryable through the logical SQL path. - For SR resource lookups, default to SR Team Level `1..4` email matching and use `Lead Email` only for explicit leader intent. - Accept short Oracle user ids through `--resource` when available. - Use `--owner-email` for direct territory-owner filters and `--owner-manager-email` for owner-hierarchy filters on SA Attach workload reads. - Use `--forecast-type` for natural-language asks such as `forecast`, `upside`, or `won` on SA Attach workload reads. - Keep opportunity-linked monetary outputs consistent as `bookingValue` and `workloadAmount`. - For `DV - SE Team` effort/hour reads about activities not related to customers, apply this classification only when the user explicitly asks for non-client, client/non-client splits, internal work, or customer-related filtering. Treat `Unspecified` in all three linkage fields (`Service Request"."SR Number"`, `"Customer"."Customer Name"`, and `"Opportunity"."Opportunity ID"`) as the signal for no customer relationship. Any populated SR, customer, or opportunity means the effort is customer-related. - For the current validated FY26 my-team pattern, the task types that matched the no-customer signal were `Administration`, `Content Creation`, `Partner Activities`, `Sales Planning`, `Training Delivery`, and `Training/Personal Development - Taken`. `Config`, `Preparation`, and `Travel` were customer-related; `Delivery` and `Follow-up` were mostly customer-related, with small cases that had SR/customer but `Opportunity ID = 'Unspecified'`, so do not classify them as non-customer solely by task type. - When answering "non-client", "sem cliente", "sem oportunidade", or "atividades internas" effort asks, prefer validating/reporting by the `Unspecified` linkage signal first and only use task type names as a helpful summary of the observed pattern. - Treat `Knowledge DV - Opportunities - V2` as the normal source for pipeline, opportunity, won, close date, territory, owner, booking, and workload. - Interpret user wording `vendedor`, `sales rep`, and `lider de vendas` as `territory owner` by default. - Treat org-wide-capable XSA datasets as org-wide reads in `--scope auto`: `Knowledge DV - Opportunities - V2`, `Knowledge DV - Hours - V2`, `Knowledge DV - Presales Involvement Aux - V1`, and `Knowledge DV - Revn Lines by SE`. - Treat `Knowledge DV - Hours - V2` as the normal source for hierarchy ownership and hours; default to org-wide unless the ask explicitly requests current-team scope. - Treat `Knowledge DV - Presales Involvement Aux - V1` as the normal source for allocated resource, manager, and presales-coverage linkage; default to org-wide unless the ask explicitly requests current-team scope. - Treat `Knowledge DV - Revn Lines by SE` as the normal source for detailed revenue-line extracts; default to org-wide unless the ask explicitly requests current-team scope. - Treat `DV - SE Team` as self-scoped to the executing user, with hierarchy starting from that user and expanding only downward through their team. - Treat `DV - SE Team` as fallback for commercial views only when the ask is explicitly about the current user's team, and as the normal source for session context and SR reads. - When mixing org-wide commercial rows with current-team resource enrichment, preserve every org-wide opportunity/workload row and leave resource fields empty when there is no match. - When a result mixes org-wide commercial rows with team-scoped resources, say that explicitly in the answer: `Opportunities/workloads: org-wide`, `Resources: only your current team`, and `rows without a match keep empty resource fields`. - When a result includes any `scope.components`, prefer those component lines over a single simplified label because they identify which source is org-wide and which source is my-team-only. ## Inputs And Outputs Input expectations: - business ask phrased in natural language, or - a known intent/view/query/SQL request, optionally with date, month, resource, manager, or status filters Normal output contract from `fetch-sales-intelligence.mjs`: - `request` - `scope` - `apiMetrics` - `columns` - `records` - `summary` for derived intents when relevant - `warnings` - `raw` for backend debugging User-facing answer contract: - Every answer that reports DV data must include a short "Context / assumptions" note near the result. Do not leave scope, defaults, or implicit DV assumptions only in the JSON. - Always state the effective scope as one of `org-wide`, `my-team-only`, or `mixed-consistent`. If `scope.components` exists, use it as the authoritative source-by-source disclosure instead of compressing the result into one label. - Always state the main source and execution path used: `--intent`, `--view`, `--query`, or `--sql`; the source subject area when known; and whether `--scope auto`, `--scope org-wide`, or `--scope my-team` was used. - When defaults are applied, explicitly say so. At minimum disclose these common defaults when relevant: `cluster = Brazil`; `--scope auto`; live Oracle DV session fiscal year; current-period shortcuts such as `current-quarter`, current FY, or the current June-to-May week cycle; default status filters; default `--limit`; and SA Attach defaults for solution, product LOB, revenue type group, sales credit type, and minimum opportunity probability. - If the user did not specify geography and the selected SA Attach/commercial path applies the traced workbook filter `cluster = Brazil`, say `Cluster default: Brazil`. If geography was overridden or no cluster filter applies, say that instead. - If date windows, weeks, quarters, or "current" wording were interpreted, state the resolved period and the date field being filtered. For commercial SA Attach close-window answers, say that the window filters `Revenue Line Close Date`. - If user wording required role interpretation, state it briefly, for example `vendedor`/`sales rep`/`lider de vendas` interpreted as `territory owner`, or short Oracle uid normalized to `@oracle.com`. - If SR, resource, manager, or workload enrichment involved implicit joins, state the join assumption: `opportunityId` is the confirmed linkage; same-resource same-customer SRs without usable `opportunityId` are only fallback candidates; and current-team enrichment can leave unmatched org-wide rows with empty resource fields. - For hour/effort answers, state whether the reported metric includes Time Off and whether customer and non-customer/internal hours were included. The default is 100% of recorded hours unless an explicit user filter says otherwise. - Always include API effort and data-shape caveats: `Raw rows pulled from the API: X`; whether the result hit the requested/default limit; any `warnings`; and whether displayed monetary fields use truncated `k` values while `raw` keeps backend-native values. - Never describe the numbers as "all company", "all Brazil", or "complete pipeline" unless the disclosed `scope`, filters, defaults, and limits actually support that statement. Scope disclosure rule: - Use the emitted `scope` object when wording the answer. - `scope.scopeMode = org-wide` means the visible rows are org-wide. - `scope.scopeMode = my-team-only` means the visible rows are limited to the executing user's current team. - `scope.scopeMode = mixed-consistent` means the opportunity/workload rows remain org-wide, resource enrichment is team-scoped, and unmatched rows stay in the output with empty resource fields. - `scope.components` is the most precise source-by-source disclosure. Use it when present, especially for mixed answers. - For `workloads-by-manager-resource-close-window`, `scope.scopeMode = org-wide` means both workload rows and manager/resource allocation came from org-wide Knowledge DV sources. If the user explicitly asks for SR details, disclose the separate SR lookup as `DV - SE Team` / my-team-only. - Explain in the output to the user which context was used to retrieve the information. API effort disclosure rule: - Use `apiMetrics.totalRowsPulledFromApi` as the canonical count of raw rows returned by Oracle DV for that invocation. - Do not replace that number with final `records.length`; they mean different things. - Do not add local-cache-only rows to this number. If the skill reused local fiscal-year/session metadata, those local reads do not count toward `apiMetrics.totalRowsPulledFromApi`. - Prefer wording the answer with a sentence like `Raw rows pulled from the API: X.` Display-format rule: - `bookingValue` and `workloadAmount`, plus `summary.totalBookingValue` and `summary.totalWorkloadAmount`, are emitted as truncated thousands with a `k` suffix, for example `849k`. The `raw` section keeps the backend-native values. Read [references/script-catalog.md](references/script-catalog.md) for the full CLI contract and [references/api-map.md](references/api-map.md) for traced backend details. ## Minimal Commands Codex normally invokes this skill from the current agent workspace, so the default runtime is `./knowledge-one-view-cli/runtime/`. If you run the scripts manually from the installed skill directory or any other location, pass `--runtime-home` or set `ORACLE_SI_RUNTIME_HOME` to point back to the target workspace. For the consolidated technical guide, testing strategy, and workspace artifact layout, read [docs/docs.html](docs/docs.html). Test definitions stay inside the installed skill `tests/` folder, while test-run artifacts go to the workspace-side `knowledge-one-view-cli/output/` and `knowledge-one-view-cli/tmp/` folders. Check auth: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --check-auth ``` Generic pipeline or opportunities: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --intent opportunities-default ` --limit 200 ``` Exact close date: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --intent opportunities-close-date ` --date 2026-05-02 ``` Calendar month: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --intent opportunities-close-month ` --month 2026-04 ``` Annual week shortcut: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --intent opportunities-by-manager-close-window ` --manager-email ` --week w2 ` --week-year 2026 ``` Current workload by owner: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --intent workloads-by-owner-current ` --owner-email ` --forecast-type Forecast,Upside ``` Current workload by owner manager: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --intent workloads-by-owner-manager-current ` --owner-manager-email ` --quarter current-quarter ` --forecast-type Forecast ``` Org-wide workload close window by manager/resource: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --intent workloads-by-manager-resource-close-window ` --manager-email-list , ` --from-date today ` --to-date +7d ``` SRs by person: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --intent srs-by-resource ` --resource ``` Alias-based ad hoc query: ```powershell node .\scripts\fetch-sales-intelligence.mjs ` --query ` --select opportunityId,opportunityName,closeDate,bookingValue,workloadAmount ` --where "closeDate = DATE '2026-05-02'" ```