Primeiro Commit v0.beta1

2026-04-29 00:27:50 -03:00
parent 93d4906fb5
commit 8662a153fe
27 changed files with 16303 additions and 0 deletions
--- a/references/api-map.md
+++ b/references/api-map.md
@@ -0,0 +1,514 @@
+# Knowledge-One-View-CLI API Map
+
+Read this file when Oracle DV behavior changes, a workbook tab must be retraced, or you need traced endpoint and default-filter details that are too low-level for the main skill guide.
+
+## Quick Navigation
+
+- Workbook identity: [Traced Workbook](#traced-workbook)
+- Required auth/session state: [Required Session Inputs](#required-session-inputs)
+- Direct and fallback endpoints: [Traced Endpoints](#traced-endpoints)
+- Local metadata and field shortcuts: [Fast Local Metadata](#fast-local-metadata)
+- Common query patterns: [Fast Query Patterns](#fast-query-patterns)
+- Traced workbook-tab defaults: [Traced Tab Defaults](#traced-tab-defaults)
+
+## Traced Workbook
+
+- Workbook URL:
+  `https://salesintelligence-dv.oracle.com/ui/dv/ui/project.jsp?pageid=visualAnalyzer&reportmode=presentation&reportpath=%2F%40Catalog%2Fshared%2FTeam%20Sharing%20Area%2FLAD%2FLAD%20Sales%20Operations%2FLAD%20Production%2FLAD%20Knowledge%20One%20View`
+- Platform:
+  Oracle Analytics / Oracle DV
+- Primary commercial subject area:
+  `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')`
+
+Keep the `ANNA.DE.MAURO@ORACLE.COM` token exactly as traced in XSA dataset references. It is part of the logical dataset identifier, not a disposable example.
+
+## Required Session Inputs
+
+The direct API calls worked with:
+
+- Cookies from Playwright `storageState`
+- `authorization: session`
+- `x-csrf-token`
+- `x-bitech-clientbin`
+- `x-requested-with: XMLHttpRequest`
+- Workbook `referer`
+
+`x-bitech-clientbin` also appears in the workbook bootstrap HTML inside static asset paths such as:
+
+`/static/dv/oracle-jet-bundles/18.1.2.fd48e9d8895d/...`
+
+The refresh helper writes both the cookies and these request headers to disk:
+
+- `auth-state.json`
+- `session-meta.json`
+
+The fetch script also persists refreshed cookies plus updated CSRF/clientbin metadata back to those files after a session restore so later runs reuse the corrected backend state.
+When the saved files are missing or Oracle redirects a normal fetch call back to sign-in, the fetch script can now invoke the browser refresh helper automatically, then reload the session artifacts and retry the backend request.
+That makes the runtime/session path parameters operationally important, not just convenience flags.
+
+## Traced Endpoints
+
+### Preferred Direct Endpoint
+
+- `POST /ui/dv/ui/api/v1/sqlquery/execute`
+  Use for custom Oracle logical SQL and for the reusable `opportunity-details` and `sr-details` views in this skill.
+  Body shape:
+
+```json
+{
+  "aQueryInfos": [
+    {
+      "sQuery": "SELECT valueof(RV_CURR_FISCAL_YEAR) FROM \"DV - SE Team\"",
+      "nResultsLimit": 1
+    }
+  ],
+  "bUseCache": true
+}
+```
+
+  Response shape:
+
+```json
+{
+  "aQueriesResults": [
+    {
+      "eStatus": "FINISHED",
+      "aColumnTypes": ["varchar"],
+      "aResults": [["FY26"]]
+    }
+  ]
+}
+```
+
+### Metadata / Bootstrap Endpoints
+
+- `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`
+  Traced from `Data Quality`. Useful when Oracle changes dataset metadata or a new workbook view must be reconstructed.
+- `POST /ui/dv/ui/api/v1/infer/activities`
+  Telemetry only. Ignore for data retrieval.
+- `GET /ui/dv/ui/api/v3/items-content`
+  Static workbook assets such as images. Ignore for data retrieval.
+
+### Workbook Rendering Endpoints
+
+- `POST /ui/dv/ui/api/v2/data/executeOrPoll`
+- `POST /ui/dv/ui/api/v2/data/poll`
+
+These drive the rendered workbook tabs. They are useful as fallback references because the POST payloads contain the exact traced columns and default filters, but they are noisier than `sqlquery/execute`.
+
+## Fast Local Metadata
+
+The skill now keeps a local field catalog inside `scripts/fetch-sales-intelligence.mjs` for the most common logical fields, so repeated asks do not need rediscovery. Use:
+
+- `--catalog`
+- `--list-intents`
+- `--describe-intent srs-by-resource`
+- `--list-fields`
+- `--list-fields --entity Opportunity`
+- `--list-fields --role filter`
+- `--describe-field closeDate`
+
+Use the intent shortcuts first for the recurring asks that previously caused parameter guesswork:
+
+- `opportunities-close-date`
+  Uses `--date`
+- `opportunities-close-month`
+  Uses `--month`
+- `srs-by-resource`
+  Uses `--resource`
+
+For ad hoc SQL, prefer template placeholders over raw Oracle expressions:
+
+- `{{opportunityId}}`
+- `{{closeDate}}`
+- `{{bookingValue}}`
+- `{{workloadAmount}}`
+- `{{subjectArea}}`
+- `{{securityEntryPointFilter}}`
+
+Render those placeholders locally without a backend call:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --render-sql `
+  --sql "SELECT {{opportunityId}}, {{closeDate}} FROM {{subjectArea}} WHERE {{securityEntryPointFilter}}"
+```
+
+For most ad hoc retrieval, prefer declarative query mode over raw SQL:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --query `
+  --select opportunityId,opportunityName,closeDate,bookingValue,workloadAmount `
+  --where "closeDate = DATE '2026-05-02'"
+```
+
+Query mode infers the safest source from the selected aliases. Commercial opportunity, revenue-line, hours, and presales-coverage aliases use org-wide-capable XSA sources in `--scope auto`; SR and session aliases remain on `DV - SE Team`, which is my-team-only.
+
+Important known fields:
+
+- `closeDate`
+  `"Opportunity"."Close Date"`
+  Use direct date literals: `DATE '2026-03-27'`
+- `opportunityId`
+  `"Opportunity"."Opportunity ID"`
+- `opportunityName`
+  `"Opportunity"."Opportunity Name"`
+- `opportunityStatus`
+  `"Opportunity"."Status"`
+- `customerName`
+  `"Customer"."Customer Name"`
+- `salesStage`
+  `"Opportunity"."Sales Stage"`
+- `opportunityValue`
+  `"Opportunity"."Opportunity Value"`
+- `bookingValue`
+  `"Opportunity"."Opportunity Value"`
+  Preferred alias when the intent is to compare booking against `workloadAmount`.
+- `workloadAmount`
+  `"Opportunity"."Workload Amount"`
+- `optyCloseFiscalYear`
+  `"Time (Close Date Opportunity)"."Opty Close Fiscal Year"`
+- `srNumber`
+  `"Service Request"."SR Number"`
+- `srStatus`
+  `"Service Request"."Status"`
+- `srTeamLevel1EmailAddress`
+  `"SR Team"."SE Team Level 1 Email Address"`
+- `srTeamLevel2EmailAddress`
+  `"SR Team"."SE Team Level 2 Email Address"`
+- `srTeamLevel3EmailAddress`
+  `"SR Team"."SE Team Level 3 Email Address"`
+- `srTeamLevel4EmailAddress`
+  `"SR Team"."SE Team Level 4 Email Address"`
+- `leadEmail`
+  `"Service Request"."Lead Email"`
+  Use only when the intent is explicitly to query the SR leader.
+
+## Fast Query Patterns
+
+### Ad Hoc SQL Without Oracle Expression Guesswork
+
+Use the local placeholder expansion:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --sql "SELECT {{opportunityId}}, {{opportunityName}}, {{closeDate}}, {{bookingValue}}, {{workloadAmount}} FROM {{subjectArea}} WHERE {{securityEntryPointFilter}} AND {{closeDate}} = DATE '2026-05-02'"
+```
+
+The script expands that locally to Oracle logical SQL before execution.
+When the `SELECT` list is simple enough, the script also infers output column names and returns object-shaped `records` instead of only raw row arrays. Explicit `AS` aliases are respected.
+
+### Declarative Query Mode
+
+Use query mode when the ask is naturally "fields + filter + grouping + ordering":
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --query `
+  --select opportunityId `
+  --measure sum:bookingValue:totalBooking,sum:workloadAmount:totalWorkload `
+  --where "closeDate = DATE '2026-05-02'" `
+  --group-by opportunityId `
+  --order-by totalBooking:desc
+```
+
+Query mode reduces guesswork by:
+
+- inferring the configured source automatically from the selected aliases
+- using org-wide XSA sources first for commercial aliases in `--scope auto`
+- injecting the standard team-security filter only when the selected source requires it or when `--scope my-team` is explicitly requested on an org-wide-capable source
+- accepting field aliases directly inside `--select` and `--where`
+- supporting aggregate specs like `sum:bookingValue:totalBooking`
+- returning object-shaped records with stable output columns
+
+### Backend Scope Reality
+
+Use this when deciding whether a request can be answered org-wide or must be disclosed as current-team only:
+
+- `Knowledge DV - Opportunities - V2`, `Knowledge DV - Hours - V2`, `Knowledge DV - Presales Involvement Aux - V1`, and `Knowledge DV - Revn Lines by SE` are treated as org-wide-capable XSA datasets by the skill. In `--scope auto`, the script avoids the current-team security predicate unless the chosen view or intent explicitly needs it.
+- `--scope my-team` on an org-wide-capable source intentionally adds the current-team predicate so the same dataset can be used for a narrower current-team read.
+- `DV - SE Team` is effectively my-team-only for this skill. Use it for SRs, session context, and fields that have no org-wide source. Do not use it as a generic org-wide commercial fallback.
+- For mixed outputs, prefer `scope.components` and `scope.disclosureLines` over a single label because one component may be org-wide while another remains my-team-only.
+
+### Opportunities By Close-Date Window
+
+Use the built-in intent or built-in view instead of rewriting SQL:
+
+Exact 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
+```
+
+Explicit window:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --view opportunities-close-window `
+  --from-date today `
+  --to-date +7d
+```
+
+Primary logical SQL pattern:
+
+```sql
+SELECT
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity ID",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Name",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Customer Name (Original)",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Status",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Sales Stage",
+  MAX(XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Pipeline") AS bookingValue,
+  MAX(XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Pipeline") AS workloadAmount
+FROM XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')
+WHERE XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date" >= DATE '2026-03-27'
+  AND XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date" <= DATE '2026-04-03'
+GROUP BY
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity ID",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Name",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Customer Name (Original)",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Status",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Sales Stage"
+ORDER BY 5, 1
+```
+
+Fallback behavior:
+
+- if the ask is explicitly about the current user's team and the primary XSA query fails, the skill may rerun the commercial read against `DV - SE Team`
+- generic org-wide commercial reads stay on `Knowledge DV - Opportunities - V2` and do not fall back to `DV - SE Team`
+
+In the built-in `opportunities-close-window` view, the last two fields are returned from the org-wide XSA `Pipeline` column:
+
+- `bookingValue` -> `Knowledge DV - Opportunities - V2` / `"Columns"."Pipeline"`
+- `workloadAmount` -> `Knowledge DV - Opportunities - V2` / `"Columns"."Pipeline"`
+
+The `bookingValue` and `workloadAmount` names are preserved for user-facing compatibility with opportunity and workload reports. For org-wide query-mode reads from `Knowledge DV - Opportunities - V2`, prefer the same `Pipeline` backing field because direct row-level reads of `"Opportunity Value"` and `"Workload Amount"` can fail in Oracle DV.
+
+### SRs By Resource Email
+
+Use the built-in intent or built-in view instead of writing custom SQL:
+
+Shortest path:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --intent srs-by-resource `
+  --resource resource.member
+```
+
+Equivalent direct view call:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --view srs-by-resource-email `
+  --resource resource.member
+```
+
+Default matching rule:
+
+```sql
+(
+  "SR Team"."SE Team Level 1 Email Address" = 'resource.member@oracle.com'
+  OR "SR Team"."SE Team Level 2 Email Address" = 'resource.member@oracle.com'
+  OR "SR Team"."SE Team Level 3 Email Address" = 'resource.member@oracle.com'
+  OR "SR Team"."SE Team Level 4 Email Address" = 'resource.member@oracle.com'
+)
+```
+
+Only use lead matching when the ask is explicitly about the leader:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --view srs-by-resource-email `
+  --resource-email resource.member@oracle.com `
+  --match-role lead
+```
+
+The built-in `srs-by-resource-email` view also returns:
+
+- `bookingValue` -> `"Opportunity"."Opportunity Value"`
+- `workloadAmount` -> `"Opportunity"."Workload Amount"`
+
+The CLI now normalizes Oracle date strings in built-in output, so values such as `02-MAY-26` are returned as `2026-05-02`.
+
+## Traced Tab Defaults
+
+### Opportunity Details
+
+- Current canvas:
+  `canvas!4`
+- Plugin:
+  `oracle.bi.tech.table`
+- Default filters:
+  - `Security.Entry Point in VALUEOF(NQ_SESSION."SEC_ARIA_SI-SR-TEAM")`
+  - `Opty Close Fiscal Year = current FY`
+  - `Opportunity Status in (Open, Won, Won Pending)`
+  - `SE Team Active Flag = Y`
+  - `SE Team Manager Flag = N`
+  - `SR Source = Opportunity`
+- Important columns:
+  - `Opportunity ID`
+  - `# Opportunity Hours`
+  - `Status`
+  - `Workload Amount`
+  - `Registry ID`
+  - `Customer Name`
+  - `Deal Qualification`
+  - `Forecast Type Group`
+  - `Opportunity Value`
+  - `Current FY Opp Hours`
+  - `Total Opportunity Hours`
+  - `Opty Close Fiscal Quarter`
+  - `# SEs With Effort`
+  - `# Service Requests with Effort`
+  - `Country`
+  - `Sales Stage`
+  - `Revenue Type Group`
+  - `LOB Type`
+  - `All Products`
+  - `Opportunity Name`
+  - `All Workloads`
+  - `Covered Flag`
+  - `All Implementers`
+  - `Win Probability`
+
+### SR Details
+
+- Current canvas:
+  `canvas!5`
+- Plugin:
+  `oracle.bi.tech.table`
+- Default filters:
+  - `Security.Entry Point in VALUEOF(NQ_SESSION."SEC_ARIA_SI-SR-TEAM")`
+  - `Opty Close Fiscal Year = current FY`
+  - `Opportunity Status = Open`
+  - `SE Team Active Flag = Y`
+  - `SE Team Manager Flag = N`
+- Important columns:
+  - `SR Number`
+  - `Parent SR Number`
+  - `Service Request Status`
+  - `Title`
+  - `Queue Name`
+  - `Country`
+  - `Registry ID`
+  - `Customer Name`
+  - `SR Source`
+  - `Opportunity ID`
+  - `Opportunity Name`
+  - `Opportunity Status`
+  - `Win Probability`
+  - `Primary Pillar`
+  - `Opportunity Value`
+  - `Workload Amount`
+  - `Total SR Hours`
+  - `Lead Email`
+  - `SR Requester Email Address`
+  - `Create SR Day`
+  - `Close SR Day`
+  - `Customer Deadline`
+  - `Internal Deadline`
+  - `Last Effort`
+  - `# Service Requests with Effort`
+  - `# SEs With Effort`
+  - `# Hours (Excl. Time Off)`
+  - `Service Description`
+
+Current limitation:
+
+- `Parent SR Number` is visible in traced workbook metadata, but the direct logical SQL path used by the CLI still fails when selecting it explicitly.
+- Because of that, current internal-SR reconciliation in the skill uses a safe fallback: confirmed joins stay based on `Opportunity ID`, and additional internal-SR candidates are inferred only when the same resource has SRs for the same customer without a usable `Opportunity ID`.
+
+### Data Quality
+
+The `Data Quality` tab used:
+
+- `POST /ui/dv/ui/api/v1/sqlquery/execute`
+- `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`
+
+That trace confirms the workbook can be queried directly through Oracle logical SQL without rendering the visualization.
+
+### Commercial Opportunity Datasets
+
+- Current canvas:
+  `canvas!15`
+- Traced endpoints:
+  - `POST /ui/dv/ui/api/v2/data/executeOrPoll`
+  - `POST /ui/dv/ui/api/v2/modelmetadata/subjectareas`
+  - `POST /ui/dv/ui/api/v2/metadata/interactionpaths`
+  - `POST /ui/dv/ui/api/v1/dataset/datasets/metadata`
+  - `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`
+- Traced workbook sources:
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')`
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Hours - V2')`
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Presales Involvement Aux - V1')`
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Revn Lines by SE')`
+- Observed metadata lookup:
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'One View Tech - Usage Information')`
+
+The first traced SA Attach visuals used `Knowledge DV - Opportunities - V2` as the active subject area and exposed these traced defaults:
+
+- Recommended default for generic opportunity retrieval:
+  `--intent opportunities-default`
+- `Cluster = Brazil`
+- `Solution in ('Cloud Infrastructure - Workloads', 'Hardware - Bookings', 'On-Premise Technology - Bookings')`
+- `Sales Credit Type = QUOTA`
+- `Executive Product LOB in ('Cloud Infrastructure', 'Hardware', 'License')`
+- `Revenue Type Group in ('NEW', 'EXPANSION', 'WORKLOAD')`
+- Current skill default: `Opportunity Probability >= 0`
+- Older workbook traces sometimes showed `Opportunity Probability >= 40`
+- `Revenue Line Status = Open` for the open-pipeline visuals
+- `Revenue Line Status in ('Won', 'Won Pending')` for the won-pipeline visual
+- Open rows are allowed in any close year, while won rows are constrained to previous/current fiscal year
+- Compatibility note:
+  older traces may still mention `License and Hardware` or `WORKLOADS`; the skill now normalizes those aliases to the backend values `License` + `Hardware` and `WORKLOAD`.
+
+Traced view mappings:
+
+- `view!1597`
+  `oracle.bi.tech.ngperformancetile`
+  Open pipeline tile based on `SUM(Pipeline)` from `Knowledge DV - Opportunities - V2`
+- `view!1612`
+  `oracle.bi.tech.ngperformancetile`
+  Won pipeline tile based on `SUM(Pipeline)` from `Knowledge DV - Opportunities - V2`
+- `view!1602`
+  `oracle.bi.tech.chart.stackbar100`
+  Involvement distribution chart based on `Pipeline`, `Revenue Line Probability`, `Presales Involvement Flag`, and `Opportunity Hours Attribute`
+
+The traced involvement bucket logic is:
+
+```sql
+CASE
+  WHEN SUM(
+    CASE WHEN <current-team filter on Presales Involvement Aux - V1>
+      THEN "Opportunity Hours Attribute"
+    END BY "Opportunity ID"
+  ) > 0
+    THEN '1. My Team Involvement'
+  WHEN "Presales Involvement Flag" = 'Y'
+    THEN '2. Other Presales Involvement'
+  ELSE '3. No Presales Involvement'
+END
+```
+
+Current skill coverage now maps that tab through these direct views:
+
+- `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`
--- a/references/initial-context-catalog.md
+++ b/references/initial-context-catalog.md
@@ -0,0 +1,83 @@
+# Initial Context Catalog
+
+Read this file at skill load time when the ask is about managers, hierarchy, architect productivity, team rollups, or when you need quick business context before touching the CLI catalog. This is a curated seed catalog for fast execution, not a replacement for `fetch-sales-intelligence.mjs --catalog`.
+
+Use this file for org and business-context interpretation. Skip it for routine close-date, SR-by-person, or generic opportunity asks that already map directly to an intent or built-in view.
+
+## Quick Navigation
+
+- Why this file exists: [Why This Exists](#why-this-exists)
+- Hierarchy heuristics: [Hierarchy Shortcuts](#hierarchy-shortcuts)
+- Verified manager anchors: [Verified Org Anchors](#verified-org-anchors)
+- Reusable business translations: [Query Translation Shortcuts](#query-translation-shortcuts)
+- SA Attach filters and anchors: [SA Attach Quick Map](#sa-attach-quick-map)
+- Final guardrails: [Practical Rules](#practical-rules)
+
+## Why This Exists
+
+- The script catalog is best for CLI and field-contract discovery.
+- This file is best for front-loading org or hierarchy context, query translation heuristics, and recurring business shortcuts.
+- Use this first when the user already gave a manager name, an email, or wording such as `top architects`, `time do manager`, `produtividade`, `booking/workload por arquiteto`, or `deals WON`.
+
+## Hierarchy Shortcuts
+
+- For SA Attach productivity-style asks, the working source of truth is usually `Knowledge DV - Hours - V2`.
+- In that dataset, the most useful working assumption is:
+  - `SE Team Level 3 Email Address` -> manager scope anchor for many manager-rollup asks.
+  - `SE Team Level 4 Email Address` -> direct manager under the level-3 manager.
+  - `SE Team Level 5 Email Address` -> architect or IC email for per-person productivity rollups.
+  - `SE Team Level 6..8 Email Address` -> often repeats the same IC email. Do not sum across those levels as separate people.
+- Do not assume `Security.Entry Point = <manager email>` reproduces the org hierarchy you need. In practice, the entry point can differ from the visible manager email and may return no rows for a valid manager.
+- For manager-scoped productivity asks, the fastest stable pattern is:
+  1. Filter `Knowledge DV - Hours - V2` by the manager email at the matching hierarchy level.
+  2. Aggregate hours by `SE Team Level 5 Email Address`.
+  3. Join or intersect with `Knowledge DV - Opportunities - V2` on `Opportunity ID` to apply `Close Date`, `Status`, `Opportunity Value`, `Workload Amount`, territory, and owner context.
+
+## SA Attach Quick Map
+
+- Hierarchy fields: `SE Team Level 3 Email Address` = manager anchor; `SE Team Level 4 Email Address` = direct manager; `SE Team Level 5 Email Address` = architect/IC.
+- SA Attach params: `--cluster`, `--solution`, `--revenue-line-status`, `--executive-product-lob`, `--revenue-type-group`, `--sales-credit-type`, `--min-opportunity-probability`.
+- SA Attach defaults: `--cluster=Brazil`; `--solution=Cloud Infrastructure - Workloads,Hardware - Bookings,On-Premise Technology - Bookings`; `--revenue-line-status=Open,Won,Won Pending`; `--executive-product-lob=Cloud Infrastructure,Hardware,License`; `--revenue-type-group=NEW,EXPANSION,WORKLOAD`; `--sales-credit-type=QUOTA`; `--min-opportunity-probability=0`.
+- SA Attach aliases: `cloud applications` -> `Cloud Applications`; `cloud infrastructure` -> `Cloud Infrastructure`; `hardware` -> `Hardware`; `license` -> `License`; `license and hardware` -> `License,Hardware`; `new` -> `NEW`; `expansion` -> `EXPANSION`; `workload|workloads` -> `WORKLOAD`.
+
+## Verified Org Anchors
+
+Last verified during a live run on `2026-03-27`.
+
+### Higher-level anchors
+
+| Level | Email | Notes |
+|---|---|---|
+| L1 | `luiz.meisler@oracle.com` | Executive-level anchor seen in SA Attach hours hierarchy. |
+| L2 | `marcelo.christianini@oracle.com` | Next-level org anchor above multiple manager branches. |
+
+Keep this section intentionally small. Only verified hierarchy anchors that materially shortcut discovery should stay here; one-off example managers should not.
+
+## Query Translation Shortcuts
+
+| Ask shape | Fastest reliable translation |
+|---|---|
+| `vendedor`, `sales rep`, `lider de vendas` | Interpret as `territory owner` by default for opportunity/pipeline asks unless the user explicitly requests another role. |
+| `Top arquitetos do manager X em WON com close date em janela Y` | Filter `Knowledge DV - Hours - V2` by manager hierarchy level, aggregate `# Opportunity Hours` by `SE Team Level 5 Email Address`, then intersect with `Knowledge DV - Opportunities - V2` `Opportunity ID`s filtered by `Close Date` and `Status = 'Won'`. |
+| `Mostrar booking/workload dos top arquitetos` | Use the same top-architect result, then de-duplicate by `architectEmail + opportunityId` before summing `Opportunity Value` and `Workload Amount` from `Knowledge DV - Opportunities - V2`. |
+| `Quais clientes compoem o total do arquiteto` | Reuse the same de-duplicated architect or opportunity set and pull `Customer Name`, `Opportunity Value`, and `Workload Amount` from `Knowledge DV - Opportunities - V2`. |
+| `Preciso descobrir qual nível representa o manager` | Probe `SE Team Level 1..8 Email Address` with a `%surname%` or exact-email search in `Knowledge DV - Hours - V2` before building the final query. |
+| `Quero deals WON do time do manager` | Prefer `Knowledge DV - Opportunities - V2` for `Close Date`, `Status`, `Opportunity Value`, `Workload Amount`, territory, and owner context; prefer `Knowledge DV - Hours - V2` for hierarchy ownership and allocated hours. |
+
+## Practical Rules
+
+- Prefer `--query` for ad hoc joins, filters, and groupings when it can express the ask cleanly.
+- Prefer `--sql` only when you need a dataset the normal `Security Entry Point` filter cannot express or when you must query XSA hierarchy columns directly.
+- Do not trust `Won Flag` from the hours dataset as the only `WON` filter for business reporting. Use `Knowledge DV - Opportunities - V2` `Opportunity Status = 'Won'` plus the required close-date window.
+- Use `Knowledge DV - Opportunities - V2` and the other Knowledge DV views for org-wide reads whose hierarchy starts at Latin America leadership.
+- Use `DV - SE Team` only for self-scoped questions where "my team" really means the executing user and the people below that user, plus the normal SR and session-context questions.
+- Do not use `DV - SE Team` as generic fallback for manager, territory, owner, or org-wide commercial reads.
+- When crossing org-wide opportunities/workloads with team-scoped resource enrichment, keep every org-wide row and leave the resource fields empty when no team match exists.
+- When listing clients and values for each architect, sum booking and workload only once per `architectEmail + opportunityId`.
+- If the SQL gets quote-heavy on Windows PowerShell, use the SQL runner helper script documented in [script-catalog.md](script-catalog.md) instead of passing a long `--sql` string directly through the shell.
+
+## Suggested First Read Order
+
+1. This file for manager or hierarchy or business context.
+2. [script-catalog.md](script-catalog.md) only if the CLI contract is still unclear.
+3. `fetch-sales-intelligence.mjs --catalog` only if the data contract is still unclear after the two files above.
--- a/references/script-catalog.md
+++ b/references/script-catalog.md
@@ -0,0 +1,473 @@
+# 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
+```
+
+### 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
+```