Appearance
Graph operations
Standard graph edits update ◆ project.json and regenerate the affected Python declarations. Use Rename ID to change an identifier. Changes to the canvas layout do not change generated files.
Generation sends the project's manifests and declared source files, including pinned dependencies, to the configured Verdog service and writes the returned files locally. It does not require sign-in; see Permissions.
Generation creates missing authored scaffolds and preserves existing authored files. It replaces or deletes generated files to reflect the current graph and dependency pins. Local modifications to a recorded generated file block generation. The editor requests confirmation before deletion or relocation of an edge's authored implementation.
Successful generation also updates generated_from and the sources manifest in ◆ project.json; the tables omit those routine changes.
The paths below use:
text
<package> = src/<python-package-path>
<graph> = <package>/subroutines/<subroutine-id>For example, package demo.countdown has path src/demo/countdown. Nested definitions repeat the structure below their parent subroutine.
File references use the convention introduced in Ownership: ● user/authored and ◆ generated/system-managed.
Definitions
| Operation | Change in ◆ project.json | Files produced |
|---|---|---|
| Add subroutine | Adds a nested graph with enter, exit, and failure ports plus an enter-to-exit edge. | Creates <graph>/subroutines/<id>/ with ● impl.py, generated declarations, and component registries. The enclosing ◆ subroutines/__init__.py remains an empty package marker. |
| Make runnable | Adds a workflow that selects a visible subroutine as its entry, with profile and session bindings. | Creates generated workflow, profile, session, and binding declarations, plus authored ● requirements.txt. The enclosing ◆ workflows/__init__.py remains an empty package marker. |
| Add subroutine call | Adds a subroutine_call node whose operation names a local or pinned subroutine. | Produces the normal node files. The typed child boundary, parameter closure, and resource mappings live in the node's generated ◆ __init__.py. |
| Add workflow call | Adds a workflow_call node whose operation names a workflow envelope. | Produces the normal node files. The process-boundary types live in the node's generated ◆ __init__.py. |
A definition and a call are independent operations: defining a subroutine does not create a call node, and adding a call node does not connect it.
Nodes and features
All added nodes update ◆ <graph>/nodes/__init__.py and create ◆ <graph>/nodes/<id>/__init__.py.
| Operation | Additional output |
|---|---|
| Add Python node | Creates ● nodes/<id>/impl.py for its output and local-state types. Each incoming edge creates a separate visit below the node. |
| Add agent node | Creates ● nodes/<id>/impl.py for output and state types. The generated declaration records the selected profile and session. Resource bindings are recorded in project.json. |
| Add feature node | Creates the node's generated ◆ __init__.py but no node ● impl.py. An incoming edge creates the user-authored feature visit that proposes candidate feature state. |
| Add feature | Adds a Boolean, integer, float, or enum entry to features[]; creates generated ◆ features/<id>/__init__.py and updates the feature registry. No authored file is created; a Feature visit assigns the initial value. |
| Add profile | Adds a local provider configuration or a subroutine profile parameter, generates ◆ profiles/<id>/__init__.py, and updates the profile registry. No authored Python is created. Workflows may own local profiles but not profile parameters. |
| Add session | Adds a local session or a subroutine session parameter, generates ◆ sessions/<id>/__init__.py, and updates the session registry. No authored Python is created. Workflows may own local sessions but not session parameters. |
An added node is initially disconnected. Each subsequent incoming edge determines a separate visit's input type. A node with no path from enter is reported as unreachable.
Edges and visits
| Operation | Change in ◆ project.json | Files produced |
|---|---|---|
| Connect nodes | Adds an edge with empty conditions and effects. | Creates ◆ edges/<edge-id>/__init__.py and updates ◆ edges/__init__.py. For an executable target it also creates ◆ nodes/<target>/visit/<edge-id>/__init__.py and the sibling ● impl.py. Edges into exit or failure ports have no visit files. |
| Constrain or clear edge | Adds, replaces, or removes one feature observation in the edge's conditions or effects. Effects are allowed only on an edge whose source is a feature node. | Updates that edge's generated ◆ edges/<edge-id>/__init__.py with typed condition or effect objects. No user-authored file is created. |
| Relink edge | Changes the source or target while retaining constraints. An automatically derived edge ID follows its new endpoints; a custom ID remains unchanged. | Updates the edge declaration. If its derived ID changes, generation replaces ◆ edges/<old-id>/__init__.py with the new path and updates the edge registry. If the target or edge ID changes the visit path, VS Code asks whether to move ● impl.py or delete it and create a fresh scaffold. A target that needs no visit removes the old implementation after confirmation. |
Every visit implementation is stored below its target and named by its edge ID. Parallel and custom-named edges therefore remain separate.
Metadata operations
| Operation | Result |
|---|---|
| Assign agent | Selects one profile and one session for the Agent node and updates its generated declaration. Nodes using the same persistent session resource share provider conversation state; a local subroutine session is recreated on each invocation. |
| Change display name | Changes name or a feature's label. ◆ Node, edge, and feature declarations embed that text and are updated; a subroutine name remains graph metadata. Paths and references do not move. |
| Move on canvas | Changes only editor.layouts. Layout is excluded from the graph hash and produces no Python change. |
| Rename ID | Rewrites graph references and Python imports, and moves the affected generated and authored paths under the new ID. |
Deletion
The deletion review lists removed entities, changes to surviving references, and imports made unused by the edit. Deletion specifies the cascade, root reset, and file-handling rules.