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

```sql
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 |