knowledge-one-view-cli/SKILL.md

name, description

name	description
knowledge-one-view-cli	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
• Need manager, hierarchy, architect-productivity, or team-rollup business context: references/initial-context-catalog.md
• Need the explicit annual week lookup such as w2, w43, or week 43: references/script-catalog.md#week-reference
• Need the exact CLI surface, flags, or script contract: references/script-catalog.md
• Need traced endpoints, workbook defaults, or view reconstruction details: references/api-map.md
• Need a migration checklist for a new computer: 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 first.
3. If the ask uses week, wk, or w1..w5, read 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 or run --catalog only when one contract detail is still unknown.
7. Read 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.
• 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-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 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 before touching the CLI catalog.
• 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 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.
• For asks like recursos do <manager de recurso> em pipe na week 2, prefer opportunities-by-manager-close-window --manager-email <manager de recurso> --week w2.
• For asks like workloads com close date nos proximos 7 dias em oportunidades com recursos abaixo de <manager de recurso 1> e <manager de recurso 2>, prefer workloads-by-manager-resource-close-window --manager-email-list <email do manager de recurso 1>,<email do manager de recurso 2> --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.
• 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.
• 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 for the full CLI contract and 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. 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:

node .\scripts\fetch-sales-intelligence.mjs `
  --check-auth

Generic pipeline or opportunities:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent opportunities-default `
  --limit 200

Exact close date:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent opportunities-close-date `
  --date 2026-05-02

Calendar month:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent opportunities-close-month `
  --month 2026-04

Annual week shortcut:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent opportunities-by-manager-close-window `
  --manager-email <email do manager de recurso> `
  --week w2 `
  --week-year 2026

Current workload by owner:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent workloads-by-owner-current `
  --owner-email <email do vendedor> `
  --forecast-type Forecast,Upside

Current workload by owner manager:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent workloads-by-owner-manager-current `
  --owner-manager-email <email do manager do vendedor> `
  --quarter current-quarter `
  --forecast-type Forecast

Org-wide workload close window by manager/resource:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent workloads-by-manager-resource-close-window `
  --manager-email-list <email do manager de recurso 1>,<email do manager de recurso 2> `
  --from-date today `
  --to-date +7d

SRs by person:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent srs-by-resource `
  --resource <recurso>

Alias-based ad hoc query:

node .\scripts\fetch-sales-intelligence.mjs `
  --query `
  --select opportunityId,opportunityName,closeDate,bookingValue,workloadAmount `
  --where "closeDate = DATE '2026-05-02'"