# Do not send a visual alone; carry its marks, explanation and source relation together when they exist

> A lineage graph does not leave a visible UI piece as a standalone screenshot. The image, any marks that actually appear on it and their meaning, the…

Canonical: https://optionos.app/guide/en/lineage-graphs
Published: 2026-07-13
Source: optionos-product:r19

A lineage graph does not leave a visible UI piece as a standalone screenshot. The image, any marks that actually appear on it and their meaning, the component/source-map trace and the spoken intent all have to be read together.

That is why every card here carries **visual evidence**, **an explanation** and **flow text between cards**. When the visual contains real marks, their explanation stays in the same card; when it does not, no numbered legend is generated. The text between cards matters as much as the image, because it answers “why is this example here, and how does it lead to the next one?”

The core goal is to mark the output instead of describing the code. The human speaks over the UI and marks what they see; the agent uses that marked surface to find the component, the source file and the change to make. Work shifts from “which code should I edit?” to “which observed outcome do we want?”

The first closed set was built for a What's New entry. The important lesson is that the smallest shared unit is not the image. The largest safe shared unit is the image-card lineage: the image and caption always travel together, while a legend travels only when it maps to marks that are actually visible in the image.

![Closed lineage set for a What's New entry](https://optionos.app/guide/lineage-graph-closed-set.png)
*The What's New image-card lineage defines the largest safe component to share instead of sharing only a bare image.*
Interactive scene: https://optionos.app/guide/en/lineage-graphs#lineage-graph-closed-set

The practical result is simple: if the Guide needs the 15-index Cockpit card from What's New, it must not link only the PNG. It calls the source entry's feature-block and image-card. Caption and the 1–15 index explanations are not written twice, but they still appear in the Guide.

The same pattern works inside documents. When a screenshot is placed into a document, the source-map or component row around it is part of the lineage too. The agent does not only see an image; it sees which component/source hint was selected in that image.

![A lineage example with source map and capture actions marked in a document](https://optionos.app/guide/lineage-doc-source-map.png)
*When lineage is visible in the document, the agent reads the marked UI piece and the source-map hint in the same context.*
1. Full captured image — the evidence packet used in the conversation
2. Selected component/source-map area — the ownership hint on the code side

In this example the document acts as a fast explanation surface. The user drops in the image, draws indexes and says what they are looking at. Because the source-map is visible under the image, the agent answers “which file/component owns this UI piece?” from evidence, not from a guess.

The next example narrows the same operation. The whole screen is no longer the point; the selected node/component row is the point. Most development decisions shrink this way: broad image, selected component, source path.

![A lineage graph example with a selected component row](https://optionos.app/guide/lineage-doc-selected-node.png)
*The selected row makes it visible which component is being discussed and which source file is likely to change.*
1. Component row — the source-map counterpart of the UI piece being discussed
2. Capture list — where the same evidence is kept in conversation and file context

These two document examples show that lineage is not decoration. It is a work protocol that makes node and edge relations visible: visible surface → selected component → source map → spoken intent → agent action.

The value of that protocol becomes clearer in the full working layout. The product surface, VS Code Cockpit panel, agent terminals, terminal content and Source Control stay visible at the same time. The user does not open the code and explain it; they move between outputs and speak.

![Working layout with optionOS, VS Code Cockpit, agents, terminal and Source Control](https://optionos.app/guide/lineage-working-layout.png)
*Keeping the product surface, Cockpit panel, agents, terminal and source view together makes fast voice-driven development possible.*
1. Product surface or component being worked on
2. The Cockpit panel inside VS Code
3. Open agent and terminal tabs
4. Terminal content — the real agent output, not a custom mock UI
5. Source Control — live view of changed files

The glue layer in this layout is voice. The user records while working on their own app, marks the observed result, and the agent does the real work in the terminal. Source Control stays as a judge-like surface: which files changed, what is staged, and what is still unstaged.

Once terminals and agents multiply, a higher-level control surface is needed. Cockpit provides that surface. It turns agent sessions into cards: waiting state, running state, host app, model and quick actions are all visible in one grid.

![Agent cards, waiting state and custom agent cards in the Cockpit app](https://optionos.app/guide/lineage-cockpit-agent-grid.png)
*Cockpit shows running and waiting agents as cards; waiting cards become action surfaces, while running cards stay as lower-priority monitoring signals.*
1. Cockpit grid — the main control surface for agent sessions
2. Selected Ghostty agent card
3. Host label — shows whether the agent runs in Ghostty or VS Code
4. Waiting state — an agent waiting for human input
5. Custom agent cards — quick-launch Claude/Codex surfaces
6. Active/focused agent card
7. Running cards — dimmed so they can be monitored without taking priority

At this layer the goal is not to read every agent. The goal is to find the agent that changes the next human decision. A waiting card asks for action; running cards are monitoring signals. Fast, controllable agents such as Codex therefore become quick-launch cards.

The same relation idea also applies while selecting components. When the inspector is open, the UI piece is selected, the source path becomes visible, and the spoken mark joins the same family.

![Component selection and source-map lineage through the inspector](https://optionos.app/guide/lineage-component-selection.png)
*When the inspector is open, the selected component, source path and spoken mark belong to the same lineage family.*
1. Selected component area — the UI piece to work on
2. Source path / lineage title — the ownership trace on the code side

This removes the need to say “open this Swift file.” The user opens the inspector, selects the component, marks it and speaks. The agent follows the bond between selected component and source path.

The last layer is the capture workflow. When Capture Actions, Inspector, captured images/files and the smart local-app bar are visible together, even the indexes can be produced by voice. Marking is no longer a separate documentation chore; it becomes part of the work loop.

![Capture actions, inspector and conversation capture list](https://optionos.app/guide/lineage-capture-inspector.png)
*Inspector, capture actions and the conversation list let the user give the UI piece, file and intent to the agent without describing code.*
Interactive scene: https://optionos.app/guide/en/lineage-graphs#lineage-capture-inspector

The big picture: every image carries its own lineage; image + explanation, plus the legend for any marks actually visible in the image, form an image-card family; the text between image-card families is workflow lineage. This is why the document is not an image gallery. The spoken glue layer connects the images into one working method.