Update to Ansight

{
  "name": "ansight-annotate-session",
  "description": "Add, update, verify, or remove timeline and UI-anchored annotations on one Ansight session. Use for requested review metadata, screenshot geometry, or visual-tree target binding; do not use merely to read annotations, investigate evidence, or operate the live app.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 288
    }
  ],
  "skill_md_contents": "---\nname: ansight-annotate-session\ndescription: Add, update, verify, or remove timeline and UI-anchored annotations on one Ansight session. Use for requested review metadata, screenshot geometry, or visual-tree target binding; do not use merely to read annotations, investigate evidence, or operate the live app.\n---\n\n## OpenAI plugin integration\n\nRun Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.\n\nUse these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:\n\n- https://www.ansight.ai/skills/ansight-install.md → [ansight-install](../ansight-install/SKILL.md)\n- https://www.ansight.ai/skills/ansight-cli-setup.md → [ansight-cli-setup](../ansight-cli-setup/SKILL.md)\n\n\n# Annotate An Ansight Session\n\nAttach concise review metadata to one exact session. Keep the observed fact in the label, supporting context in notes, and inference explicitly qualified.\n\n## Prerequisites And Routing\n\nCLI annotation requires the Ansight CLI and a session available from local history or an imported archive. The app does not need to remain installed or connected, and its SDK does not need to be present, when annotating retained evidence.\n\n- A UI-anchored annotation also requires a captured screenshot frame; a semantic target requires a corresponding persisted visual-tree snapshot.\n- Direct diagnostic annotation tools such as `ansight_inject_annotation` require an available diagnostic tool connection and a resolvable session. A live-only tool path also requires an initialized SDK session.\n- If new live evidence must first be captured, use the Ansight Operate Live App skill; if the app lacks the SDK integration, follow `https://www.ansight.ai/skills/ansight-install.md`.\n- If the CLI cannot access the session, follow `https://www.ansight.ai/skills/ansight-cli-setup.md`.\n\nDo not install or reconnect the SDK solely to add metadata to an existing recorded or imported session.\n\nAnnotation writes change retained session metadata. Resolve the session and read existing annotations before creating or replacing one:\n\n```sh\nansight session show <session-id> --json\nansight session annotations <session-id> --json\n```\n\nUse a stable, meaningful annotation ID when the note may be updated. A CLI upsert with an existing ID replaces the stored annotation, so preserve any geometry, target, evidence, custom data, and capture metadata that should remain.\n\n## Add A Timeline Annotation With The CLI\n\nUse CLI fields for a point-in-time or range annotation:\n\n```sh\nansight session annotation upsert <session-id> \\\n  --annotation-id <stable-id> \\\n  --label <label> \\\n  --notes <notes> \\\n  --source agent \\\n  --start <utc> \\\n  --end <utc> \\\n  --json\n```\n\nOmit `--end` for an instantaneous marker. Use ISO-8601 UTC timestamps taken from session evidence. Do not manufacture precision beyond the evidence that established the moment.\n\n## Ground A UI Annotation\n\nA UI annotation is still time-based, but also anchors geometry to a captured screenshot frame. Establish the frame before writing:\n\n```sh\nansight session images <session-id> --json\nansight session screenshot export <session-id> --frame-id <frame-id> --output <path>\nansight session trees <session-id> --json\n```\n\nChoose the frame that displays the observed issue. If the annotation targets a semantic element, choose a visual-tree snapshot whose `screenshotFrameId` matches that frame or whose timestamp clearly corresponds to it. Preserve the snapshot ID, automation ID, element metadata, and bounds returned by that tree.\n\nGeometry coordinates are normalized to the captured frame:\n\n- `x = left / frameWidth`\n- `y = top / frameHeight`\n- `width = regionWidth / frameWidth`\n- `height = regionHeight / frameHeight`\n\nClamp values to `0.0` through `1.0` and verify the region stays inside the frame. Do not estimate geometry without inspecting the exported frame or trustworthy visual-tree bounds.\n\n## Write A UI Annotation From A CLI JSON File\n\nCreate a complete annotation JSON file and pass it to the CLI:\n\n```json\n{\n  \"annotationId\": \"checkout-submit-disabled\",\n  \"startUtc\": \"2026-08-28T03:14:15Z\",\n  \"label\": \"Submit button remained disabled\",\n  \"source\": \"agent\",\n  \"notes\": \"Observed after the address request completed.\",\n  \"geometry\": [\n    {\n      \"geometryId\": \"checkout-submit-disabled-rect\",\n      \"frameId\": \"<frame-id>\",\n      \"capturedAtUtc\": \"2026-08-28T03:14:15Z\",\n      \"kind\": 1,\n      \"x\": 0.62,\n      \"y\": 0.71,\n      \"width\": 0.25,\n      \"height\": 0.08,\n      \"text\": \"Disabled submit control\",\n      \"strokeColor\": \"#FF3B30\",\n      \"strokeWidth\": 2\n    }\n  ],\n  \"target\": {\n    \"kind\": \"visualTreeElement\",\n    \"source\": \"agent\",\n    \"targetId\": \"<target-id>\",\n    \"visualTreeSnapshotId\": \"<snapshot-id>\",\n    \"type\": \"Button\",\n    \"elementKind\": \"button\",\n    \"label\": \"Submit\",\n    \"automationId\": \"CheckoutSubmit\",\n    \"normalizedBounds\": {\n      \"x\": 0.62,\n      \"y\": 0.71,\n      \"width\": 0.25,\n      \"height\": 0.08\n    }\n  }\n}\n```\n\nThen upsert and verify:\n\n```sh\nansight session annotation upsert <session-id> --file <annotation.json> --json\nansight session annotations <session-id> --json\n```\n\nThe CLI file contract uses `geometry`, singular. Its geometry enum is numeric: point `0`, rectangle `1`, ellipse `2`, free draw `3`, line `4`, and arrow `5`. Each geometry requires a unique `geometryId`, exact `frameId`, `capturedAtUtc`, `kind`, `x`, and `y`; rectangles and ellipses also need width and height, while free-draw, line, and arrow shapes need normalized points appropriate to the shape.\n\nA target is optional. Include it only when it was derived from an actual visual-tree snapshot. Geometry identifies what region to draw, while the target records semantic element context.\n\n## Use Diagnostic Annotation Tools Without Mixing Schemas\n\nWhen the client exposes `ansight_inject_annotation`, use that tool directly for creation. It accepts `geometries`, plural, and string kinds `point`, `rectangle`, `ellipse`, or `freeDraw`. It can resolve by `sessionId` or an unambiguous `appId` and can default `startUtc` to the session's latest timestamp.\n\nUse `ansight_update_annotation` for a partial update when available. It supports source guards and explicit clear operations, avoiding accidental loss of fields. Use `ansight_delete_annotation` only for an authorized removal.\n\nDo not copy a diagnostic-tool `geometries` payload into the CLI `--file` contract, and do not send CLI numeric kinds to the diagnostic tools.\n\n## Preserve Existing Annotations During CLI Updates\n\nBefore updating an existing ID through the CLI:\n\n1. Read the annotation with `session annotations`.\n2. Copy the full existing object into a working JSON file.\n3. Change only the intended fields.\n4. Upsert with `--file`.\n5. Read it back and compare the ID, timestamps, geometry frame IDs, target snapshot ID, and source.\n\nDo not update a UI annotation with only `--label` and `--start`; that replacement would omit its existing geometry and target.\n\n## Verify Or Remove\n\nVerification should confirm that the stored annotation belongs to the intended session and that its time and frame fall within the capture. Export the referenced screenshot again when spatial placement matters.\n\nDelete through the CLI only when explicitly requested:\n\n```sh\nansight session annotation delete <session-id> <annotation-id> --json\n```\n\nReport the session ID, annotation ID, source, time range, frame and snapshot IDs, geometry kind and normalized bounds, verification performed, and whether an existing annotation was replaced or removed.\n"
}