Data, saving and exports

What appears after saving

Video CV: runtime, markup and export are different data

Video CV workflow and track apply →

What the canonical project contains

• project_info, the coordinate contract and canvas object/layer state;
• context, Capture context, source-image references and timeline selection;
• gui_elements, image features/matches, geometry, annotations, typed edges, regions and markup groups;
• the selected save profile, tree-module registry entries and a CV result manifest reference;
• write reports, feature diagnostics, the artifact-integrity report and save summary.

JSON Schema Draft 2020-12 validates structure during loading. The artifact validator then checks missing files, hashes, absolute or escaping paths, coordinates and consistency. Successful schema validation alone does not prove that every file is present.

How a CV result enters the project package

The CV runtime, image series and canonical markup are three different boundaries. Live preview remains working state. In the main panel, manual Apply normally stores a verified bundle and attaches or replaces the selected element's cv_result; Add mask to results appends a separate cv_mask entry. These image-series mutations participate in undo/redo and dirty the project, but do not create new canonical geometry or semantics.

• Save creates a named runtime archive under ScrephData/screen_selector/cv/results; this is technical/debug history outside the project package.
• During canonical save, the importer takes only attached CV image-series entries, copies source/recipe/config/metrics/outputs into staged <name>_artifacts, and builds the project-local result_manifest.json.
• The main JSON stores cv_result_manifest_path, while the image-series entry remains a lightweight projection with run/output identity. The manifest is published after required artifact write/readback.
• Add as elements or confirmed promotion apply separately mutates canonical markup. General/GUI promotion validates the accepted decision and stale context, builds an apply preview/plan, and runs transactionally with a rollback attempt.

CV panel actions and their side effects →

What the save profile actually changes

The project environment selects a downstream strategy, save scope selects the destination directory, and the code-tool switch controls a best-effort launch/context handoff after writing. The feature-output profile has a narrower scope: Full/Compact/Automation/LLM/Debug, coordinate space, color formats, assets and summary apply to the preview or explicit feature projection, not to the canonical representation.

• Canonical JSON always stores the complete feature payload, summary, linked assets and screenshot_raw_px geometry; the chosen output profile is stored as metadata.
• The primary save flow does not write a separate feature-projection file. InfoPanel can build it for preview, and a code or external consumer must request it explicitly.
• “Will be created” shows the primary JSON and selected target script/guide, but it is not a complete package manifest and omits the automatic agent export, artifacts and conditional sidecars.

Image inspection: project state and temporary data

Image Inspection separates persisted canvas state from temporary measurements. The presence of a measurements layer does not mean that measurement lines are included in the project package.

• canvas_layer_state in the canonical project stores six layer IDs plus visibility, opacity and order. Locks are excluded and reset on restore.
• A/B/C/D layout, assignments, display modes, linked panes, the selected evidence tab and navigator settings are stored separately as local Selector state, not as portable project markup.
• Profile lines and their local Undo/Redo exist only for the runtime session and are cleared when the source changes. Copy profile as TSV writes to the clipboard, while Export profile to CSV creates a standalone file with distance, x/y, RGB, luminance, sampled layer and source reference.

Derived for_ai_agent export

<name>.for_ai_agent.json is generated automatically from the saved canonical package. It contains the source Project JSON hash, normalized elements/relations, features and issues, a CV summary, asset references, the tree-module registry and authoring context. Heavy bodies normally remain files in the project package and are represented by references.

• The primary save flow uses this sidecar when available; canonical JSON remains the fallback context. Project Manager save and some legacy save entry points currently pass the canonical path directly.
• Project Manager classifies the sidecar as an agent export and does not open it in Selector as a project.
• The Assistant action project.export_for_automation requires confirmation and an explicit output path, but currently also writes the for_ai_agent role with an automation_runtime_context profile rather than a separate automation_export.

A tree module is a compact slice, not a subproject

In the element tree, open Module → Create module from subtree.... Screph writes <name>_artifacts/modules/<slug>/module.json, a Python helper class and a README, while the canonical project stores only the registry entry and freshness/hash information.

• refs_only keeps project-asset references; self_contained copies used files into the module directory and records SHA-256.
• The module includes internal relations and separate boundary references to objects outside the selected branch.
• After the branch changes, the badge may show a stale state; use Update module or Update stale modules.

What Automation Runtime consumes

The current Python runtime loads the canonical project and reads gui_elements; for_ai_agent is not its direct input contract. A GUI Automation save target may additionally prepare:

The canonical/agent package is written before automation coordinate validation and target preparation. A failure at those stages therefore does not roll back project files already created and may leave a partially prepared guide or script; the current project path and clean state are not updated. Save again after correcting the cause.

Screph CV does not materialize a special CV-workspace artifact: it uses the same basic canonical writer as “project only.” The difference is only the explicit Open Result action, which switches to the existing internal CV tab instead of opening the project directory.

Project loading, coordinates and input backends →

A schema on disk does not always mean a user-facing export

Formal schemas exist for the canonical project, for_ai_agent, tree module, CV result manifest, feature, automation_export and llm_export. Current materialized user paths directly produce canonical/agent/tree outputs and CV/feature data; automation_export and llm_export are currently contract surfaces for adapters/tests and have no separate user-facing writer in the primary save flow.

In addition to formal schemas, Capture, timeline, diagnostics and Action CV use versioned runtime JSON roles without a separate JSON Schema file for every sidecar. Check json_role and both version forms rather than relying on the .json extension.

Project Manager, moving and recovery

Ctrl+O opens Project Manager with Projects, Autosaves and Problems tabs. It distinguishes canonical projects, agent exports, tree modules, unknown JSON and damaged JSON.

• Duplicate/rename/restore operate on the project directory and update the primary JSON name, timeline state and frame-bound index.
• After a rename or duplicate, save the project again before agent/code handoff; this rebuilds for_ai_agent with the current basename and SHA.
• GraphML, interactive HTML and project-graph JSON exported by Manager visualize the project/module map; they are not the canonical project or an automation script. GraphML requires networkx.
• An agent export appears as a problem/derived entry, but when its reference exists, Open resolves to the linked canonical project. A tree module or arbitrary JSON does not become a project.
• Manager considers a canonical project or autosave openable only with a non-zero domain count; a screenshot-only autosave has a separate startup recovery path.

Manager does not delete a project directory. Remove from history and Clear missing only change ScrephData/local_state/selector_project_history.json. Tags and notes live in a separate path-keyed selector_project_metadata.json; they are outside the package and do not migrate during duplicate, rename or a manual move.

Manager's pre-open diagnostics cover JSON decoding and role, the canonical schema, kind-specific feature schemas, missing paths and an empty domain. Manager does not run a fresh full artifact scan before opening; after load, InfoPanel combines the current domain load report with saved save diagnostics.

Crash reports, autosave and diagnostics →

Safe handoff sequence

1. Review markup and explicitly apply the required CV candidates.
2. Save the canonical project and ensure save diagnostics report no failure.
3. Choose the consumer: a runtime target, Screph Code/IDE, a tree module or your own adapter.
4. Hand off only the package files and assets required by that consumer.
5. Before automation execution, review package diagnostics and then explicitly handle the (ok, errors) returned by validate_project; load_project does not do this automatically.
6. Verify the target window, coordinate projection, selected input monitor/backend and a separate postcondition after each input action.

Privacy

Local saving does not upload the package automatically. However, canonical/agent JSON may contain annotations, OCR text, window/capture context and references to sensitive images. Before using a cloud LLM, speech service, support upload or sharing the directory, inspect not only JSON but also _artifacts, timeline sources, guides and generated scripts.

The project-local Assistant mirror may contain prompts, responses, paths and action metadata; global 180-day cleanup does not remove it. See the local-data guide for the complete storage and cleanup map.