Goose projects docs (#3272)

documentation/docs/guides/goose-cli-commands.md

@@ -421,8 +421,6 @@ goose schedule remove --id daily-report
 
 Start working on your last project or create a new one.
 
-A project is a record of a working directory and recent session metadata. Note that any directory where you run `goose project` becomes a tracked project, so you might want to run the command from the directory where you want to work.
-
 **Alias**: `p`
 
 **Usage:**
@@ -430,14 +428,7 @@ A project is a record of a working directory and recent session metadata. Note t
 goose project
 ```
 
-The command provides three options:
+For a complete guide, see [Managing Projects Guide](/docs/guides/managing-projects).
-1. **Resume project with session**: Continue the last session in the project
-2. **Resume project with fresh session**: Start a new session in the project
-3. **Start new project in current directory**: Create a new project in the current directory
-
-:::note
-Goose stores your project history in `~/.local/share/goose/projects.json`.
-:::
 
 ---
 ### projects
@@ -451,23 +442,7 @@ Choose one of your projects to start working on.
 goose projects
 ```
 
-Example output:
+For detailed usage examples and workflows, see [Managing Projects Guide](/docs/guides/managing-projects).
-```bash
-┌  Goose Project Manager
-│
-◆  Select a project:
-│  ● .../Users/svera (2025-05-21 18:42:05)
-│  ○ .../Development/goose (2025-05-21 18:38:26)
-│  ○ .../Documents/goose-recipes (2025-05-21q 18:29:15)
-│  ○ .../Desktop/temp (2025-05-21 15:13:48)q
-│  ○ .../doc_projects/shared (2025-05-21 14:32:22)
-│  ○ Cancel
-└
-```
-
-After selecting a project, you'll be asked to either:
-- **Resume previous session**: Continue the last session in the selected project
-- **Start new session**: Start a new session in the selected project
 
 ---
 ### web

documentation/docs/guides/managing-goose-sessions.md

@@ -41,10 +41,6 @@ A session is a single, continuous interaction between you and Goose, providing a
         ```sh
         goose web --open
         ```
-
-        :::tip
-        You can also use the [`project`](/docs/guides/goose-cli-commands#project) and [`projects`](/docs/guides/goose-cli-commands#projects) commands to start or resume sessions from a project, which is a tracked working directory with session metadata.
-        :::
     </TabItem>
 </Tabs>
 
@@ -116,10 +112,6 @@ Note that sessions are automatically saved when you exit.
         :::tip
         While you can resume sessions using the commands above, we recommend creating new sessions for new tasks to reduce the chance of [doom spiraling](/docs/troubleshooting#stuck-in-a-loop-or-unresponsive).
         :::
-
-        :::tip
-        You can also use the [`project`](/docs/guides/goose-cli-commands#project) and [`projects`](/docs/guides/goose-cli-commands#projects) commands to start or resume sessions from a project, which is a tracked working directory with session metadata.
-        :::
     </TabItem>
 </Tabs>
 
@@ -234,6 +226,10 @@ You can resume a CLI session in Desktop and vice versa.
     </TabItem>
 </Tabs>
 
+## Project-Based Sessions
+
+You can also use the [`project`](/docs/guides/goose-cli-commands#project) and [`projects`](/docs/guides/goose-cli-commands#projects) commands to start or resume sessions from a project, which is a tracked working directory with session metadata. For a complete guide to using Projects, see [Managing Projects Guide](/docs/guides/managing-projects).
+
 ## Remove Sessions
 
 You can remove sessions using CLI commands. For detailed instructions on session removal, see the [CLI Commands documentation](/docs/guides/goose-cli-commands#session-remove-options).

documentation/docs/guides/managing-projects.md

@@ -0,0 +1,114 @@
+---
+sidebar_position: 2
+title: Managing Projects
+sidebar_label: Managing Projects
+---
+
+Goose Projects automatically track your working directories and associated sessions, making it easy to resume work across multiple codebases with full context preservation.
+
+A **project** in Goose is a record of a working directory where you've used Goose. Every time you run Goose, it automatically tracks the current directory as a project, storing:
+
+- **Path**: The absolute path to the project directory
+- **Last accessed**: When you last worked on this project  
+- **Last instruction**: The most recent command you gave to Goose
+- **Session ID**: The associated session for context continuity
+
+Projects are stored in `~/.local/share/goose/projects.json`.
+
+:::info CLI Only Feature
+Projects are currently available only through the Goose CLI. Desktop support is planned for future releases.
+:::
+
+## Basic Usage
+
+**Resume your most recent project:**
+
+```bash
+goose project  
+```
+
+**Browse all your projects:**
+
+```bash
+goose projects  
+```
+:::tip
+When resuming a project, you can continue the previous session or start fresh in that directory.
+:::
+
+For complete command syntax and options, see the [CLI Commands Guide](/docs/guides/goose-cli-commands#project).
+
+## Workflow Example
+
+Let's follow Sarah, a developer working on multiple projects throughout her day:
+
+### Morning: API Development
+```bash
+cd ~/projects/ecommerce-api
+goose session --name "api-auth-work"
+```
+*Sarah asks Goose to help implement JWT token refresh logic*
+
+### Mid-Morning: Mobile App Bug Fix  
+```bash
+cd ~/projects/mobile-app
+goose session
+```
+*Sarah gets help debugging an iOS crash in the login screen*
+
+### Afternoon: Admin Dashboard
+```bash
+cd ~/projects/admin-dashboard  
+goose session --name "dashboard-ui"
+```
+*Sarah works on creating user management interface components*
+
+### Next Day: Quick Resume
+```bash
+# From any directory, quickly resume the most recent project
+goose project
+```
+
+Goose shows:
+```
+┌ Goose Project Manager
+│
+◆ Choose an option:
+│  ○ Resume project with session: .../admin-dashboard
+│    Continue with the previous session
+│  ○ Resume project with fresh session: .../admin-dashboard  
+│    Change to the project directory but start a new session
+│  ○ Start new project in current directory: /Users/sarah
+│    Stay in the current directory and start a new session
+└
+```
+
+### Later: Browse All Projects
+```bash
+goose projects
+```
+
+Goose displays:
+```
+┌ Goose Project Manager
+│
+◆ Select a project:
+│  ○ 1  .../admin-dashboard (2025-01-07 09:15:30) [create user management interface]
+│  ○ 2  .../mobile-app (2025-01-06 11:45:20) [login screen crashing on iOS]  
+│  ○ 3  .../ecommerce-api (2025-01-06 09:30:15) [JWT token refresh logic]
+│  ○ Cancel
+└
+```
+
+Sarah can see her recent projects with timestamps and context, making it easy to choose where to continue working.
+
+## Benefits
+
+:::tip Time Savings
+Projects eliminate the typical 2-5 minutes lost when switching between codebases, especially valuable for developers working on multiple projects daily.
+:::
+
+- **Eliminate context switching friction** - Jump between projects instantly without manual navigation
+- **Preserve work context** - Resume exactly where you left off with full conversation history
+- **Seamless session integration** - Maintain continuity across different codebases
+