resolutionflow/docs/plans/2026-02-25-flow-to-library-sync-design.md

Flow-to-Library Step Sync Design

Date: 2026-02-25 Feature: Automatically sync steps from published flows into the step library

---

Overview

When a flow is published, its steps are extracted and written into the step_library table so engineers can discover and reuse them when building new flows or inserting ad-hoc steps during a live session. Library entries are flow-owned and read-only — forking creates a personal copy for customization.

What gets synced:

• procedural / maintenance flows → each procedure_step node → step_type: 'action'
• troubleshooting flows → each action node → step_type: 'action'; each solution node → step_type: 'solution'
• section_header and procedure_end nodes are NOT synced as library entries

Sync trigger: PUT /trees/{tree_id} when status transitions to 'published'

Sync model: Upsert keyed on (source_tree_id, source_node_id) — subsequent publishes update existing entries without losing usage counts or ratings.

---

Section 1: Data Model

New columns on step_library (one migration)

Column	Type	Default	Notes
source_tree_id	UUID FK → trees.id	NULL	SET NULL on tree delete
source_node_id	String(255)	NULL	Node id within tree_structure JSONB
is_flow_synced	Boolean	false	Distinguishes synced from manually created entries
last_synced_at	DateTime(timezone=True)	NULL	Timestamp of last sync

New optional field on StepContent schema

Add group_label: Optional[str] = None to StepContent in backend/app/schemas/step_library.py. For procedural steps that belong to a section, this stores the section header title so steps are browsable/filterable by section in the library.

Per-step visibility override on procedural step nodes

Add optional library_visibility field to individual step nodes in tree_structure JSONB:

• Type: 'team' | 'public' (no 'private' — synced steps are always at minimum team-visible)
• If absent: inherits visibility from the flow (default behavior)
• Stored directly on the step node in tree_structure — no schema migration needed (JSONB is flexible)

Visibility inheritance mapping

Flow state	Resolved step visibility
is_public=True	'public'
is_public=False, has account_id	'team'
is_public=False, no account_id	'team'
Step has library_visibility set	Use that value (overrides above)

On flow deactivation / deletion

When is_active is set to False on a tree, or the tree is deleted, soft-delete all synced library entries for that tree: UPDATE step_library SET is_active=False WHERE source_tree_id=:tree_id AND is_flow_synced=True.

Forked copies (is_flow_synced=False, different created_by) are unaffected.

---

Section 2: Sync Logic (Backend)

Trigger location

backend/app/api/endpoints/trees.py — update_tree() function, after the block at line ~587 where status is confirmed to be transitioning to 'published'.

Extraction logic

For procedural/maintenance flows:

steps = tree_structure.get('steps', [])
for node in steps:
    if node['type'] != 'procedure_step':
        continue
    # find the most recent section_header preceding this step
    group_label = last_seen_section_header_title
    yield StepLibraryUpsert(
        title=node['title'],
        step_type='action',
        content=StepContent(
            instructions=node.get('description') or node['title'],
            help_text=node.get('expected_outcome'),
            commands=[StepCommand(label=c.get('label',''), command=c['code'], command_type=c.get('language'))
                      for c in normalize_commands(node.get('commands'))],
            group_label=group_label,
        ),
        visibility=node.get('library_visibility') or resolve_visibility(tree),
        source_tree_id=tree.id,
        source_node_id=node['id'],
    )

For troubleshooting flows:

walk all nodes recursively
for node with type in ('action', 'solution'):
    yield StepLibraryUpsert(
        title=node['title'],
        step_type='action' if node['type']=='action' else 'solution',
        content=StepContent(
            instructions=node.get('description') or node['title'],
        ),
        visibility=resolve_visibility(tree),
        source_tree_id=tree.id,
        source_node_id=node['id'],
    )

Command normalization: node.commands can be a plain string or an array of {language, code, label} objects. Normalize both into StepCommand list.

Upsert query

INSERT INTO step_library (id, title, step_type, content, visibility, created_by,
    account_id, is_flow_synced, source_tree_id, source_node_id, last_synced_at, ...)
VALUES (...)
ON CONFLICT (source_tree_id, source_node_id)
DO UPDATE SET
    title = EXCLUDED.title,
    content = EXCLUDED.content,
    visibility = EXCLUDED.visibility,
    last_synced_at = EXCLUDED.last_synced_at,
    is_active = true  -- re-activate if previously soft-deleted

Requires a unique constraint on (source_tree_id, source_node_id).

created_by for synced entries

Set to the tree's author_id. This gives the flow author "ownership" of the entry, consistent with the flow-owned model. Permissions in core/permissions.py already allow the creator to see their own private steps — no change needed.

---

Section 3: Per-Step Visibility Override (Editor)

Where

frontend/src/components/procedural-editor/StepEditor.tsx — inside the existing "More Options" collapsible section.

What

A "Library Visibility" select field, shown only for procedure_step nodes (not section headers, not end nodes):

Library Visibility
[ Inherit from flow ▼ ]   (options: Inherit from flow / Team only / Public)

• Default (no library_visibility on node): renders as "Inherit from flow"
• Selecting "Team only" or "Public" writes library_visibility: 'team' or library_visibility: 'public' to the node
• Selecting "Inherit from flow" removes the library_visibility key from the node

Only rendered when tree_type is 'procedural' or 'maintenance'. Troubleshooting flows have no per-node override (they inherit the flow visibility always).

---

Section 4: Frontend — Step Library Browser

Changes to StepLibraryBrowser / step list

• "From Flow" badge on synced entries (is_flow_synced: true): small chip — same style as existing type badges. Shows source flow name.
• Step detail/preview panel: add "Sourced from: [Flow Name]" line with a link to the flow's navigate/edit page.
• Read-only indicator: for is_flow_synced entries, replace the Edit button with a lock icon + tooltip: "Managed by source flow — fork to customize."
• Fork behavior: existing "Save to Library" copy mechanism unchanged. Forked copy gets is_flow_synced=false, source_tree_id=null, created_by=current_user.

API response changes

StepLibraryResponse needs two new fields:

• is_flow_synced: bool
• source_tree_name: Optional[str] — joined from trees.name at query time

---

Files Changed

File	Change
backend/alembic/versions/030_add_step_library_sync_fields.py	New migration — add 4 columns + unique constraint
backend/app/models/step_library.py	Add 4 new columns + FK relationship to Tree
backend/app/schemas/step_library.py	Add group_label to StepContent; add is_flow_synced + source_tree_name to response schema
backend/app/api/endpoints/trees.py	Add sync logic after publish transition
backend/app/core/step_sync.py	New module — extraction + upsert logic (keeps trees.py clean)
backend/tests/test_step_sync.py	New test file
frontend/src/types/step.ts	Add is_flow_synced, source_tree_name to Step type
frontend/src/components/procedural-editor/StepEditor.tsx	Add Library Visibility select in More Options
frontend/src/components/step-library/StepLibraryBrowser.tsx	From Flow badge, read-only indicator, source flow link