# Ergon Archon Screen Discovery

> Investigate legacy Ergon/Archon screens for Oracle lineage and Java API migration. Use for screen workflow, debug/XML components, SQL lineage, resources and Parte 1 API contracts. Requests to identify or migrate active customer customizations or business rules on a write operation belong to ergon-rule-migration-orchestration, even when a screen identifier is the only context.

- Skill: `codexrodrigues/ergon-archon-screen-discovery` (Agent Skill, multi-file: 35 files)
- Install (CLI): `npx get-skill add codexrodrigues/ergon-archon-screen-discovery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/ergon-archon-screen-discovery/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/ergon-archon-screen-discovery

---


# Ergon Archon Screen Discovery

When available, consult the derived `praxis-screen-discovery-matrix` before
starting discovery to choose comparable pilots and identify known contracts or
runtime gaps. Regenerate it after discovery changes the operation inventory or
phase gate. It is an index only: XML/runtime evidence, the phase gate and the
canonical Praxis resource contract decide discovery conclusions.

Use this skill to turn an exploratory Ergon/Archon screen investigation into a reproducible migration package. Prefer evidence-backed conclusions over naming conventions. When coordinating a multi-phase migration, use `ergon-migration-orchestration` first to verify phase gates and artifact handoff.

## Rule-intent handoff

Do not answer a Parte 2 request for an active customer customization from XML,
JavaScript, `onChanged`, field validation or another client-side screen rule
merely because those sources are easy to locate. A short prompt such as
“identifique uma customização cliente ativa na escrita de <SCREEN>” carries an
intent plus identifier: resolve the existing Parte 1 write handoff and route to
`ergon-rule-migration-orchestration`. You must use that skill before issuing
any active/inactive conclusion; do not finish the request inside screen
discovery. Screen discovery may contribute the
operation and DB-backed route, but it must not substitute a UI rule for the
requested customer-specific server-side rule.

If both a client-side validation and an Oracle/HADES customer extension exist,
preserve both as distinct origins and let the rule workflow classify the
requested one. Do not ask the user to spell out HADES flags, owners, EP names,
packages or source ranges that the factory is expected to discover.

For developer onboarding and day-to-day execution, use [developer-quickstart.md](references/developer-quickstart.md). For repeatable starts, use [prompt-template.md](references/prompt-template.md). For didactic PT-BR user guidance and ready-to-use prompts by reading/discovery scenario, use [read-prompt-examples.md](references/read-prompt-examples.md). For team handoff review, use [handoff-review-checklist.md](references/handoff-review-checklist.md). For database access provisioning, use [codex-oracle-access.md](references/codex-oracle-access.md). For authenticated browser-session capture, use [codex-browser-runtime-capture.md](references/codex-browser-runtime-capture.md) and [runtime-capture-form-template.md](references/runtime-capture-form-template.md). For Cronos XML source-of-truth decisions, use [cronos-source-of-truth-template.md](references/cronos-source-of-truth-template.md). For legacy documentation discovery, use [legacy-docs-discovery.md](references/legacy-docs-discovery.md). For component-to-API inventory, use [component-lineage-matrix-template.md](references/component-lineage-matrix-template.md). For read endpoint parity gates, use [read-parity-matrix-template.md](references/read-parity-matrix-template.md). For Java/API package-state parity, use [java-oracle-session-context.md](references/java-oracle-session-context.md). For API endpoint design, use [api-design-patterns.md](references/api-design-patterns.md), [lib-ui-fieldspec-api.md](references/lib-ui-fieldspec-api.md), and [java-api-implementation-playbook.md](references/java-api-implementation-playbook.md). For a filled read-first frequency API model, use [example-ergadm00189-api-contract.md](references/example-ergadm00189-api-contract.md). For architecture-level write patterns, use [archon-write-patterns.md](references/archon-write-patterns.md). For write behavior and write deferral, use [write-risk-template.md](references/write-risk-template.md), [write-risk-detail-template.sql](references/write-risk-detail-template.sql), and [write-api-handoff-template.md](references/write-api-handoff-template.md). For deciding whether a screen can move to API implementation, use [closure-checklist-template.md](references/closure-checklist-template.md).

## Platform Governance

Apply the root migration `AGENTS.md` while producing discovery artifacts. The
screen discovery phase must identify whether a finding belongs to the Ergon
host, `praxis-metadata-starter`, `praxis-config-starter`, `praxis-ui-angular`,
or another owner.

When discovery finds missing or weak support for `_links`, `/actions`,
`/surfaces`, `/capabilities`, `/schemas/filtered`, `x-ui`, option sources, or
Angular runtime behavior, do not prescribe an Ergon-local workaround as the
default. First classify the need as `ja-suportado-so-ux`,
`ja-suportado-mal-nomeado-ou-mal-materializado`,
`suportado-parcialmente`, or `lacuna-real-de-contrato`. Only real contract
gaps should become `Praxis Platform Follow-up`.

Keep HADES, SQL, `ROWID`, empresa, usuario, perfil, package names, and session
context as evidence for backend implementation, not public DTO/schema/URL/x-ui
contract.

## Operating Principle

Investigate in this order unless the user gives a stronger reason to change it:

1. Open the legacy screen and observe the actual user workflow.
2. Find the Archon XML/debug definition for the same screen.
3. Extract screen SQL, component names, bind tokens, links, filters, page size, hidden fields, and default values from browser/XML evidence.
4. Use the extracted SQL objects as the seed list for Oracle metadata discovery.
5. Expand Oracle lineage, security, grants, triggers, keys, and write risks only after the screen evidence is anchored.
6. Close write behavior as either API-ready or explicitly blocked/deferred with evidence before claiming read/API readiness.

Do not start from broad Oracle scans or name matching when browser/XML evidence is available. The screen XML and runtime SQL are the primary evidence for what the user-facing workflow actually uses.

## Standard Operation Inventory

Every Ergon/Archon screen discovery must produce or update `operation-inventory.md`. Start from the standard framework operations and then mark each one with one of the allowed states: `Implemented`, `Ready`, `Candidate`, `Blocked`, `Deferred`, or `Not present`.

- `Consultar/listar`: default load, visible filters, pagination, sorting, company/user scope, empty state.
- `Ler detalhe`: row selection, detail form/panel, nested grids, public key, internal locators.
- `Novo/Salvar`: create button, edit state, defaults, required fields, validation messages, `P_OPER`/routine/table route, success side effects.
- `Editar/Salvar`: editable fields, immutable keys, changed-field payload, validation messages, side effects.
- `Apagar`: delete/anulation button, confirmation text, permission and dependency blockers.
- `Duplicar`: copied/defaulted values, new key fields, whether it reuses create route.
- `Cancelar`: no-op behavior from create/edit/duplicate modes.
- `Documentos legais`: tab/block/component, read source, write route when editable, `PONTLEI` or equivalent link key.
- `Publicacoes/atos`, `Pendencias`, and other related framework blocks when visible in XML, browser, or table-rule side effects.

For each row, record: browser evidence, XML/component evidence, Oracle/source evidence, candidate endpoint, FieldSpec/platform mapping, current backend state, parity state, and exact next check. Do not collapse `Novo`, `Editar`, `Apagar`, `Duplicar`, and `Documentos legais` into a generic "writes pending" note.

Use this FieldSpec mapping baseline when filling `operation-inventory.md`:

- `Consultar/listar`: `POST /<resource>/filter` backed by `BaseResourceService.filterWithIncludeIds`.
- `Ler detalhe`: `GET /<resource>/{id}` backed by `BaseResourceService.findById`; `GET /by-ids` when the UI needs selected-row reloads.
- Lookups/options: `POST /options/filter`, `GET /options/by-ids`, `OptionDTO`, and `@UISchema(endpoint/filterField/sortField/optionsPageSize)`.
- `Novo/Salvar`: `POST /<resource>` backed by `save` only after write gates close; otherwise blocked/deferred.
- `Editar/Salvar`: `PUT /<resource>/{id}` backed by `update` only after update payload and side effects close.
- `Apagar`: `DELETE /<resource>/{id}` backed by `deleteById`; batch delete is a separate explicit decision.
- `Duplicar`: `POST /<resource>/{id}/duplicate-draft` through `DuplicateDraftResourceService.duplicateDraft`, then normal create on save.
- `Cancelar`: no backend mutation; prove UI state reset/no write.
- `Documentos legais`, `Publicacoes/atos`, and `Pendencias`: separate related resources/workflows unless runtime/XML proves they are fields of the main resource.

For Ergon screens that depend on `HADES.FLAG_PACK`, note that the FieldSpec endpoint shape stays standard while implementation must run context setup/cleanup on the same Oracle connection through the shared legacy bridge.

## New Platform Reuse Discovery

After the legacy operation inventory is anchored, search the target Java/OMS modules before creating new API candidates. Produce `platform-reuse-inventory.md` with one row per operation/resource and a decision: `reuse`, `extend`, `create`, `block`, `defer`, or `not-api`.

Inspect at minimum:

- endpoint/path constants and OpenAPI groups;
- controllers, resource services, DTOs, FilterDTOs, mappers, repositories, entities, and tests;
- resources already migrated for related screens or shared lookups/options;
- `docs/migracao/platform-option-sources.md` generated by `tools/migration-factory/export-platform-option-sources.ps1 -Force` when the workspace has that helper, plus `docs/migracao/options-lov-promotion-status.md`, before treating a LOV/option as new or blocked; record `generatedAt`, covered property files/modules, and promotion status source so a missing source is not inferred from stale or incomplete coverage;
- shared services for legacy context, authorization, legal documents, publications, pending flows, and FieldSpec schemas;
- semantic gaps between the existing new-platform resource and the legacy screen behavior.

If an existing resource matches the legacy operation, record the exact path/class and prefer reuse or extension. Do not propose a duplicate endpoint unless the incompatibility is explicit.
For LOV/options, record `PLATFORM_OPTION_SOURCE_RESOLVED` when sourceKey, dependencies, selected-value reload, and visible semantics match; `PLATFORM_OPTION_SOURCE_REVIEW_REQUIRED` when an existing source is close but semantically incomplete; and `PLATFORM_OPTION_SOURCE_BACKLOG_REQUIRED` only when no configured/promoted source fits and the target microservice/module was covered by the inventory. For dependent sources, selected-value reload must be proven separately from filtering: either the ID is self-contained for `GET .../by-ids`, or the contextual `POST .../by-ids` path is implemented and consumed with the required public dependencies. Treat review-required as an `extend` decision by default; use `block` only when the gap prevents the current screen contract.

## Phase Boundary

Use this as phases 1 and 1.5 of the migration:

1. `ergon-archon-screen-discovery` discovers and closes the screen boundary: browser workflow, XML/runtime SQL, Oracle lineage, keys, scope, authorization, read API candidates, and write risk/handoff.
2. It may produce a candidate read API contract, but `ergon-archon-read-api-migration` owns final read API design/implementation.
3. Write endpoints remain `Blocked` or `Deferred` unless write behavior is fully closed.
4. When write remains blocked/deferred, create `write-risk.md` and `write-api-handoff.md` so `ergon-archon-write-api-migration` can run after the read API phase.
5. Before leaving phase 1, close the screen's write surface: visible actions, XML/runtime action source, candidate routines/tables, payload evidence or explicit gap, key/ROWID strategy, session context, and blockers.
6. Before handing off to `ergon-archon-read-api-migration`, create `read-parity-matrix.md` from [read-parity-matrix-template.md](references/read-parity-matrix-template.md). Do not mark the read phase as closed if list/detail/options/related read endpoints lack explicit parity status and gaps.
7. Before handing off to read/write API skills, produce `platform-reuse-inventory.md` or mark reuse discovery blocked with exact missing repository/module access.
8. Use `ergon-table-rule-audit` only for table-level write-rule closure, normally after the read API phase and after target tables are known.

If the user asks for write implementation before these artifacts exist, keep the work in discovery mode and close the missing handoff evidence first.

## Discovery Gates

Before starting Phase 1, require an entry gate. `docs/migracao/<SCREEN>/migration-plan.md` and `phase-0-execution-gate.md` must exist, the target screen code must be explicit, and Fase 0 must recommend `ergon-archon-screen-discovery`. If these are missing, do not create a partial discovery package by hand; return to `ergon-migration-orchestration` and the canonical roadmap entry point.

At the start of discovery, record the evidence plan: browser/runtime availability, runtime XML/local XML/HADES source plan, `docs-legado` paths to search, Oracle access status, expected factory helpers, and whether the intended slice is quick discovery, full discovery, or API migration. Missing browser, Oracle, XML export, or docs access is not fatal by itself, but it must become an explicit `Blocked`, `Partial`, or `Unavailable` status in the gate and artifacts.

Before handing off to any API implementation skill, require an exit gate. The package must contain `phase-1-execution-gate.md`, `closure-checklist.md`, `component-lineage-matrix.md`, `operation-inventory.md`, `read-parity-matrix.md`, Oracle/HADES confirmation or blocked rerun artifacts, and a candidate `api-contract.md` when API migration is in scope. A gate may be `Ready for read API`, `Read handoff ready; write deferred`, `Ready for write API`, `Blocked`, or `Deferred`; it must not be implied by the presence of Markdown files alone.

Legacy documentation under `docs-legado` is primary evidence for business meaning, historical model context, related flows, and parity scenarios, but it is not implementation proof by itself. Promote a doc fact into API readiness only after it is tied to browser/runtime, XML/debug, local source, Oracle metadata, or an explicit accepted deferral.

## Legacy System Access

Default demo entry point:

- `http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm_mnu001.tp`

Use the authenticated browser surface that actually has the session. Prefer the Codex in-app browser when the user has it open or can log in interactively. Use Chrome when the user asks for Chrome, the authenticated session is already in Chrome, or the user's profile/extensions are needed. Use Playwright only as a fallback for repeatable screenshots or scripted smoke checks after the browser-session path is understood.

Legacy Archon pages can have unstable DOM locators. If DOM inspection hangs or returns unreliable results, use screenshots plus coordinate/CUA-style actions to operate the page, and record the limitation in `browser-runtime.md`. Do not downgrade confirmed visible behavior just because DOM automation is weak.

If credentials are provided in the conversation, use them only for the active private session, but do not write them into reports, SQL files, commits, logs, screenshots, command history artifacts, or generated files. If credentials need to be reused locally, prefer environment variables or a private password manager outside the repository.

After login:

1. Confirm the authenticated Home/Menu screen: visible user, visible company, current URL path, and current menu transaction.
2. Click or focus the search field labeled like `Buscar transacao`.
3. Search for the target page code first, for example `ERGadm00033`, `ERGadm00034`, or `ERGadm00189`. Search by visible title only if the code does not return a result.
4. Open the matched page from the search result instead of guessing the final URL.
5. Record the selected result text, navigation path, visible title, module/breadcrumb, and final URL path.
6. Exercise the visible workflow: default load, company selector, search/filter fields, tabs, links, action buttons, pagination, and detail navigation.
7. Capture observed parameters and changed SQL behavior after each interaction.

If the search does not find the transaction, try the visible menu/area path and record each clicked label. If neither search nor menu opens the screen, mark navigation as `Blocked - screen not reachable for current user`.

If login or browser access is unavailable, continue from local XML/source and mark `Observed` as `Missing` or `Partial` in the gates.

## Runtime XML Export Gate

For Cronos/Archon `.tp` transactions, always try the matching `.xml` runtime export before treating local XML as final:

```text
/<Application>/<Module>/<Transaction>.xml
```

Example: `http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm00034.xml`.

This route is handled by Cronos export code, requires an authenticated user with layout-export permission (`privilegiado` or `alteraLayout`), retrieves the runtime descriptor, and serializes it through `TransactionXmlWriter`. It is not merely a static file read.

If `tools/migration-factory/download-runtime-xml.ps1` exists in the repository, run it before any manual extraction from the browser viewer. It is the preferred path because it saves the raw response only after XML parser validation and writes sanitized evidence. Pass credentials only through a pre-created `PSCredential` or pre-existing env vars; do not put secrets in the command.

Required behavior:

1. Use credentials only for the active private session; never write them to artifacts, logs, SQL, commits, screenshots, command history, or prompt templates.
2. Open the `.tp` route to prove the runtime screen is reachable for the current user.
3. Download the `.xml` route for the same application/module/transaction. If browser JavaScript cannot read `HttpOnly` cookies or lacks `fetch`/`XMLHttpRequest`, do not stop there: when the login page exposes a form, parse the actual `<form action>` and resolve it against the response URL. Example: `action="/login"` under `/Ergon/Administracao/<SCREEN>.tp` resolves to `http://host/login`, not `/Ergon/login`. Use an in-memory HTTP session/cookie container to request `.tp`, submit the resolved login action with the observed form fields, then request `.xml`. Keep credentials and cookies only in memory.
4. Save the exported XML under `docs/migracao/<SCREEN>/runtime/<SCREEN>.authenticated.xml` or `docs/migracao/<SCREEN>/runtime-exported-xml/<SCREEN>.xml` only when it contains no credentials or sensitive runtime data beyond screen metadata and the saved file parses as XML.
5. Record URL, HTTP status, redirect/login status, content type, byte size, SHA-256 hash, parser result, timestamp, and non-sensitive user/session context.
6. Compare exported XML against local product XML under `docs-legado/**/crodata/trans/<Module>/<Transaction>.xml`.
7. Produce or update `cronos-source-of-truth.md` with one of: `RUNTIME_EXPORTED_XML_MATCH`, `RUNTIME_EXPORTED_XML_DIVERGED_FROM_LOCAL`, `RUNTIME_XML_EXPORT_FORBIDDEN`, `RUNTIME_XML_EXPORT_AUTH_BLOCKED`, `RUNTIME_XML_EXPORT_NOT_FOUND`, or `LOCAL_XML_ONLY_UNCONFIRMED`. This artifact is mandatory whenever a runtime XML, local XML, HADES/stored XML, or XML-export residual exists. If HADES/Oracle is unavailable, still create the file and mark the source-of-truth decision `Blocked` or `Partial`; do not leave the decision only inside `investigation.md`.

Never use `document.documentElement.outerHTML` from Chromium's XML viewer as the raw XML export; it can capture the viewer page instead of the original resource. If the raw XML cannot be saved, record the exact attempted methods and residual such as `XML_RAW_EXPORT_NOT_SAVED`.

Do not treat copied/rendered text from Chromium's XML viewer as raw XML unless an XML parser accepts the saved file. The viewer can display escaped XML attribute content as literal markup, producing invalid XML such as attributes containing raw `<div ...>`. If parsing fails, classify the file as `RUNTIME_XML_BROWSER_TEXT_INVALID`; use it only as diagnostic evidence and continue from parser-valid local XML, raw HTTP export, or HADES/Cronos source.

Never place credential literals in shell commands, generated scripts, report snippets, or command transcripts. Prefer a local secrets/env file, environment variables, or an already-authenticated browser session. If no safe non-recording credential path exists, ask the user for one before running an HTTP login from the shell.

When credentials exist only in the active conversation/session, prefer logging in through the authenticated browser surface over embedding credentials in shell. If browser automation cannot safely submit the login, ask the user to log in manually and continue from that session. Even without submitting credentials, parse and record sanitized login mechanics from the login HTML: resolved form action, method, field names, HTTP status, and issued cookie names only.

Use exported runtime XML as the primary structural source when it exists and diverges from local XML. Still capture browser/runtime evidence for SQL behavior, binds, permissions, action availability, write payloads, and dynamic controller behavior; exported XML alone does not close API parity.

## Cronos Bind And Scope Resolution

For Cronos/Archon screens, do not treat Chrome/browser automation as the only
way to close bind semantics. When the open question is bind order, lookup source,
special selector values, or company/session scope, first combine parser-valid XML
and Oracle metadata:

1. Read `sqlParameters` and bind order from the runtime XML or from the accepted
   source in `cronos-source-of-truth.md`.
2. Read the SQL predicate where the bind is applied, for example `VALOR = ?`.
3. Locate the reused component definition or an equivalent screen component that
   defines the same control.
4. Resolve the combo/searchbox source through Oracle metadata, view text,
   dependencies, synonyms, or package/function source.
5. Save the read-only Oracle output under `docs/migracao/<SCREEN>/oracle-results/`.
6. Classify the bind as public filter, server-side scope, constant bind,
   parent-row context, or internal runtime parameter.

Example pattern already proven in `ERGadm00034`: `component/HADadm_blk003`
exposes `drpSelecEmpresa`; equivalent screens define it with
`select valor, descr from SELEC_COMBO_EMPRESA_VW order by valor`; Oracle view
text confirms `-1` = all companies, `-2` = no company, and
`flag_pack.get_empresa` = current company. That means `VALOR` is internal
company/query-mode scope, not a public `FilterDTO`, schema, URL, `OptionDTO.extra`,
or x-ui field when a functional key exists.

### Public Identity Must Follow The Effective Legacy Query

Never infer a composite or opaque public id merely because a legacy view
contains duplicate domain keys. First distinguish view fan-out from entity
identity:

1. prove the base-table PK/UK and its projection through the view;
2. reconstruct the exact list/detail query used by the component;
3. apply server-side scope/session binds under the same Oracle connection;
4. test key uniqueness in that effective resource slice;
5. confirm how child components and legacy operations identify the selected row.

The unscoped view count is diagnostic only. If the domain key is unique in the
effective slice, expose that key and keep company, user, HADES state, `VALOR`,
`ROWID`, and equivalent locators internal. If duplicates remain, determine
whether they are projections of the same entity or genuinely distinct public
resources before considering normalization, a composite key, or an opaque id.
Record `candidate_public_key_unique_in_effective_scope` when the effective probe
proves one selected-row match and key uniqueness. Record
`blocked_effective_scope_key_uniqueness_not_proven` when that probe has not run
or its same-connection scope is not reproducible; do not convert uncertainty
into an opaque-token design.

Use `docs/migracao/phase1-cronos-bind-resolution-standard.md` when present. If
XML plus Oracle metadata closes the semantics and no browser evidence
contradicts it, record `BIND_SEMANTICS_CLOSED_BY_XML_ORACLE` or equivalent in
the gate instead of blocking only because Chrome/browser automation is
unavailable. Browser/runtime evidence is still required for visible workflow,
action availability, messages, write payloads, restricted-user behavior, and
final legacy/API parity.

## Cronos RecordPanel Write Payload Resolution

For standard Cronos/Archon write panels, do not make browser navigation the first
or only path to close create/update payloads. If XML shows
`component/recordPanelEdit` with `dataTable` and without `rotina`,
`insertMethod`, `updateMethod`, or `deleteMethod`, resolve the payload from
parser-valid XML plus the local Cronos framework source before asking the
developer to operate the browser.

Required source-derived check:

1. Locate the `recordPanelEdit` component and its `dataTable`.
2. Extract sibling/child `component/editField/*` controls in layout order:
   `field`, `fieldTarget`, `caption`, `dataType`, `required`, `validators`,
   `initialValue`, `valueProperty`, `displayProperty`, and lookup SQL/options.
3. Confirm in Cronos source that `RecordPanelEditImpl` dispatches `dataTable` to
   `createManagerDescription()`.
4. Confirm `ManagerDescriptionParameters` uses `_op` for operation, `_p_` for
   proposed values, `_o_` for original values, and `_q_p_` for query/reload
   values.
5. Confirm `ManagerTableParametersImpl` and `AbstractTableDescription` generate
   table `INSERT`, `UPDATE ... WHERE PK`, and `DELETE ... WHERE PK`.
6. Confirm `ManagerDescriptionImpl` executes the generated Oracle SQL on the
   application connection and reloads rows by internal rowid/query description.

When `tools/migration-factory/new-cronos-recordpanel-write-payload.ps1` exists,
run it with `-Strict` and save the generated Markdown/JSON under
`docs/migracao/<SCREEN>/factory/`. A passing result may close create/update
payload discovery as `SOURCE_DERIVED_PAYLOAD_READY_FOR_DB_PROBE`.

This source-derived payload replaces browser payload capture for the standard
`recordPanelEdit + dataTable` pattern. Browser remains useful for visible
success/error messages, action availability, duplicate defaults, permissions,
cancel/no-op behavior, and final UI parity, but it should not block payload
closure when XML + Cronos source already prove the route.

## Assisted Codex Browser Session

When the in-app browser is available, ask the developer to log in once if needed, then operate from the authenticated page. For direct URLs such as:

```text
http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm00189.tp
```

record the page as `Browser access status: Partial` as soon as the authenticated screen is visible, even before every workflow is exercised. Then complete the observation by clicking through the visible UI:

- Confirm final URL, title, module, and whether the menu/search path also finds the page.
- Inspect frames, popups, debug panels, XML/debug buttons, network/runtime SQL panels, and hidden fields exposed by the legacy UI.
- Prefer direct browser observation for dynamic behavior that automation often misses: enabled/disabled actions, popup navigation, row selection, tab lazy loading, validation messages, and session-specific authorization.
- Save only concise evidence. Do not dump full page HTML, screenshots with sensitive data, or credential-bearing logs into the migration package.
- If Codex cannot programmatically inspect the in-app browser in the current environment, have the developer keep the page open and use browser-visible facts they provide as `CONFIRMED_RUNTIME_MANUAL`; do not upgrade SQL/bind behavior to `CONFIRMED_RUNTIME` until Codex or a captured debug artifact verifies it.

Create or update `docs/migracao/<SCREEN>/browser-runtime.md` using [codex-browser-runtime-capture.md](references/codex-browser-runtime-capture.md). Also create `runtime-capture-form.md` from [runtime-capture-form-template.md](references/runtime-capture-form-template.md) when Codex cannot inspect the browser DOM directly and the developer must relay visible/debug facts. `browser-runtime.md` is the working runtime notebook; summarize only stable findings back into `investigation.md`.

For Phase 1 validation before developer handoff, `runtime-capture-form.md` is not a substitute for executed runtime evidence. If default load, runtime bind values, page size, selected-row/public-key proof, visible action state, or representative non-empty fixture/context are missing, close Phase 1 as `Blocked`; do not mark it `Ready for next phase` or `Ready for next phase with adjustments`.

When the workspace provides `docs/migracao/phase1-scope-authorization-standard.md`, use it as the Phase 1 scope/authorization contract. The factory workbook should record `phase1-scope-authorization-v2-bridge` when the screen is an API-only Ergon/HADES bridge. `allowed-default-context` can close only with authenticated browser default load, non-empty fixture, selected row, public-key correlation, and same-connection Ergon/HADES Oracle context. For API-only screens governed by `ergon-hades-security-starter` and `ergon-legacy-bridge`, `company-scoped-context` and `restricted-user-context` close by the shared bridge/security contract and must not block each screen individually. Reopen them as blocking only when the screen bypasses `HadesLegacyAccessGuard`/equivalent, bypasses `ErgonLegacyExecutor`/equivalent, exposes company/user/profile/security context publicly, or implements custom security outside HADES. When the factory provides `new-phase1-scope-authorization-decision-pack.ps1`, generate its Markdown/JSON pack only for genuinely open scope cases; the pack requests owner decisions but does not close Phase 1 by itself. Do not turn company, user, profile, permission, or session binds into public FilterDTO/schema/URL/option/x-ui fields.

## Workflow

1. Identify the target screen code, URL, title, module, and user-visible workflow.
2. Open the default legacy entry point when no direct URL is known, log in using credentials provided by the user for the active session, and locate the screen through the page/menu search field.
3. Run the Runtime XML Export Gate for the matching `.xml` route. If export succeeds, compare it with local product XML and use the runtime export as the primary structural source when it diverges. If export is blocked, record the blocker and continue with lower confidence.
4. Inspect the running screen with the Codex in-app browser when available, or Chrome when the user's Chrome profile is required. Capture visible grids, tabs, actions, links to related screens, debug tree nodes, XML/debug `sqlSelect`, `sqlParameters`, page size, filters, hidden fields, and observed bind values. If browser inspection is unavailable, continue from local XML/source and mark browser evidence as missing or manual-only.
5. Inspect local legacy artifacts when present, especially `docs-legado/**/<SCREEN>.xml`, view scripts, Java services, DTOs, and resource classes. Treat XML `sqlSelect`, `sqlParameters`, component ids, links, and filter bindings as an initial source for Oracle seed objects only after classifying runtime export availability.
6. Inspect the legacy architecture/documentation tree when `docs-legado/v7x` is available using [legacy-docs-discovery.md](references/legacy-docs-discovery.md). This tree has known evidence layers: Archon XML/controllers under `java`, local DDL/source under `aps`, Enterprise Architect exports under `EA`, RoboHelp model/reference archives under `help`, functional/technical specs under `docs/Interno`, workflow assets under `workflow`, and older Forms/Reports assets under `forms` and `reports`. Use these sources for business meaning, candidate parity cases, model context, and related-flow discovery; do not let documentation override browser/XML/Oracle evidence.
7. Build a narrow seed list from browser/XML SQL before querying Oracle. Include screen views, lookup views, linked-screen views, packages/functions referenced by SQL, and objects introduced by related flows.
8. Query Oracle metadata using [oracle-queries.md](references/oracle-queries.md). Treat `ERGON` and `HADES` as defaults, not universal owners. Resolve synonyms, expand views recursively, inspect columns, constraints, indexes, triggers, grants, package arguments, source references, updatable columns, and write risks.
9. Classify every object by role and confidence. Do not promote structural matches to confirmed objects without evidence.
10. If screen SQL, views, helpers, triggers, or packages depend on Oracle package state such as `HADES.FLAG_PACK`, document the Java same-connection context strategy using [java-oracle-session-context.md](references/java-oracle-session-context.md). Do this before marking any Java/API contract as ready.
11. Produce or update read-only Oracle confirmation SQL from [oracle-confirmation-template.md](references/oracle-confirmation-template.md) when Oracle access is available or when follow-up confirmation is needed. When the repository has `tools/migration-factory/new-phase1-oracle-sql.ps1` and `factory/extraction.json` exists, use that generator before writing any manual Oracle/HADES SQL. It standardizes `oracle-confirmation.sql` and `hades-registry.sql` from XML seeds, preserves owner/package/subprogram identity, avoids known dictionary mistakes such as `ALL_PROCEDURES.STATUS`, expands view/physical lineage, reports owner collisions, covers HADES registry/access/menu/stored-resource candidates, and adds minimal non-empty smoke probes for read/view seeds. Manual SQL is allowed only as a supplemental artifact with the exact reason recorded in the gate. A Phase 1 package must include both object confirmation coverage and HADES registry coverage, either in `oracle-confirmation.sql` plus `hades-registry.sql`, or in one clearly sectioned SQL file. Use the executed outputs to fill the component-to-API matrix and candidate API contract facts: DTO fields, FilterDTOs, options, keys, scope, authorization, session context, related resources, and blocked/deferred writes. If execution fails, save a sanitized blocked note under `oracle-results/` and keep all Oracle/HADES findings below `CONFIRMED_ORACLE_METADATA`. Before closing the gate, scan every referenced Oracle/tool output for `ORA-`, `SP2-`, `TNS-`, `ERROR:`, `Exception`, and `IllegalArgumentException`; a corrected supplemental SQL may supersede a failed statement only when the gate explicitly records the failed output and the replacement evidence.
12. Create or update `read-parity-matrix.md` from [read-parity-matrix-template.md](references/read-parity-matrix-template.md). For every read endpoint candidate, record the legacy component, Oracle source, Java/API source if it exists, key strategy, filters/binds, paging/sort, options behavior, HTTP/API execution status, and the exact remaining gap. A read API can be "implemented" and still not be "parity closed".
13. When the XML/browser shows create, edit, delete, duplicate, pending, publication, legal-document behavior, or `recordPanelEdit` with a `db:*` routine, read [archon-write-patterns.md](references/archon-write-patterns.md), then create `write-risk.md` from [write-risk-template.md](references/write-risk-template.md) and a focused `write-risk-detail.sql` from [write-risk-detail-template.sql](references/write-risk-detail-template.sql). Use exact routines/tables/triggers from XML/runtime evidence; avoid broad table-name source searches. If the screen is closed as `Ready for read API` or receives a read-first implementation while write remains blocked/deferred, create `write-api-handoff.md` from [write-api-handoff-template.md](references/write-api-handoff-template.md).
14. Before starting Phase 3 write design, close write payloads for every visible write action in scope. For standard Cronos `recordPanelEdit + dataTable`, prefer the source-derived XML + Cronos framework path above and then require a controlled DB probe. For rotina/object-method/custom actions, or when XML/source does not prove the route, capture runtime write payloads for `Novo`, `Editar`, `Apagar`, `Duplicar`, `Salvar`, `Cancelar`, legal-document actions, publication actions, pending actions, and any screen-specific business action. Record UI state before/after click, confirmation dialogs, hidden keys such as `ROWID_REG`, operation selector values, selected public id, `P_MENS`, routine arguments, legal-document/publication/pending fields, changed debug/network request, and observed validation messages. If neither source-derived payload nor runtime payload can be captured, mark the operation `Blocked` or `Deferred` with the exact next XML/source/browser/debug step; do not leave `operation-inventory.md` with a generic `Unknown` backend state and do not infer payloads from PL/SQL signatures alone.
15. Use gates before finalizing: `Observed`, `Resolved`, `Expanded`, `Read-parity planned/executed`, `Write-risk checked`, `False-positive checked`, `Confirmation SQL complete`, `Session-context checked`, and, for Java work, `API-ready`.
16. Produce the investigation report using [investigation-template.md](references/investigation-template.md).
17. If the user is planning Java migration, read [api-design-patterns.md](references/api-design-patterns.md), [lib-ui-fieldspec-api.md](references/lib-ui-fieldspec-api.md), and [java-api-implementation-playbook.md](references/java-api-implementation-playbook.md), then produce the API contract using [api-migration-template.md](references/api-migration-template.md). Keep endpoints as `Candidate`, `Blocked`, or `Deferred` until keys, scope, authorization, session context, runtime binds, FieldSpec contract, read parity plan, and write boundaries are closed.
18. Load [example-ergadm00033-findings.md](references/example-ergadm00033-findings.md) only when the target is ERGadm00033/ERGadm00034 or when the user explicitly asks for that example.
19. Load [example-ergadm00189-findings.md](references/example-ergadm00189-findings.md) only when the target is ERGadm00189 or when the user explicitly asks for that example. Load [example-ergadm00189-api-contract.md](references/example-ergadm00189-api-contract.md) when drafting or validating a read-first frequency API contract.
20. Load [case-review-ergadm00189.md](references/case-review-ergadm00189.md) when improving the skill process or when investigating a similar read/write frequency screen.

## Browser Capture Checklist

Capture enough runtime evidence to explain what the user sees and how the SQL changes:

- Login entry point, navigation path, final URL, screen title, and module.
- Search terms used in the menu/page search field and the selected result.
- Initial grid SQL, page size, default order, visible columns, hidden key fields, and default bind values.
- Company selector or scope selector values, including special values such as `-1` and `-2` when present.
- Filter behavior for each visible search field, including empty/null/default behavior.
- Tabs and nested grids loaded only after user interaction.
- Links to related screens and the exact parameters passed in the URL or runtime state.
- Action buttons, edit/delete/detail flows, confirmation dialogs, and whether the screen appears read-only.
- Runtime/debug SQL snippets, `sqlSelect`, `sqlParameters`, component ids, and observed bind values.

Prefer concise evidence snippets. Do not paste huge XML/debug dumps into the final report.

## XML And SQL First

Before deep Oracle investigation, extract from the screen XML/debug:

- Component id and user-visible area.
- `sqlSelect` and `sqlParameters`.
- Bind token order and default/null behavior.
- Lookup/combo SQLs.
- Linked screen URLs and parameter names.
- `ROWID`, hidden ids, composite keys, generated columns, and any edit/delete a

…(truncated)
