storkit/.story_kit/specs/functional/PROJECT_MANAGEMENT.md

Functional Spec: Project Management

1. Project Lifecycle State Machine

The application operates in two primary states regarding project context:

1. Idle (No Project):
   • The user cannot chat about code.
   • The only available primary action is "Open Project".
2. Active (Project Loaded):
   • A valid local directory path is stored in the Session State.
   • Tool execution (read/write/shell) is enabled, scoped to this path.

2. Selection Logic

• Trigger: User initiates "Open Project".
• Mechanism: Native OS Directory Picker (via tauri-plugin-dialog).
• Validation:
  • The backend receives the selected path.
  • The backend verifies:
    1. Path exists.
    2. Path is a directory.
    3. Path is readable.
  • If valid -> State transitions to Active.
  • If invalid -> Error returned to UI, State remains Idle.

3. Security Boundaries

• Once a project is selected, the SessionState struct in Rust locks onto this path.
• All subsequent file operations must validate that their target path is a descendant of this Root Path.