Workspace Mode - Quick Start Guide

Ready to start implementing? Follow this guide.

---

Before You Begin

Read These Documents (in order)

1. WORKSPACE_VISION.md - Understand the vision and key decisions
2. WORKSPACE_ROADMAP.md - Full implementation plan
3. WORKSPACE_TASKS.md - Task tracker (update as you go)

Prerequisites

• All existing fac features working
• Clean build: make clean && make
• All tests passing
• Git working tree clean (commit current work)

---

Phase 0: Planning & Design (START HERE)

Goal: Create specification documents before writing code

Step 1: Create Directory Structure

mkdir -p docs
# (already done if you're reading this)

Step 2: Create workspace_spec.md

Document the workspace.json format in detail:

• JSON schema
• Field descriptions
• Example workspaces
• Validation rules

Template:

# Workspace Configuration Specification

## Overview
workspace.json stores the complete editor state for a workspace.

## Schema
...

## Example
...

## Validation
...

Step 3: Create fortress_integration.md

Document how Fortress modules integrate:

• Which modules to copy from ../fortress
• How to adapt them for fac
• Module dependencies
• API contracts

Template:

# Fortress Integration Plan

## Modules to Copy
1. filesystem/directory_module.f90
   - Functions: ...
   - Changes needed: ...

## Integration Points
...

Step 4: Create config_spec.md

Document config file formats:

• favorites.json format
• recents.json format
• backup metadata format
• File locations (XDG paths)

Template:

# Configuration Files Specification

## favorites.json
Location: ~/.config/fac/favorites.json
Format:
...

## recents.json
...

Step 5: Review & Finalize

• Review all specs
• Check for gaps
• Verify against WORKSPACE_VISION.md
• Get approval before coding

Phase 0 Complete When:

• ✅ All spec documents created
• ✅ Specs are detailed and clear
• ✅ No open questions remain
• ✅ Ready to write code

---

Phase 1: Fortress Navigator

Goal: Build basic dual-pane file/directory navigator

Step 1: Copy Fortress Code

# From fortress repo
cd ../fortress
ls -la app/
# Identify modules to copy

cd ../facsimile
mkdir -p src/fortress/{filesystem,terminal,ui}

# Copy files (example)
cp ../fortress/app/filesystem/*.f90 src/fortress/filesystem/
cp ../fortress/app/terminal/*.f90 src/fortress/terminal/
cp ../fortress/app/ui/*.f90 src/fortress/ui/

Step 2: Adapt for fac

• Remove main program
• Change module names if conflicts
• Adapt to fac's terminal API
• Remove fortress-specific features (git, fzf for now)

Step 3: Create Navigator Module

! src/fortress/ui/navigator_module.f90
module navigator_module
    implicit none
contains
    subroutine open_fortress_navigator(selected_path, selection_type)
        ! Returns selected path and whether it's a file or directory
    end subroutine
end module

Step 4: Add to Build

# Makefile
SOURCES = ... \
          src/fortress/filesystem/directory_module.f90 \
          src/fortress/terminal/fortress_render_module.f90 \
          src/fortress/ui/navigator_module.f90 \
          ...

Step 5: Add Ctrl-O Keybinding

! src/commands/command_handler_module.f90
else if (key_input == 'CTRL_O') then
    call handle_fortress_navigator(editor, buffer)
end if

Step 6: Test

make clean && make
./fac test.txt
# Press Ctrl-O
# Should see dual-pane navigator
# Navigate, select, verify return

Phase 1 Complete When:

• ✅ Ctrl-O opens Fortress navigator
• ✅ Can navigate filesystem
• ✅ Selecting directory returns path
• ✅ Selecting file returns path
• ✅ ESC cancels
• ✅ No regressions in existing features

---

Phase 2: Workspace Detection

Goal: Detect/create workspace directories and configs

Step 1: Create Workspace Module

! src/workspace/workspace_module.f90
module workspace_module
    implicit none

    type :: workspace_t
        character(len=:), allocatable :: path
        logical :: is_workspace_mode
    end type

contains
    subroutine workspace_init(workspace, path)
        ! Detect or create workspace
    end subroutine

    function workspace_exists(path) result(exists)
        ! Check for .fac/workspace.json
    end function
end module

Step 2: Update main.f90

! app/main.f90
type(workspace_t) :: workspace

if (argc == 0) then
    ! Open Fortress welcome (Phase 5)
else if (is_directory(arg)) then
    call workspace_init(workspace, arg)
else
    ! Single file mode
end if

Step 3: Create .fac/ Structure

subroutine create_workspace_structure(path)
    ! Create .fac/ directory
    ! Create .fac/workspace.json
    ! Create .fac/backups/
end subroutine

Step 4: Test

cd /tmp/test-workspace
../facsimile/fac .
# Should create .fac/workspace.json
ls -la .fac/

Phase 2 Complete When:

• ✅ fac . creates workspace
• ✅ .fac/workspace.json created
• ✅ fac file.txt still works (single-file mode)
• ✅ Command line parsing correct

---

Development Guidelines

Commit Often

Commit after each major task:

git add .
git commit -m "Implement fortress navigator dual-pane display"

Test After Each Change

make clean && make
./fac test.txt
# Test new feature
# Test existing features (regression check)

Update Task Tracker

Mark tasks complete in WORKSPACE_TASKS.md as you go.

Debug Logging

Add debug logging for complex logic:

! DEBUG: Remove before final release
open(unit=99, file='/tmp/fac_workspace_debug.txt', position='append')
write(99, '(A,A)') 'Loading workspace: ', trim(path)
close(99)

Handle Errors Gracefully

if (error) then
    ! Show error to user
    ! Fallback to safe state
    ! Don't crash
end if

Keep Backwards Compatibility

Always test single-file mode:

./fac README.md
# Should work exactly as before

---

When Things Go Wrong

Build Fails

make clean
# Check for syntax errors
# Check module dependencies (order matters)
# Verify all files in SOURCES
make

Feature Not Working

1. Add debug logging
2. Check file permissions
3. Verify paths are correct
4. Test with simple case first
5. Compare with spec documents

Cursor Bugs Appear

1. Check if new code modified cursor state
2. Verify sync_editor_to_pane calls
3. Test with single pane/tab first
4. Add debug output for cursor positions

State Not Persisting

1. Verify workspace.json being written
2. Check file permissions
3. Verify JSON format is valid
4. Test load/save separately

---

Communication

Document Decisions

If you make a design decision not in the specs:

1. Add it to WORKSPACE_VISION.md
2. Note why in commit message
3. Update WORKSPACE_ROADMAP.md if it affects plan

Ask Questions

If unclear about a requirement:

1. Check WORKSPACE_VISION.md first
2. Check WORKSPACE_ROADMAP.md
3. Ask before proceeding

---

Completion Checklist

Each Phase

• All tasks completed
• Tests passing
• No regressions
• Code committed
• Documentation updated
• WORKSPACE_TASKS.md updated

Final Release (Phase 7)

• All phases complete
• Performance acceptable
• User testing done
• Documentation complete
• README.md updated
• --help updated
• No debug logging
• Clean git history
• Version bumped
• Tagged release

---

Useful Commands

# Clean build
make clean && make

# Test single file mode
./fac README.md

# Test workspace mode
cd /tmp/test && ../facsimile/fac .

# Check for .fac directory
ls -la .fac/

# View workspace config
cat .fac/workspace.json | python -m json.tool

# Debug
tail -f /tmp/fac_workspace_debug.txt

# Remove workspace (clean slate)
rm -rf .fac/

---

Ready?

1. ✅ Read all documentation
2. ✅ Understand the vision
3. ✅ Environment ready
4. ✅ Start Phase 0!

Let's build this thing! 🚀