# Workflow Artifact Layout Evaluation

## Context

Current workflow authoring is centered on hidden project files under `.zibby/`:

- `.zibby/graph.mjs`
- `.zibby/nodes/*`
- `.zibby/chat.mjs`
- `.zibby/result-handler.mjs`
- runtime output in `.zibby/output/sessions/*`

The product direction is to support live workflow creation via `zibby chat` and local/remote arbitrary workflow execution, while keeping user-authored workflow code commit-friendly.

## Options

### Option A: Keep everything in hidden `.zibby/`

Pros:
- No migration needed.
- Fully compatible with current Studio/CLI assumptions.

Cons:
- User-authored workflow source remains hidden and less discoverable.
- Weaker commit ergonomics for user-owned workflow code.

### Option B: Move everything to visible `zibby/`

Pros:
- Clear, commit-friendly source-of-truth for workflow code.
- Better UX for editing workflow artifacts directly.

Cons:
- High migration cost.
- Breaks many path assumptions in Studio bridge, Electron, docs, and integrations.
- Requires dual-path compatibility window to avoid immediate breakage.

### Option C: Hybrid (recommended)

Store user-authored workflow source in visible `zibby/`, keep runtime/output in hidden `.zibby/output`.

Pros:
- Commit-friendly source artifacts.
- Preserves hidden runtime/cache/output behavior.
- Smaller migration blast radius than full move.

Cons:
- Requires resolver precedence logic and migration tooling.
- Transitional complexity (legacy `.zibby` source + new `zibby` source).

### Option D: Hybrid + configurable path in `.zibby.config.mjs`

Same as Option C, but adds explicit config override for source workflow path.

Pros:
- Flexible for monorepos and custom project conventions.
- Future-proofs enterprise setups.

Cons:
- Slightly larger surface area and testing burden.

## Impact Map (Current Coupling)

Key areas that currently assume hidden-source and/or hidden-output conventions:

- `studio/electron/main.js`
  - project-root detection uses `.zibby/graph.mjs`
  - default sessions root uses `.zibby/output/sessions`
- `studio/vite.config.js`
  - bridge fallbacks for session/output discovery
- `studio/src/adapters/platform.js`
  - APIs and comments assume `.zibby/output/sessions`
- `docsite/docs/*`
  - user docs describe hidden `.zibby` workflow/source model

Secondary impacts:

- integrations under `integrations/*` referencing current command/path patterns
- helper comments and UI command snippets across Studio/frontend

## Recommended Migration Strategy

### Phase 1 (compatibility, no breakage)

- Keep `.zibby/` source loading as primary behavior.
- Add support for visible `zibby/` source layout in resolvers.
- Resolver precedence:
  1. explicit config path (if set)
  2. `zibby/` source
  3. legacy `.zibby/` source
- Keep runtime output in `.zibby/output`.

### Phase 2 (opt-in default shift)

- New projects scaffold workflow source under `zibby/`.
- Existing projects continue to work with `.zibby/`.
- Add migration helper command to copy/move source artifacts safely.

### Phase 3 (deprecation)

- Emit warnings for legacy hidden-source layouts.
- After a compatibility window, finalize the preferred source layout.
- Continue hidden runtime/output unless there is strong product need to change it.

## Suggested Source/Runtime Split

- User-authored source (commit-friendly):
  - `zibby/graph.mjs`
  - `zibby/nodes/*`
  - `zibby/chat.mjs`
  - `zibby/result-handler.mjs`
- Runtime/cache/output (hidden):
  - `.zibby/output/*`
  - `.zibby/scratch/*`
  - `.zibby/memory/*`

## Why this recommendation

Hybrid with configuration gives the best balance: user-visible source for authoring and version control, while preserving stable hidden runtime/output semantics already used by Studio, CLI, and integrations.