Primeiro Commit v0.beta1

portable-setup.md

@@ -0,0 +1,106 @@
+# Portable Setup
+
+Use this flow when moving the skill to another computer.
+
+## What to copy
+
+- Copy the full `knowledge-one-view-cli` skill folder into the target Codex `skills` directory.
+
+## What does not matter
+
+- The workspace name does not need to be `fusion`.
+- The workspace may be empty.
+
+## First run on the new computer
+
+When Codex invokes the skill from the agent workspace, no extra path flag is needed.
+
+Browser helper note:
+
+- `scripts/refresh-auth-state.mjs` now tries browser automation in this order:
+  - local module resolution for `playwright` or `playwright-core`
+  - shared runtime at `~/.codex/skills/playwright`
+  - bundled Codex runtimes such as `~/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules`
+- In a normal Codex desktop installation, this means the browser helper should usually work on a new machine even if `~/.codex/skills/playwright` was not copied over.
+- If you use the skill outside Codex and none of those runtimes exist, install a shared Playwright runtime under `~/.codex/skills/playwright`.
+
+If you want to test manually from outside the workspace, point `--runtime-home` back to the target workspace runtime:
+
+```powershell
+node /path/to/.codex/skills/knowledge-one-view-cli/scripts/refresh-auth-direct.mjs `
+  --runtime-home ./knowledge-one-view-cli/runtime `
+  --username <user-email>
+```
+
+This creates the runtime state inside the workspace-side skill folder:
+
+- `knowledge-one-view-cli/runtime/auth-state.json`
+- `knowledge-one-view-cli/runtime/session-meta.json`
+- `knowledge-one-view-cli/runtime/chrome-profile/`
+
+## Bootstrap rule
+
+The first test run in a new workspace must bootstrap the full workspace-side tree, even if the workspace starts empty.
+
+Expected workspace-side structure:
+
+- `knowledge-one-view-cli/output/`
+- `knowledge-one-view-cli/tmp/` (todos os temporarios e intermediarios diretamente aqui, sem subpastas obrigatorias)
+- `knowledge-one-view-cli/runtime/`
+- `knowledge-one-view-cli/runtime/chrome-profile/`
+
+Notes:
+
+- permanent test definitions stay in the installed skill under `.../knowledge-one-view-cli/tests/`
+- run outputs, diffs, temporary inputs, rendered SQL and runtime state stay in the workspace-side `knowledge-one-view-cli/` folder
+- the bootstrap runner also writes the first run bundle under `output/`
+
+Example bootstrap test run:
+
+```powershell
+node /path/to/.codex/skills/knowledge-one-view-cli/tests/run-systemic-suite.mjs `
+  --bootstrap-only `
+  --workspace-root .
+```
+
+If you launch the command from inside the workspace-side `knowledge-one-view-cli/` folder instead of the workspace root, the skill now normalizes that location back to the real workspace root automatically, so it will not create `knowledge-one-view-cli/knowledge-one-view-cli/...`.
+
+Recommended post-migration smoke:
+
+```powershell
+node /path/to/.codex/skills/knowledge-one-view-cli/tests/run-post-migration-smoke.mjs `
+  --workspace-root .
+```
+
+This smoke runner does the standard migration validation flow:
+
+- bootstraps the workspace-side tree
+- validates the Oracle session with `--check-auth`
+- runs a real Brazil workload sample for `current-quarter`
+- writes the sample JSON into `knowledge-one-view-cli/output/post-migration-workload-sample.json`
+- writes the run bundle into `knowledge-one-view-cli/output/test-runs/<run-id>/`
+
+## Daily use
+
+```powershell
+node /path/to/.codex/skills/knowledge-one-view-cli/scripts/fetch-sales-intelligence.mjs `
+  --runtime-home ./knowledge-one-view-cli/runtime `
+  --intent opportunities-default `
+  --limit 200
+```
+
+When running directly from the workspace-side `knowledge-one-view-cli/` folder, the default path inference now keeps outputs in `./output/`, `./tmp/` and `./runtime/` under that folder instead of creating a second nested `knowledge-one-view-cli/`.
+
+## Optional development helper
+
+If direct auth is blocked or you need to refresh workbook/browser tracing, use:
+
+```powershell
+node /path/to/.codex/skills/knowledge-one-view-cli/scripts/refresh-auth-state.mjs `
+  --runtime-home ./knowledge-one-view-cli/runtime
+```
+
+## Related references
+
+- `docs/docs.html`
+- `references/script-catalog.md`