Knowledge One View CLI Docs

Oracle DV

Skill para consultar o DV LAD Knowledge One View direto pela API.

Guia consolidado da skill para onboarding, operação e consulta rápida da superfície atual.

Casos de uso práticos

Pense nesta skill como um tradutor entre linguagem de negócio e Oracle DV. Você descreve o recorte desejado no Codex; a skill decide se usa intent, view, query ou SQL, resolve a autenticação e devolve uma saída utilizável.

Exemplo 1

Workloads com SR por manager

Prompt no Codex:

"Me traga todos os workloads do cluster Brazil para a próxima semana fiscal da Oracle, cruzando quais têm SR na oportunidade de recursos abaixo de <manager de recurso>."

Esse tipo de pedido costuma cair no intent workloads-by-manager-resource-close-window. A skill resolve a semana Oracle, filtra as revenue lines e enriquece o resultado com recursos e SRs visíveis.

Exemplo 2

Pipeline com janela comercial

Prompt no Codex:

"Quais oportunidades com close no mês atual têm booking acima de 500k e territory owner abaixo de <manager comercial>?"

A skill tende a usar intents ou views comerciais em Knowledge DV - Opportunities - V2, mantendo escopo org-wide e o vocabulário comercial consistente.

Exemplo 3

SRs por recurso

Prompt no Codex:

"Liste os SRs do <recurso alocado> com status e opportunityId, em formato tabela."

Aqui a skill normalmente usa srs-by-resource ou uma view equivalente em DV - SE Team, respeitando o escopo do time visível ao usuário executor.

Exemplo 4

Formato de resposta

Resposta típica:

- semana Oracle resolvida
- escopo da leitura
- total de linhas puxadas da API
- tabela final com cliente, workload, recurso e SR

Se você pedir "mostre em tabela", "gere um relatório HTML", "monte um PDF executivo", "organize em planilha" ou "automatize o envio por email", o Codex pode transformar o payload final em entregáveis mais úteis para consumo e acompanhamento.

Instalação rápida e primeiro uso

Em uma máquina nova, a sequência ideal é: instalar a skill, confirmar a sessão Oracle DV uma vez e depois seguir browserless na rotina normal. O objetivo é gastar energia no negócio, não em setup.

Passo 1

Pedir a instalação no Codex

Prompt no Codex:

"Instale a skill knowledge-one-view-cli no Codex e valide a pasta runtime/output no workspace."

Depois disso, a skill fica instalada em ~/.codex/skills/knowledge-one-view-cli.

Passo 2

Testar a autenticação no Chrome

Prompt no Codex:

"Faça um teste de autenticação da skill via Chrome e confirme se o backend Oracle DV respondeu."

O helper abre o navegador só para gravar auth-state.json e session-meta.json no runtime do workspace.

Passo 3

Seguir browserless

Prompt no Codex:

"Me traga todos os workloads do cluster Brazil para a próxima semana fiscal da Oracle."

Daí em diante, a skill normalmente segue sem browser, consultando o backend Oracle DV direto pela API.

How-to relâmpago

Peça ao Codex para instalar ou validar a skill.
Peça ao Codex para fazer um teste de autenticação da skill via Chrome.
Conclua login e MFA.
Depois disso, siga usando em linguagem natural.

Exemplo de resposta após o primeiro uso

Resultado típico:

"Auth validado no runtime do workspace.
Backend Oracle DV acessível.
Raw rows pulled from the API: 5.
Segue a tabela com cliente, workload, close date e territory owner."

Internals - Não é necessário para usar a skill

A página foi reorganizada para funcionar bem tanto para onboarding quanto para troubleshooting. Se você estiver chegando agora, vale seguir esta ordem em vez de pular direto para os comandos.

Leitura 1

Entenda o pedido

Comece por Casos de uso e Papéis e linguagem. Eles mostram como transformar uma pergunta de negócio em um recorte consistente de owner, manager, recurso, workload e SR.

Leitura 2

Entenda a execução

Depois veja Arquitetura, Datasets e Intents. Essa parte explica de onde os dados vêm e por que a skill escolhe intent, view, query ou SQL.

Leitura 3

Entenda a operação

Feche com Auth e Runtime, Contrato de saída, Testes e Comandos. Aí você já consegue instalar, validar e depurar com segurança.

Atalho mental para usar bem

Se a pergunta for recorrente, pense em intent.
Se você quiser um extrato conhecido, pense em view.
Se precisar montar um recorte sob medida sem ir para SQL, pense em query.
Se estiver investigando um caso raro ou depurando Oracle DV, aí sim pense em sql.

Papéis e linguagem

Este guia evita nomes pessoais e usa papéis de negócio. Isso deixa a documentação mais transferível, mais segura e mais fácil de reaproveitar em outros times.

Papéis que aparecem neste guia

<territory owner>: dono comercial direto da oportunidade ou workload.
<manager comercial>: gestor da hierarquia de territory owners usada para recortes comerciais.
<manager de recurso>: gestor do lado presales/engenharia, usado para cruzar recursos alocados em oportunidades.
<recurso alocado>: arquiteto, engenheiro ou especialista associado à oportunidade.
<time atual do usuário>: escopo visível em DV - SE Team para quem executa a skill.

Tradução prática da linguagem

Quando alguém pedir "vendedor", a leitura padrão deve ser <territory owner>.
Quando alguém pedir "recursos abaixo de um manager", a leitura costuma ser <manager de recurso> em Knowledge DV - Presales Involvement Aux - V1.
Quando alguém pedir SR, cobertura ou contexto de sessão, a leitura costuma envolver o escopo do <time atual do usuário>.
Quando o pedido mistura comercial e recurso, a skill normalmente combina fonte org-wide com enriquecimento controlado por papel.

Como ler os exemplos

Sempre que você vir um papel entre <...>, substitua pelo identificador real da sua pergunta. O papel explica qual atributo da hierarquia a skill deve usar, sem amarrar a documentação a uma pessoa específica.

Arquitetura

Estrutura simples: o fetch principal concentra a lógica de negócio e scripts/lib/runtime-paths.mjs cuida do runtime, output e bootstrap do workspace.

Fluxo principal

Parse de argumentos e validação do modo de execução.
Resolução de runtime-home, arquivos de sessão e cache.
Opcionalmente resolução de ano fiscal e contexto de sessão.
Montagem de SQL via intent, view, query declarativa ou SQL bruto.
Execução em sqlquery/execute com restauração de sessão se necessário.
Normalização de linhas, escopo, métricas, warnings e persistência opcional em arquivo.

Módulos atuais

A skill hoje está organizada em um script principal, helpers de autenticação e utilitários internos em scripts/lib/. A lista abaixo reflete os módulos realmente presentes no código atual.

Módulo	Responsabilidade
`fetch-sales-intelligence.mjs`	Catálogo local, query engine, intents, views, orchestration e execução Oracle DV.
`refresh-auth-direct.mjs`	Login Oracle sem abrir Chrome, com MFA.
`refresh-auth-state.mjs`	Refresh de auth via browser/Playwright quando o fluxo direto não basta.
`run-sales-intelligence-sql.mjs`	Ajuda para SQL longa ou sensível a quoting de shell.
`lib/runtime-paths.mjs`	Resolução canônica de `runtime`, `output`, `tmp`, bootstrap de workspace e fallback legado.
`lib/auth-shared.mjs`	Leitura, persistência e refresh dos artefatos de sessão, cookies, CSRF e metadados de autenticação.
`lib/cli-shared.mjs`	Parse de argumentos, normalização de flags e helpers utilitários de entrada.
`lib/date-windows.mjs`	Resolução de janelas temporais, semanas fiscais, quarters e atalhos como `today` ou `+7d`.
`lib/output-contract.mjs`	Montagem do payload final com `apiMetrics`, `warnings`, normalização de linhas e emissão JSON.

Endpoint e estado local

Endpoint principal: POST /ui/dv/ui/api/v1/sqlquery/execute.
Workbook alvo: salesintelligence-dv.oracle.com no report path LAD Knowledge One View.
Estado persistido: auth-state.json e session-meta.json.
Fallback legado de leitura: ~/.codex/oracle-sales-intelligence-direct/.

Datasets

Resumo das fontes realmente usadas pela skill e do papel de cada uma. Esta seção existe para evitar o erro mais comum nesse tipo de análise: consultar a fonte certa com a leitura errada de escopo.

Dataset	Escopo	Papel principal	Observações
`Knowledge DV - Opportunities - V2`	Org-wide	Fonte comercial principal: pipeline, opportunities, won, close date, booking, workload, territory e owner.	Base normal para `opportunities-default`, `opportunities-close-` e views `sa-attach-` comerciais.
`Knowledge DV - Hours - V2`	Org-wide por padrão; my-team com `--scope my-team`	Horas, ownership e produtividade por hierarquia.	Exposto em `sa-attach-hours-by-opportunity`; em `--scope auto` preserva a leitura org-wide.
`Knowledge DV - Presales Involvement Aux - V1`	Org-wide por padrão; my-team com `--scope my-team`	Cobertura e vínculo manager/recurso/oportunidade.	Base normal para cobertura presales e linkage manager/recurso; intents de workload/manager usam essa leitura org-wide.
`DV - SE Team`	My-team-only	Session context, SRs e fallback comercial só quando a pergunta é explicitamente do time atual.	Não usar como fonte comercial genérica org-wide.
`Knowledge DV - Revn Lines by SE`	Org-wide por padrão; my-team com `--scope my-team`	Detalhe de revenue lines.	Exposto por `revenue-line-details` como extrato org-wide em `--scope auto`.

Como escolher a fonte certa

Se a pergunta é comercial e precisa preservar todas as oportunidades do recorte, a base tende a ser Knowledge DV - Opportunities - V2.
Se a pergunta é sobre quem está alocado, coberto ou relacionado a uma oportunidade, a base tende a ser Knowledge DV - Presales Involvement Aux - V1 e a skill tenta org-wide primeiro.
Se a pergunta é sobre SR, contexto da sessão ou o time visível do executor, a base tende a passar por DV - SE Team.
Se a pergunta é sobre horas e produtividade, a skill tende a usar Knowledge DV - Hours - V2 em org-wide, salvo pedido explícito de time atual.
Se a pergunta é sobre revenue line detalhada, a skill tende a olhar Knowledge DV - Revn Lines by SE em org-wide, salvo pedido explícito de time atual.

Defaults SA Attach

cluster=Brazil, sales-credit-type=QUOTA, solution=Cloud Infrastructure - Workloads, Hardware - Bookings, On-Premise Technology - Bookings, revenue-type-group=NEW,EXPANSION,WORKLOAD.

Aliases importantes

workload e workloads normalizam para WORKLOAD. license and hardware normaliza para License,Hardware.

Monetário

Outputs comerciais usam preferencialmente bookingValue e workloadAmount; a seção raw preserva o valor nativo do backend.

Intents

Use intent primeiro quando o pedido já parece um caso de negócio recorrente. Essa é a forma mais fácil de pedir algo no Codex sem precisar pensar em SQL, aliases ou tabelas internas.

Intent	Quando usar	Entrada chave	Escopo
`opportunities-default`	Consulta comercial padrão de pipeline/opportunities.	`--limit`	Org-wide
`opportunities-close-date`	Close date exata.	`--date`	Org-wide
`opportunities-close-month`	Mês calendário.	`--month`	Org-wide
`opportunities-close-quarter`	Quarter fiscal.	`--quarter`	Org-wide
`opportunities-current-team-close-window`	Janela comercial org-wide enriquecida com cobertura do time atual.	janela de datas	Mixed-consistent
`opportunities-by-resource-close-window`	Janela comercial com cobertura de um recurso explícito.	`--resource` + janela	Org-wide
`opportunities-by-manager-close-window`	Janela comercial com cobertura de um manager explícito.	`--manager-email` + janela	Org-wide
`workloads-by-owner-current`	Estado atual de workloads para um territory owner.	`--owner-email`	Org-wide
`workloads-by-owner-manager-current`	Estado atual de workloads sob um manager de owners.	`--owner-manager-email`	Org-wide
`workloads-by-manager-resource-close-window`	Revenue lines workload com manager/resource allocation org-wide e SRs visíveis do time.	`--manager-email-list` + janela	Mixed-consistent
`srs-by-resource`	SRs por recurso Oracle.	`--resource`	My-team-only

Views

Use view quando você já sabe exatamente o shape do extrato que quer. Views são boas para integrações, análises repetidas e validações em cima de um contrato estável, sem precisar redescobrir campo por campo.

View	Fonte	Escopo	Uso
`current-fiscal-year`	DV session	My-team-only	Ano fiscal da sessão Oracle DV.
`data-quality-session-context`	DV session	My-team-only	Entry point e variáveis fiscais da sessão.
`effort-by-se-team`	DV - SE Team	My-team-only	Horas por membro do time.
`effort-task-type-summary`	DV - SE Team	My-team-only	Horas por task type.
`opportunities-close-window`	Knowledge DV - Opportunities - V2	Org-wide	Uma linha por oportunidade em janela de close date.
`opportunity-details`	Knowledge DV - Opportunities - V2	Org-wide	Detalhe comercial de oportunidades.
`revenue-line-details`	Knowledge DV - Revn Lines by SE	Org-wide	Detalhe de revenue lines.
`sa-attach-hours-by-opportunity`	Knowledge DV - Hours - V2	Org-wide	Horas/cobertura por oportunidade.
`sa-attach-involvement-distribution`	Knowledge DV - Opportunities - V2	Org-wide	Distribuição agregada por bucket de envolvimento.
`sa-attach-open-pipeline`	Knowledge DV - Opportunities - V2	Org-wide	Métrica de pipeline aberto.
`sa-attach-pipeline-details`	Knowledge DV - Opportunities - V2	Org-wide	Extrato comercial mais completo da skill.
`sa-attach-presales-coverage`	Knowledge DV - Presales Involvement Aux - V1	Org-wide	Cobertura presales por oportunidade.
`sa-attach-won-pipeline`	Knowledge DV - Opportunities - V2	Org-wide	Métrica de pipeline won.
`sr-details`	DV - SE Team	My-team-only	Detalhe de SR.
`srs-by-resource-email`	DV - SE Team	My-team-only	SRs por email de recurso.
`won-and-open-by-se-opty`	DV - SE Team	My-team-only	Contribuição por oportunidade e membro do time.

Notas rápidas de escopo

org-wide: linhas comerciais visíveis para a hierarquia comercial da workbook.
my-team-only: visibilidade limitada ao time do usuário executor em DV - SE Team.
mixed-consistent: linhas comerciais org-wide preservadas, enriquecimento de recursos/SRs restrito ao escopo apropriado.
scope.components: detalhe fonte por fonte; prefira esse campo quando o resultado combinar escopos.

Superfície CLI

A CLI existe para quando você quer rodar a skill manualmente ou entender o que o Codex está fazendo por baixo. Cada chamada deve escolher exatamente um modo entre --intent, --view, --query e --sql.

Modos

--intent: caminho preferido para perguntas recorrentes.
--view: extrato conhecido, contrato estável.
--query: aliases + filtros + grouping + ordering, com inferência de fonte e política org-wide-first por padrão.
--sql: SQL lógico Oracle bruto, com placeholders locais.
--render-sql: render local para --query ou --sql, sem backend.

Discovery

--catalog
--list-views, --describe-view
--list-intents, --describe-intent
--list-fields, --describe-field
--list-parameters, --describe-parameter
--list-scripts, --describe-script

Janela temporal

--date, --month, --quarter, --week ou o par --from-date/--to-date. Nunca combine entre si.

Hierarquia e recurso

--resource, --resource-email, --manager-email, --manager-email-list, --owner-email, --owner-manager-email, --match-role.

Filtros SA Attach

--cluster, --solution, --revenue-line-status, --executive-product-lob, --revenue-type-group, --sales-credit-type, --min-opportunity-probability, --forecast-type.

Escopo

--scope auto tenta org-wide primeiro nas fontes XSA compatíveis; --scope my-team força a leitura do time atual quando a fonte suporta esse recorte.

Modelo de week

week-year é o ano de início do ciclo Junho-Maio.
No contexto atual, o ciclo default é 2025-06-01 até 2026-05-31.
Exemplos: W1 = 2025-06-01..2025-06-07, W43 = 2026-03-22..2026-03-28, W53 = 2026-05-31.

Regra prática de escolha

Comece por --intent sempre que existir um intent compatível com a pergunta.
Use --view quando você quer consistência de colunas para export, reconciliação ou integração.
Use --query quando a pergunta é nova, mas ainda cabe em aliases conhecidos e filtros claros.
Deixe --sql para casos realmente excepcionais, porque ele exige mais cuidado com Oracle DV e aumenta a chance de drift de contrato.

Auth e Runtime

O objetivo é reutilizar sessão local e abrir browser apenas quando a sessão precisar ser refeita. Em uso normal, a skill deve parecer browserless mesmo quando houve uma autenticação inicial no Chrome.

Arquivos de sessão

<workspace>/knowledge-one-view-cli/runtime/auth-state.json
<workspace>/knowledge-one-view-cli/runtime/session-meta.json
<workspace>/knowledge-one-view-cli/runtime/chrome-profile/

Leitura pode cair para o legado em ~/.codex/oracle-sales-intelligence-direct/ quando o runtime novo ainda está vazio.

Estratégia de autenticação

--check-auth só diagnostica.
refresh-auth-direct.mjs é o caminho preferido para MFA sem browser.
refresh-auth-state.mjs é helper de browser para troubleshooting ou refresh interativo.
Em execução normal, o fetch pode disparar refresh automático e reexecutar a consulta.

Como pensar o runtime no workspace

A árvore operacional do workspace é a âncora da instalação migrada de máquina. É ali que a skill grava autenticação, outputs e arquivos temporários; por isso a checagem inicial deve validar esse diretório antes de qualquer teste de negócio.

Playwright / browser helper

Procura runtime em módulos locais, skill compartilhada ~/.codex/skills/playwright e runtimes empacotados do Codex.
Útil em máquinas novas: normalmente o helper já funciona sem instalação adicional fora do ambiente Codex.

Contrato de saída

O formato JSON é estável e foi desenhado para consumo por agente e leitura humana. A ideia é que a mesma execução possa servir para responder no chat, exportar para arquivo e depurar um problema sem reinventar o payload.

Campo	Função
`request`	Modo, flags resolvidas, escopo, SQL final e contexto da execução.
`scope`	Disclosure canônico de escopo com `scopeMode`, explicação e linhas de divulgação.
`apiMetrics`	Contagem crua de linhas puxadas do Oracle DV. Este é o número oficial de esforço de API.
`columns`	Colunas estáveis do payload final.
`records`	Registros já normalizados.
`summary`	Agregados de intents derivados quando aplicável.
`warnings`	Limite atingido, fallback, SQL custom sem alias estável, etc.
`raw`	Payload nativo do Oracle DV para debugging.

Scope modes

org-wide, my-team-only e mixed-consistent.

Métricas

apiMetrics.totalRowsPulledFromApi nunca deve ser trocado por records.length.

Moedas

bookingValue e workloadAmount saem formatados em k; raw preserva o valor nativo.

Como interpretar o payload sem se perder

Leia request para entender o que a skill realmente executou, mesmo que o prompt original tenha sido mais informal.
Leia scope antes de tirar conclusão de negócio; é ele que explica se o recorte é org-wide, my-team-only ou misto.
Leia records como resultado final pronto para tabela, CSV ou resumo executivo.
Volte para raw apenas quando precisar investigar divergência com o backend Oracle DV.

Hierarquia e semântica

Regras que evitam leituras erradas de manager, território, time atual e cobertura. Esta é a seção mais importante quando a pergunta mistura owner comercial, manager de recurso e SR no mesmo resultado.

Heurísticas úteis

Em produtividade estilo SA Attach: L3 costuma ser o anchor de manager, L4 o manager direto e L5 o IC/arquiteto.
Não assumir que Security.Entry Point replica a hierarquia comercial desejada.
vendedor, sales rep e lider de vendas devem ser lidos como territory owner por padrão.
Para perguntas por manager/recurso, priorizar Knowledge DV - Presales Involvement Aux - V1 para cobertura e Knowledge DV - Opportunities - V2 para monetário e close date.

Papéis típicos na hierarquia

Anchors altos da hierarquia costumam ser úteis para leituras executivas ou rollups amplos.
O nível usado como <manager comercial> costuma ser o ponto de corte para pipeline, owner e workload em leitura org-wide.
O nível usado como <manager de recurso> costuma ser o ponto de corte para cobertura, recursos alocados e cruzamento com SR.
O nível usado como <recurso alocado> costuma representar o IC, arquiteto ou engenheiro diretamente vinculado à oportunidade.

Regras de escopo que precisam aparecer na resposta

Quando o resultado for misto: deixar explícito que oportunidades/workloads são org-wide e recursos/SRs podem ser limitados ao time atual.
No intent workloads-by-manager-resource-close-window, resourceDetails.srNumbers mistura SR direto confirmado com candidatos internos por mesmo customer quando não há opportunityId utilizável.
Linhas comerciais org-wide nunca devem sumir só porque não houve match de recurso no enriquecimento.

Leitura segura para perguntas cruzadas

Quando alguém pedir "quais workloads do Brasil têm SR na oportunidade de recursos abaixo de <manager de recurso>", a leitura correta não é "mostrar apenas o que existe no time". A leitura correta é preservar o conjunto comercial do recorte e, em seguida, enriquecer com a visibilidade de recursos e SR disponível para o papel consultado.

Estrutura de pastas

Separação clara entre skill instalada e árvore operacional do workspace.

Skill instalada

knowledge-one-view-cli/
  SKILL.md
  agents/
    openai.yaml
  portable-setup.md
  scripts/
    fetch-sales-intelligence.mjs
    refresh-auth-direct.mjs
    refresh-auth-state.mjs
    run-sales-intelligence-sql.mjs
    lib/
      auth-shared.mjs
      cli-shared.mjs
      date-windows.mjs
      output-contract.mjs
      runtime-paths.mjs
  references/
    api-map.md
    initial-context-catalog.md
    script-catalog.md
  docs/
    docs.html
    tests.html
  tests/
    README.md
    run.mjs
    functions.test.mjs
    sales-prompts.test.mjs
    helpers/
      catalogs.mjs
      cli.mjs
      examples.mjs
    prompts/
      sales-prompts.json

Workspace-side

<workspace>/
  knowledge-one-view-cli/
    output/
      test-runs/
      *.json / *.csv
    runtime/
      auth-state.json
      session-meta.json
      chrome-profile/
    tmp/
      tmp-render-output-*.json

Testes e validação

A skill possui uma suíte pequena e executável em tests/, com relatório humano em docs/tests.html. Esta parte separa duas perguntas: se o contrato local continua estável e se o backend ainda responde como esperado.

Status recente

Offline passou com 12 pass, 0 falhas e 1 live skipped. Live passou com 13 pass e 0 falhas.

O que o offline cobre

Funções locais, SQL renderizado, escopo, contratos de CLI, prompts documentados e summaries com dados controlados.

O que o live cobre

Execução real de comandos já mapeados contra Oracle DV, com --no-cache, escopo, fonte e métricas esperadas.

Suite	Objetivo
`functions.test.mjs`	Funções locais, janelas de data, SQL, escopo, summaries e métricas.
`sales-prompts.test.mjs`	Mapeamento documentado de prompts para comandos CLI e checks live opcionais.
`tests/prompts/sales-prompts.json`	Casos de prompt com argumentos esperados e placeholders dinâmicos para pessoas.
`docs/tests.html`	Relatório legível em português e espanhol com objetivos, entradas, saídas e avaliação.

Sequência recomendada de validação

Rode node tests/run.mjs para validar contrato local sem Oracle DV.
Quando houver sessão válida, rode o live com KNOWLEDGE_ONE_VIEW_LIVE=1 e ORACLE_SI_RUNTIME_HOME.
Use docs/tests.html para revisar objetivo, entrada, saída e avaliação de cada caso.
Só depois avance para um teste de negócio novo, como um workload do Brasil ou um cruzamento com SR.

Comandos úteis

Esses exemplos ajudam a entender o que a skill faz por baixo do pedido em linguagem natural. Use-os como referência manual, não como ponto de partida obrigatório; no dia a dia, o ideal é continuar pedindo em português claro para o Codex.

Discovery e render

node scripts/fetch-sales-intelligence.mjs --list-intents

node scripts/fetch-sales-intelligence.mjs \
  --render-sql \
  --query \
  --select opportunityId,bookingValue \
  --where "opportunityId IS NOT NULL"

Execução normal

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

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

Janela e cobertura

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

node scripts/fetch-sales-intelligence.mjs \
  --intent workloads-by-manager-resource-close-window \
  --manager-email-list <manager de recurso A>@oracle.com,<manager de recurso B>@oracle.com \
  --from-date today \
  --to-date +7d

Auth e testes

node scripts/fetch-sales-intelligence.mjs --check-auth

node scripts/refresh-auth-direct.mjs --username <usuario oracle>@oracle.com

node tests/run.mjs

KNOWLEDGE_ONE_VIEW_LIVE=1 \
ORACLE_SI_RUNTIME_HOME=/path/to/workspace/knowledge-one-view-cli/runtime \
node tests/run.mjs

Quando usar cada bloco

Discovery e render serve para entender o catálogo e inspecionar SQL sem tocar o backend.
Execução normal serve para consultas diretas de pipeline e close date.
Janela e cobertura serve para cruzamentos por manager, recurso e período fiscal.
Auth e testes serve para onboarding, migração de máquina e troubleshooting controlado.

Boas práticas

Regras curtas para manter uso e manutenção consistentes. Se a skill continuar simples de operar, a tendência é ela permanecer confiável mesmo quando o workbook ou o ambiente mudarem.

Preferir --intent para perguntas recorrentes e --query para ad hoc; cair para --sql só quando necessário.
Usar aliases de campo locais e placeholders como {{opportunityId}} e {{securityEntryPointFilter}} em vez de adivinhar expressão Oracle.
Tratar DV - SE Team como fonte de time atual e SR, não como leitura comercial org-wide genérica.
Quando misturar org-wide com enriquecimento de recurso, preservar sempre a linha comercial original.
Em PowerShell, usar run-sales-intelligence-sql.mjs para SQL longa ou com quoting frágil.
Usar --output-file para persistir payloads finais; nomes temporários/intermediários vão para tmp/.
Documentação oficial da skill fica em docs/docs.html; catálogos operacionais continuam em references/.

Documento consolidado da skill knowledge-one-view-cli. Mantido para leitura rápida, onboarding e referência operacional sem duplicação desnecessária.

Oracle DV

Skill para consultar el DV LAD Knowledge One View directamente por la API.

Guía consolidada de la skill para onboarding, operación y consulta rápida de la superficie actual.

Casos de uso prácticos

Piense en esta skill como un traductor entre el lenguaje de negocio y Oracle DV. Usted describe el alcance deseado en Codex; la skill decide si usa intent, view, query o SQL, resuelve la autenticación y devuelve una salida utilizable.

Ejemplo 1

Workloads con SR por manager

Prompt en Codex:

"Tráeme todos los workloads del cluster Brazil para la próxima semana fiscal de Oracle, cruzando cuáles tienen SR en la oportunidad con recursos bajo <manager de recursos>."

Este tipo de solicitud suele caer en el intent workloads-by-manager-resource-close-window. La skill resuelve la semana Oracle, filtra las revenue lines y enriquece el resultado con recursos y SRs visibles.

Ejemplo 2

Pipeline con ventana comercial

Prompt en Codex:

"¿Qué oportunidades con close en el mes actual tienen booking por encima de 500k y territory owner bajo <manager comercial>?"

La skill tiende a usar intents o views comerciales en Knowledge DV - Opportunities - V2, manteniendo alcance org-wide y el vocabulario comercial consistente.

Ejemplo 3

SRs por recurso

Prompt en Codex:

"Liste los SRs de <recurso asignado> con status y opportunityId, en formato tabla."

Aquí la skill normalmente usa srs-by-resource o una view equivalente en DV - SE Team, respetando el alcance del equipo visible para el usuario ejecutor.

Ejemplo 4

Formato de respuesta

Respuesta típica:

- semana Oracle resuelta
- alcance de la lectura
- total de filas obtenidas de la API
- tabla final con cliente, workload, recurso y SR

Si usted pide "muéstralo en tabla", "genera un informe HTML", "arma un PDF ejecutivo", "organiza en una planilla" o "automatiza el envío por email", Codex puede transformar el payload final en entregables más útiles para consumo y seguimiento.

Instalación rápida y primer uso

En una máquina nueva, la secuencia ideal es: instalar la skill, confirmar la sesión Oracle DV una vez y luego seguir browserless en la rutina normal. El objetivo es gastar energía en el negocio, no en setup.

Paso 1

Pedir la instalación en Codex

Prompt en Codex:

"Instala la skill knowledge-one-view-cli en Codex y valida la carpeta runtime/output en el workspace."

Después de eso, la skill queda instalada en ~/.codex/skills/knowledge-one-view-cli.

Paso 2

Probar la autenticación en Chrome

Prompt en Codex:

"Haz una prueba de autenticación de la skill vía Chrome y confirma si el backend Oracle DV respondió."

El helper abre el navegador solo para grabar auth-state.json y session-meta.json en el runtime del workspace.

Paso 3

Seguir browserless

Prompt en Codex:

"Tráeme todos los workloads del cluster Brazil para la próxima semana fiscal de Oracle."

A partir de ahí, la skill normalmente sigue sin browser, consultando el backend Oracle DV directamente por la API.

How-to exprés

Pídale a Codex que instale o valide la skill.
Pídale a Codex que haga una prueba de autenticación de la skill vía Chrome.
Complete el login y el MFA.
Después de eso, siga usándola en lenguaje natural.

Ejemplo de respuesta después del primer uso

Resultado típico:

"Auth validada en el runtime del workspace.
Backend Oracle DV accesible.
Raw rows pulled from the API: 5.
Aquí está la tabla con cliente, workload, close date y territory owner."

Internals - No es necesario para usar la skill

La página fue reorganizada para funcionar bien tanto para onboarding como para troubleshooting. Si usted está llegando ahora, conviene seguir este orden en lugar de saltar directo a los comandos.

Lectura 1

Entienda la solicitud

Empiece por Casos de uso y Roles y lenguaje. Muestran cómo transformar una pregunta de negocio en un alcance consistente de owner, manager, recurso, workload y SR.

Lectura 2

Entienda la ejecución

Después vea Arquitectura, Datasets e Intents. Esta parte explica de dónde vienen los datos y por qué la skill elige intent, view, query o SQL.

Lectura 3

Entienda la operación

Cierre con Auth y Runtime, Contrato de salida, Pruebas y Comandos. Así ya puede instalar, validar y depurar con seguridad.

Atajo mental para usar bien

Si la pregunta es recurrente, piense en intent.
Si quiere un extracto conocido, piense en view.
Si necesita montar un alcance a medida sin ir a SQL, piense en query.
Si está investigando un caso raro o depurando Oracle DV, entonces sí piense en sql.

Roles y lenguaje

Esta guía evita nombres personales y usa roles de negocio. Eso hace la documentación más transferible, más segura y más fácil de reutilizar en otros equipos.

Roles que aparecen en esta guía

<territory owner>: dueño comercial directo de la oportunidad o workload.
<manager comercial>: responsable de la jerarquía de territory owners usada para alcances comerciales.
<manager de recursos>: responsable del lado presales/ingeniería, usado para cruzar recursos asignados en oportunidades.
<recurso asignado>: arquitecto, ingeniero o especialista asociado a la oportunidad.
<equipo actual del usuario>: alcance visible en DV - SE Team para quien ejecuta la skill.

Traducción práctica del lenguaje

Cuando alguien pida "vendedor", la lectura estándar debe ser <territory owner>.
Cuando alguien pida "recursos bajo un manager", la lectura suele ser <manager de recursos> en Knowledge DV - Presales Involvement Aux - V1.
Cuando alguien pida SR, cobertura o contexto de sesión, la lectura suele involucrar el alcance del <equipo actual del usuario>.
Cuando la solicitud mezcla comercial y recurso, la skill normalmente combina una fuente org-wide con enriquecimiento controlado por rol.

Cómo leer los ejemplos

Siempre que vea un rol entre <...>, sustitúyalo por el identificador real de su pregunta. El rol explica qué atributo de la jerarquía debe usar la skill, sin atar la documentación a una persona específica.

Arquitectura

Estructura simple: el fetch principal concentra la lógica de negocio y scripts/lib/runtime-paths.mjs se ocupa del runtime, output y bootstrap del workspace.

Flujo principal

Parse de argumentos y validación del modo de ejecución.
Resolución de runtime-home, archivos de sesión y caché.
Opcionalmente resolución de año fiscal y contexto de sesión.
Construcción de SQL vía intent, view, query declarativa o SQL bruto.
Ejecución en sqlquery/execute con restauración de sesión si es necesario.
Normalización de filas, alcance, métricas, warnings y persistencia opcional en archivo.

Módulos actuales

Actualmente, la skill está organizada en un script principal, helpers de autenticación y utilitarios internos en scripts/lib/. La lista siguiente refleja los módulos realmente presentes en el código actual.

Módulo	Responsabilidad
`fetch-sales-intelligence.mjs`	Catálogo local, query engine, intents, views, orquestación y ejecución Oracle DV.
`refresh-auth-direct.mjs`	Login Oracle sin abrir Chrome, con MFA.
`refresh-auth-state.mjs`	Refresh de auth vía browser/Playwright cuando el flujo directo no alcanza.
`run-sales-intelligence-sql.mjs`	Ayuda para SQL larga o sensible al quoting del shell.
`lib/runtime-paths.mjs`	Resolución canónica de `runtime`, `output`, `tmp`, bootstrap de workspace y fallback legado.
`lib/auth-shared.mjs`	Lectura, persistencia y refresh de los artefactos de sesión, cookies, CSRF y metadatos de autenticación.
`lib/cli-shared.mjs`	Parse de argumentos, normalización de flags y helpers utilitarios de entrada.
`lib/date-windows.mjs`	Resolución de ventanas temporales, semanas fiscales, quarters y atajos como `today` o `+7d`.
`lib/output-contract.mjs`	Construcción del payload final con `apiMetrics`, `warnings`, normalización de filas y emisión JSON.

Endpoint y estado local

Endpoint principal: POST /ui/dv/ui/api/v1/sqlquery/execute.
Workbook objetivo: salesintelligence-dv.oracle.com en el report path LAD Knowledge One View.
Estado persistido: auth-state.json y session-meta.json.
Fallback legado de lectura: ~/.codex/oracle-sales-intelligence-direct/.

Datasets

Resumen de las fuentes realmente usadas por la skill y del papel de cada una. Esta sección existe para evitar el error más común en este tipo de análisis: consultar la fuente correcta con la lectura equivocada del alcance.

Dataset	Alcance	Papel principal	Observaciones
`Knowledge DV - Opportunities - V2`	Org-wide	Fuente comercial principal: pipeline, opportunities, won, close date, booking, workload, territory y owner.	Base normal para `opportunities-default`, `opportunities-close-` y views `sa-attach-` comerciales.
`Knowledge DV - Hours - V2`	Org-wide por defecto; my-team con `--scope my-team`	Horas, ownership y productividad por jerarquía.	Expuesto en `sa-attach-hours-by-opportunity`; en `--scope auto` preserva la lectura org-wide.
`Knowledge DV - Presales Involvement Aux - V1`	Org-wide por defecto; my-team con `--scope my-team`	Cobertura y vínculo manager/recurso/oportunidad.	Base normal para cobertura presales y linkage manager/recurso; intents de workload/manager usan esta lectura org-wide.
`DV - SE Team`	My-team-only	Session context, SRs y fallback comercial solo cuando la pregunta es explícitamente del equipo actual.	No debe usarse como fuente comercial genérica org-wide.
`Knowledge DV - Revn Lines by SE`	Org-wide por defecto; my-team con `--scope my-team`	Detalle de revenue lines.	Expuesto por `revenue-line-details` como extracto org-wide en `--scope auto`.

Cómo elegir la fuente correcta

Si la pregunta es comercial y necesita preservar todas las oportunidades del alcance, la base tiende a ser Knowledge DV - Opportunities - V2.
Si la pregunta es sobre quién está asignado, cubierto o relacionado con una oportunidad, la base tiende a ser Knowledge DV - Presales Involvement Aux - V1 y la skill intenta org-wide primero.
Si la pregunta es sobre SR, contexto de la sesión o el equipo visible del ejecutor, la base tiende a pasar por DV - SE Team.
Si la pregunta es sobre horas y productividad, la skill tiende a usar Knowledge DV - Hours - V2 en org-wide, salvo solicitud explícita de equipo actual.
Si la pregunta es sobre revenue line detallada, la skill tiende a consultar Knowledge DV - Revn Lines by SE en org-wide, salvo solicitud explícita de equipo actual.

Defaults SA Attach

cluster=Brazil, sales-credit-type=QUOTA, solution=Cloud Infrastructure - Workloads, Hardware - Bookings, On-Premise Technology - Bookings, revenue-type-group=NEW,EXPANSION,WORKLOAD.

Aliases importantes

workload y workloads se normalizan a WORKLOAD. license and hardware se normaliza a License,Hardware.

Monetario

Los outputs comerciales usan preferentemente bookingValue y workloadAmount; la sección raw preserva el valor nativo del backend.

Intents

Use intent primero cuando la solicitud ya parece un caso de negocio recurrente. Esta es la forma más fácil de pedir algo en Codex sin tener que pensar en SQL, aliases o tablas internas.

Intent	Cuándo usar	Entrada clave	Alcance
`opportunities-default`	Consulta comercial estándar de pipeline/opportunities.	`--limit`	Org-wide
`opportunities-close-date`	Close date exacta.	`--date`	Org-wide
`opportunities-close-month`	Mes calendario.	`--month`	Org-wide
`opportunities-close-quarter`	Quarter fiscal.	`--quarter`	Org-wide
`opportunities-current-team-close-window`	Ventana comercial org-wide enriquecida con cobertura del equipo actual.	ventana de fechas	Mixed-consistent
`opportunities-by-resource-close-window`	Ventana comercial con cobertura de un recurso explícito.	`--resource` + ventana	Org-wide
`opportunities-by-manager-close-window`	Ventana comercial con cobertura de un manager explícito.	`--manager-email` + ventana	Org-wide
`workloads-by-owner-current`	Estado actual de workloads para un territory owner.	`--owner-email`	Org-wide
`workloads-by-owner-manager-current`	Estado actual de workloads bajo un manager de owners.	`--owner-manager-email`	Org-wide
`workloads-by-manager-resource-close-window`	Revenue lines workload con manager/resource allocation org-wide y SRs visibles del equipo.	`--manager-email-list` + ventana	Mixed-consistent
`srs-by-resource`	SRs por recurso Oracle.	`--resource`	My-team-only

Views

Use view cuando ya sabe exactamente el shape del extracto que quiere. Las views son buenas para integraciones, análisis repetidos y validaciones sobre un contrato estable, sin tener que redescubrir campo por campo.

View	Fuente	Alcance	Uso
`current-fiscal-year`	DV session	My-team-only	Año fiscal de la sesión Oracle DV.
`data-quality-session-context`	DV session	My-team-only	Entry point y variables fiscales de la sesión.
`effort-by-se-team`	DV - SE Team	My-team-only	Horas por miembro del equipo.
`effort-task-type-summary`	DV - SE Team	My-team-only	Horas por task type.
`opportunities-close-window`	Knowledge DV - Opportunities - V2	Org-wide	Una fila por oportunidad en ventana de close date.
`opportunity-details`	Knowledge DV - Opportunities - V2	Org-wide	Detalle comercial de oportunidades.
`revenue-line-details`	Knowledge DV - Revn Lines by SE	Org-wide	Detalle de revenue lines.
`sa-attach-hours-by-opportunity`	Knowledge DV - Hours - V2	Org-wide	Horas/cobertura por oportunidad.
`sa-attach-involvement-distribution`	Knowledge DV - Opportunities - V2	Org-wide	Distribución agregada por bucket de involucramiento.
`sa-attach-open-pipeline`	Knowledge DV - Opportunities - V2	Org-wide	Métrica de pipeline abierto.
`sa-attach-pipeline-details`	Knowledge DV - Opportunities - V2	Org-wide	Extracto comercial más completo de la skill.
`sa-attach-presales-coverage`	Knowledge DV - Presales Involvement Aux - V1	Org-wide	Cobertura presales por oportunidad.
`sa-attach-won-pipeline`	Knowledge DV - Opportunities - V2	Org-wide	Métrica de pipeline won.
`sr-details`	DV - SE Team	My-team-only	Detalle de SR.
`srs-by-resource-email`	DV - SE Team	My-team-only	SRs por email de recurso.
`won-and-open-by-se-opty`	DV - SE Team	My-team-only	Contribución por oportunidad y miembro del equipo.

Notas rápidas de alcance

org-wide: filas comerciales visibles para la jerarquía comercial del workbook.
my-team-only: visibilidad limitada al equipo del usuario ejecutor en DV - SE Team.
mixed-consistent: filas comerciales org-wide preservadas, enriquecimiento de recursos/SRs restringido al alcance apropiado.
scope.components: detalle fuente por fuente; prefiera ese campo cuando el resultado combine alcances.

Superficie CLI

La CLI existe para cuando quiere ejecutar la skill manualmente o entender qué está haciendo Codex por debajo. Cada llamada debe elegir exactamente un modo entre --intent, --view, --query y --sql.

Modos

--intent: camino preferido para preguntas recurrentes.
--view: extracto conocido, contrato estable.
--query: aliases + filtros + grouping + ordering, con inferencia de fuente y política org-wide-first por defecto.
--sql: SQL lógico Oracle bruto, con placeholders locales.
--render-sql: render local para --query o --sql, sin backend.

Discovery

--catalog
--list-views, --describe-view
--list-intents, --describe-intent
--list-fields, --describe-field
--list-parameters, --describe-parameter
--list-scripts, --describe-script

Ventana temporal

--date, --month, --quarter, --week o el par --from-date/--to-date. Nunca los combine entre sí.

Jerarquía y recurso

--resource, --resource-email, --manager-email, --manager-email-list, --owner-email, --owner-manager-email, --match-role.

Filtros SA Attach

--cluster, --solution, --revenue-line-status, --executive-product-lob, --revenue-type-group, --sales-credit-type, --min-opportunity-probability, --forecast-type.

Alcance

--scope auto intenta org-wide primero en fuentes XSA compatibles; --scope my-team fuerza la lectura del equipo actual cuando la fuente soporta ese alcance.

Modelo de week

week-year es el año de inicio del ciclo Junio-Mayo.
En el contexto actual, el ciclo default es 2025-06-01 hasta 2026-05-31.
Ejemplos: W1 = 2025-06-01..2025-06-07, W43 = 2026-03-22..2026-03-28, W53 = 2026-05-31.

Regla práctica de elección

Empiece por --intent siempre que exista un intent compatible con la pregunta.
Use --view cuando quiera consistencia de columnas para export, reconciliación o integración.
Use --query cuando la pregunta es nueva, pero todavía cabe en aliases conocidos y filtros claros.
Deje --sql para casos realmente excepcionales, porque exige más cuidado con Oracle DV y aumenta la posibilidad de drift de contrato.

Auth y Runtime

El objetivo es reutilizar la sesión local y abrir el browser solo cuando la sesión necesite rehacerse. En uso normal, la skill debe parecer browserless incluso cuando hubo una autenticación inicial en Chrome.

Archivos de sesión

<workspace>/knowledge-one-view-cli/runtime/auth-state.json
<workspace>/knowledge-one-view-cli/runtime/session-meta.json
<workspace>/knowledge-one-view-cli/runtime/chrome-profile/

La lectura puede caer al legado en ~/.codex/oracle-sales-intelligence-direct/ cuando el runtime nuevo todavía está vacío.

Estrategia de autenticación

--check-auth solo diagnostica.
refresh-auth-direct.mjs es el camino preferido para MFA sin browser.
refresh-auth-state.mjs es helper de browser para troubleshooting o refresh interactivo.
En ejecución normal, el fetch puede disparar refresh automático y reejecutar la consulta.

Cómo pensar el runtime en el workspace

El árbol operativo del workspace es el ancla de la instalación migrada de máquina. Es allí donde la skill graba autenticación, outputs y archivos temporales; por eso la verificación inicial debe validar ese directorio antes de cualquier prueba de negocio.

Playwright / browser helper

Busca runtime en módulos locales, skill compartida ~/.codex/skills/playwright y runtimes empaquetados de Codex.
Útil en máquinas nuevas: normalmente el helper ya funciona sin instalación adicional fuera del entorno Codex.

Contrato de salida

El formato JSON es estable y fue diseñado para consumo por agente y lectura humana. La idea es que la misma ejecución pueda servir para responder en el chat, exportar a archivo y depurar un problema sin reinventar el payload.

Campo	Función
`request`	Modo, flags resueltas, alcance, SQL final y contexto de la ejecución.
`scope`	Disclosure canónico de alcance con `scopeMode`, explicación y líneas de divulgación.
`apiMetrics`	Conteo bruto de filas obtenidas de Oracle DV. Este es el número oficial de esfuerzo de API.
`columns`	Columnas estables del payload final.
`records`	Registros ya normalizados.
`summary`	Agregados de intents derivados cuando aplica.
`warnings`	Límite alcanzado, fallback, SQL custom sin alias estable, etc.
`raw`	Payload nativo de Oracle DV para debugging.

Scope modes

org-wide, my-team-only y mixed-consistent.

Métricas

apiMetrics.totalRowsPulledFromApi nunca debe ser reemplazado por records.length.

Monedas

bookingValue y workloadAmount salen formateados en k; raw preserva el valor nativo.

Cómo interpretar el payload sin perderse

Lea request para entender qué ejecutó realmente la skill, incluso si el prompt original fue más informal.
Lea scope antes de sacar una conclusión de negocio; ese campo explica si el alcance es org-wide, my-team-only o mixto.
Lea records como resultado final listo para tabla, CSV o resumen ejecutivo.
Vuelva a raw solo cuando necesite investigar una divergencia con el backend Oracle DV.

Jerarquía y semántica

Reglas que evitan lecturas equivocadas de manager, territorio, equipo actual y cobertura. Esta es la sección más importante cuando la pregunta mezcla owner comercial, manager de recursos y SR en el mismo resultado.

Heurísticas útiles

En productividad estilo SA Attach: L3 suele ser el anchor de manager, L4 el manager directo y L5 el IC/arquitecto.
No asumir que Security.Entry Point replica la jerarquía comercial deseada.
vendedor, sales rep y líder de ventas deben leerse como territory owner por defecto.
Para preguntas por manager/recurso, priorizar Knowledge DV - Presales Involvement Aux - V1 para cobertura y Knowledge DV - Opportunities - V2 para monetario y close date.

Roles típicos en la jerarquía

Anchors altos de la jerarquía suelen ser útiles para lecturas ejecutivas o rollups amplios.
El nivel usado como <manager comercial> suele ser el punto de corte para pipeline, owner y workload en lectura org-wide.
El nivel usado como <manager de recursos> suele ser el punto de corte para cobertura, recursos asignados y cruce con SR.
El nivel usado como <recurso asignado> suele representar al IC, arquitecto o ingeniero directamente vinculado a la oportunidad.

Reglas de alcance que deben aparecer en la respuesta

Cuando el resultado sea mixto: dejar explícito que oportunidades/workloads son org-wide y recursos/SRs pueden estar limitados al equipo actual.
En el intent workloads-by-manager-resource-close-window, resourceDetails.srNumbers mezcla SR directo confirmado con candidatos internos del mismo customer cuando no hay opportunityId utilizable.
Las filas comerciales org-wide nunca deben desaparecer solo porque no hubo match de recurso en el enriquecimiento.

Lectura segura para preguntas cruzadas

Cuando alguien pida "qué workloads de Brasil tienen SR en la oportunidad con recursos bajo <manager de recursos>", la lectura correcta no es "mostrar solo lo que existe en el equipo". La lectura correcta es preservar el conjunto comercial del alcance y, a continuación, enriquecerlo con la visibilidad de recursos y SR disponible para el rol consultado.

Estructura de carpetas

Separación clara entre la skill instalada y el árbol operativo del workspace.

Skill instalada

knowledge-one-view-cli/
  SKILL.md
  agents/
    openai.yaml
  portable-setup.md
  scripts/
    fetch-sales-intelligence.mjs
    refresh-auth-direct.mjs
    refresh-auth-state.mjs
    run-sales-intelligence-sql.mjs
    lib/
      auth-shared.mjs
      cli-shared.mjs
      date-windows.mjs
      output-contract.mjs
      runtime-paths.mjs
  references/
    api-map.md
    initial-context-catalog.md
    script-catalog.md
  docs/
    docs.html
    tests.html
  tests/
    README.md
    run.mjs
    functions.test.mjs
    sales-prompts.test.mjs
    helpers/
      catalogs.mjs
      cli.mjs
      examples.mjs
    prompts/
      sales-prompts.json

Lado del workspace

<workspace>/
  knowledge-one-view-cli/
    output/
      test-runs/
      *.json / *.csv
    runtime/
      auth-state.json
      session-meta.json
      chrome-profile/
    tmp/
      tmp-render-output-*.json

Pruebas y validación

La skill posee una suite pequeña y ejecutable en tests/, con reporte humano en docs/tests.html. Esta parte separa dos preguntas: si el contrato local sigue estable y si el backend todavía responde como se espera.

Estado reciente

Offline pasó con 12 pass, 0 fallas y 1 live skipped. Live pasó con 13 pass y 0 fallas.

Qué cubre offline

Funciones locales, SQL renderizado, alcance, contratos de CLI, prompts documentados y summaries con datos controlados.

Qué cubre live

Ejecución real de comandos ya mapeados contra Oracle DV, con --no-cache, alcance, fuente y métricas esperadas.

Suite	Objetivo
`functions.test.mjs`	Funciones locales, ventanas de fecha, SQL, alcance, summaries y métricas.
`sales-prompts.test.mjs`	Mapeo documentado de prompts a comandos CLI y checks live opcionales.
`tests/prompts/sales-prompts.json`	Casos de prompt con argumentos esperados y placeholders dinámicos para personas.
`docs/tests.html`	Reporte legible en portugués y español con objetivos, entradas, salidas y evaluación.

Secuencia recomendada de validación

Ejecute node tests/run.mjs para validar el contrato local sin Oracle DV.
Cuando haya sesión válida, ejecute live con KNOWLEDGE_ONE_VIEW_LIVE=1 y ORACLE_SI_RUNTIME_HOME.
Use docs/tests.html para revisar objetivo, entrada, salida y evaluación de cada caso.
Solo después avance a una prueba de negocio nueva, como un workload de Brasil o un cruce con SR.

Comandos útiles

Estos ejemplos ayudan a entender qué hace la skill detrás de una solicitud en lenguaje natural. Úselos como referencia manual, no como punto de partida obligatorio; en el día a día, lo ideal es seguir pidiendo en español claro a Codex.

Discovery y render

node scripts/fetch-sales-intelligence.mjs --list-intents

node scripts/fetch-sales-intelligence.mjs \
  --render-sql \
  --query \
  --select opportunityId,bookingValue \
  --where "opportunityId IS NOT NULL"

Ejecución normal

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

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

Ventana y cobertura

node scripts/fetch-sales-intelligence.mjs \
  --intent opportunities-by-manager-close-window \
  --manager-email <manager de recursos>@oracle.com \
  --week w2 \
  --week-year 2026

node scripts/fetch-sales-intelligence.mjs \
  --intent workloads-by-manager-resource-close-window \
  --manager-email-list <manager de recursos A>@oracle.com,<manager de recursos B>@oracle.com \
  --from-date today \
  --to-date +7d

Auth y pruebas

node scripts/fetch-sales-intelligence.mjs --check-auth

node scripts/refresh-auth-direct.mjs --username <usuario oracle>@oracle.com

node tests/run.mjs

KNOWLEDGE_ONE_VIEW_LIVE=1 \
ORACLE_SI_RUNTIME_HOME=/path/to/workspace/knowledge-one-view-cli/runtime \
node tests/run.mjs

Cuándo usar cada bloque

Discovery y render sirve para entender el catálogo e inspeccionar SQL sin tocar el backend.
Ejecución normal sirve para consultas directas de pipeline y close date.
Ventana y cobertura sirve para cruces por manager, recurso y período fiscal.
Auth y pruebas sirve para onboarding, migración de máquina y troubleshooting controlado.

Buenas prácticas

Reglas cortas para mantener el uso y el mantenimiento consistentes. Si la skill sigue siendo simple de operar, la tendencia es que permanezca confiable incluso cuando el workbook o el entorno cambien.

Preferir --intent para preguntas recurrentes y --query para ad hoc; caer a --sql solo cuando sea necesario.
Usar aliases de campo locales y placeholders como {{opportunityId}} y {{securityEntryPointFilter}} en lugar de adivinar la expresión Oracle.
Tratar DV - SE Team como fuente del equipo actual y SR, no como lectura comercial org-wide genérica.
Cuando mezcle org-wide con enriquecimiento de recurso, preservar siempre la fila comercial original.
En PowerShell, usar run-sales-intelligence-sql.mjs para SQL larga o con quoting frágil.
Usar --output-file para persistir payloads finales; nombres temporales/intermedios van a tmp/.
La documentación oficial de la skill queda en docs/docs.html; los catálogos operativos siguen en references/.

Documento consolidado de la skill knowledge-one-view-cli. Mantenido para lectura rápida, onboarding y referencia operativa sin duplicación innecesaria.