docs: reorganize (#9310)

documentation/blog/2025-03-06-goose-tips/index.md

@@ -50,11 +50,11 @@ Beyond projects, global .goosehints files (`~/.config/goose/.goosehints`) apply
 
 ## 4. Choose the Right Mode for Your Workflow
 
-goose offers [different modes](/docs/guides/goose-permissions) that determine how much autonomy it has when modifying files, using extensions, and performing automated actions. 
+goose offers [different modes](/docs/guides/managing-tools/goose-permissions) that determine how much autonomy it has when modifying files, using extensions, and performing automated actions. 
 
 * ⚡️ **Auto Mode (Default):** goose can modify, create, and delete files, as well as use extensions, without requiring approval. Best for users who want seamless automation.
 
-* ✅ **Approve Mode:** goose asks for confirmation before making changes. With [Smart Approve](/docs/guides/goose-permissions#permission-modes) enabled, it evaluates risk levels and prompts for high-risk actions while executing safe ones automatically.
+* ✅ **Approve Mode:** goose asks for confirmation before making changes. With [Smart Approve](/docs/guides/managing-tools/goose-permissions#permission-modes) enabled, it evaluates risk levels and prompts for high-risk actions while executing safe ones automatically.
 
 * 💬 **Chat Mode:** goose operates in chat-only mode, without modifying files or using extensions. Ideal for users who want AI assistance without automation.
 

documentation/blog/2025-04-08-vibe-code-responsibly/index.md

@@ -65,7 +65,7 @@ This is especially useful for tasks that span multiple files, involve side effec
 
 ### 3. Choose the Right Mode for the Job
 
-While letting your AI agent take the lead is fun, not every moment calls for full autonomy. Sometimes, you need to pause, review, or plan before any code changes. Goose offers several [modes](https://goose-docs.ai/docs/guides/goose-permissions) that help you stay in control without breaking your momentum. Here's how to use them intentionally during your sessions:
+While letting your AI agent take the lead is fun, not every moment calls for full autonomy. Sometimes, you need to pause, review, or plan before any code changes. Goose offers several [modes](https://goose-docs.ai/docs/guides/managing-tools/goose-permissions) that help you stay in control without breaking your momentum. Here's how to use them intentionally during your sessions:
 
 * **Chat Mode**  
   Goose will only respond with text so that you can brainstorm together.

documentation/blog/2025-06-16-multi-model-in-goose/index.md

@@ -8,7 +8,7 @@ authors:
 ---
 
 :::danger Outdated
-Lead/Worker mode has been removed from goose. It has been replaced by [Planning Mode](/docs/guides/creating-plans), which uses a dedicated planner model with the `/plan` command. See the [multi-model guide](/docs/guides/multi-model/) for current workflows.
+Lead/Worker mode has been removed from goose. It has been replaced by [Planning Mode](/docs/guides/context-engineering/creating-plans), which uses a dedicated planner model with the `/plan` command. See the [multi-model guide](/docs/guides/multi-model/) for current workflows.
 :::
 
 ![blog cover](multi-model-ai-agent.png)
@@ -84,7 +84,7 @@ export GOOSE_MODEL="claude-4-sonnet"
 
 From there, Goose takes care of the hand off, the fallback, and the recovery. You just... keep vibing.
 
-If you're curious how it all works under the hood, see the [planning guide](/docs/guides/creating-plans).
+If you're curious how it all works under the hood, see the [planning guide](/docs/guides/context-engineering/creating-plans).
 
 ---
 

documentation/blog/2025-07-21-orchestrating-subagents/index.md

@@ -36,7 +36,7 @@ I decided to create a digital resource that teaches foundational concepts like A
 
 ## Meet the Subagents
 
-[Subagents](/docs/guides/subagents) are individual AI instances that take on specific tasks. Each one runs in its own session, which helps preserve the main context window and keeps your primary Goose conversation uncluttered and focused on high-level orchestration. I think of subagents as temporary teammates. Goose assigns each subagent a job and deallocates it when the work is complete.
+[Subagents](/docs/guides/context-engineering/subagents) are individual AI instances that take on specific tasks. Each one runs in its own session, which helps preserve the main context window and keeps your primary Goose conversation uncluttered and focused on high-level orchestration. I think of subagents as temporary teammates. Goose assigns each subagent a job and deallocates it when the work is complete.
 
 For this project, I turned my subagents into an on-demand dev squad, and I assigned them the following roles:
 
@@ -56,7 +56,7 @@ As of version 1.10.0, subagents are no longer experimental and don't require ena
 
 ## Instructing My Team
 
-There are a few ways to create subagents in Goose. You can use natural language prompts, define them through [recipes](/docs/guides/recipes/), or even spin up [external subagents](/docs/guides/subagents/#external-subagents) like Codex or Claude Code.
+There are a few ways to create subagents in Goose. You can use natural language prompts, define them through [recipes](/docs/guides/recipes/), or even spin up [external subagents](/docs/guides/context-engineering/subagents/#external-subagents) like Codex or Claude Code.
 
 I took the natural language prompt approach because it felt convenient to directly configure a subagent through one prompt. Here’s the prompt I used:
   
@@ -171,7 +171,7 @@ What will you build with subagents?
 
 [Download Goose](/)
 
-[Learn about subagents](/docs/guides/subagents)
+[Learn about subagents](/docs/guides/context-engineering/subagents)
 
 <head>
   <meta property="og:title" content="Orchestrating 6 Subagents to Build a Collaborative API Playground for Kids" />

documentation/blog/2025-07-28-ai-to-ai/index.md

@@ -406,7 +406,7 @@ Angie's Diner shows exceptional performance with premium order values and strong
 </details>
 
 
-What a fun experiment! This gave me a better understanding of how agent-to-agent and [subagent](/docs/guides/subagents) workflows may work behind the scenes. Makes you wonder, what else could happen when AIs start talking to each other without us?
+What a fun experiment! This gave me a better understanding of how agent-to-agent and [subagent](/docs/guides/context-engineering/subagents) workflows may work behind the scenes. Makes you wonder, what else could happen when AIs start talking to each other without us?
 
 ---
 

documentation/blog/2025-08-11-llm-tag-team-lead-worker-model/index.md

@@ -7,7 +7,7 @@ authors:
 ---
 
 :::danger Outdated
-Lead/Worker mode has been removed from goose. It has been replaced by [Planning Mode](/docs/guides/creating-plans), which uses a dedicated planner model with the `/plan` command. See the [multi-model guide](/docs/guides/multi-model/) for current workflows.
+Lead/Worker mode has been removed from goose. It has been replaced by [Planning Mode](/docs/guides/context-engineering/creating-plans), which uses a dedicated planner model with the `/plan` command. See the [multi-model guide](/docs/guides/multi-model/) for current workflows.
 :::
 
 ![blog cover](header-image.png)
@@ -42,7 +42,7 @@ This is where it gets really cool - you can use Claude for reasoning and OpenAI
 - 🏃‍♂️ Handle Long Dev Sessions
 Perfect for those marathon coding sessions where you need sustained performance without breaking the bank.
 
-## [Setting It Up](/docs/guides/creating-plans)
+## [Setting It Up](/docs/guides/context-engineering/creating-plans)
 
 Getting started with the Lead/Worker model is surprisingly straightforward. In the Goose desktop app, you just need to:
 
@@ -104,7 +104,7 @@ The best part? The models made smart decisions we hadn't even thought of, like a
 
 ## Ready to Try Multi-Model Workflows?
 
-Lead/Worker mode has been removed, but goose now supports [Planning Mode](/docs/guides/creating-plans) for multi-model workflows. Whether you're working on documentation, building features, or tackling complex refactoring, pairing a strong planner model with a fast execution model can be a game changer.
+Lead/Worker mode has been removed, but goose now supports [Planning Mode](/docs/guides/context-engineering/creating-plans) for multi-model workflows. Whether you're working on documentation, building features, or tackling complex refactoring, pairing a strong planner model with a fast execution model can be a game changer.
 
 Want to see it in action? Check out the full stream where we built this feature live:
 

documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md

@@ -21,7 +21,7 @@ Every week, the PulseMCP team faced the same time-consuming workflow: sourcing r
 
 ## The Solution: Why Sequential Beats Monolithic
 
-Instead of building one massive "do-everything" agent (which inevitably fails on complex tasks), PulseMCP broke their workflow into six distinct phases. Each phase gets handled by focused [recipes](/docs/guides/recipes/session-recipes), [subrecipes](/docs/guides/recipes/subrecipes) and [subagents](/docs/guides/subagents) with clear inputs, outputs, and a single job.
+Instead of building one massive "do-everything" agent (which inevitably fails on complex tasks), PulseMCP broke their workflow into six distinct phases. Each phase gets handled by focused [recipes](/docs/guides/recipes/session-recipes), [subrecipes](/docs/guides/recipes/subrecipes) and [subagents](/docs/guides/context-engineering/subagents) with clear inputs, outputs, and a single job.
 
 This approach has three main benefits: debugging becomes easier when agents have single responsibilities, results become more predictable with clear handoffs between stages, and humans stay in control of the editorial process while automating the tedious work.
 

documentation/blog/2025-08-14-agent-coordination-patterns/index.md

@@ -36,7 +36,7 @@ Think lone developer grinding through the ticket.
 
 ## The Subagent Setup: Orchestrator With a Crew
 
-With [subagents](/docs/guides/subagents), you still have one "main" agent, but instead of doing everything, it plays tech lead and delegates pieces of the work to other specialized agents.
+With [subagents](/docs/guides/context-engineering/subagents), you still have one "main" agent, but instead of doing everything, it plays tech lead and delegates pieces of the work to other specialized agents.
 
 The main agent says:
 

documentation/blog/2025-08-18-understanding-context-windows/index.md

@@ -81,7 +81,7 @@ The [Memory extension](https://goose-docs.ai/docs/mcp/memory-mcp) stores importa
 
 **5. Subagents**
 
-[Subagents](https://goose-docs.ai/docs/guides/subagents) handle specific tasks in their own isolated sessions. This prevents your main conversation from getting cluttered with implementation details and tool outputs. You delegate work to subagents and only see the final results, keeping your primary context window clean and focused.
+[Subagents](https://goose-docs.ai/docs/guides/context-engineering/subagents) handle specific tasks in their own isolated sessions. This prevents your main conversation from getting cluttered with implementation details and tool outputs. You delegate work to subagents and only see the final results, keeping your primary context window clean and focused.
 
 **6. Short sessions**
 
@@ -89,7 +89,7 @@ Keep individual sessions focused on specific tasks. When you complete a task or
 
 **7. Planner model + focused execution**
 
-Use a dedicated [planner model](/docs/guides/creating-plans) for complex reasoning and keep your default model focused on execution. This gives you control over cost and quality while keeping model behavior explicit and predictable.
+Use a dedicated [planner model](/docs/guides/context-engineering/creating-plans) for complex reasoning and keep your default model focused on execution. This gives you control over cost and quality while keeping model behavior explicit and predictable.
 
 ---
 

documentation/blog/2025-08-27-get-started-for-free-with-tetrate/index.md

@@ -55,7 +55,7 @@ Browse and select from a wide range of options, including:
 - **Specialized models** optimized for different use cases
 
 :::tip Protip 
- Want the best of both worlds? Use a dedicated [planner model](/docs/guides/creating-plans) for complex strategy and a faster default model for execution. Pair this with `/plan` to get strong reasoning only when you need it—saving both time and credits.
+ Want the best of both worlds? Use a dedicated [planner model](/docs/guides/context-engineering/creating-plans) for complex strategy and a faster default model for execution. Pair this with `/plan` to get strong reasoning only when you need it—saving both time and credits.
 :::
 
 ---

documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md

@@ -7,7 +7,7 @@ authors:
 
 ![Subagents vs Subrecipes](subrecipes-vs-subagents.png)
 
-When you're working on complex projects with goose, you'll often need to break work into multiple tasks and run them with AI agents. Goose gives you two powerful ways to do this: [subagents](/docs/guides/subagents/) and [subrecipes](/docs/tutorials/subrecipes-in-parallel/). Both can run multiple AI instances in parallel, but they work  differently. Picking which one to use can be confusing, so we're going to guide you to a decision.
+When you're working on complex projects with goose, you'll often need to break work into multiple tasks and run them with AI agents. Goose gives you two powerful ways to do this: [subagents](/docs/guides/context-engineering/subagents/) and [subrecipes](/docs/tutorials/subrecipes-in-parallel/). Both can run multiple AI instances in parallel, but they work  differently. Picking which one to use can be confusing, so we're going to guide you to a decision.
 
 I've been using both approaches, and the choice between them depends on what you're trying to accomplish. Let me break down when to use each method and show you real examples.
 

documentation/blog/2025-12-19-does-your-ai-agent-need-a-plan/index.md

@@ -30,13 +30,13 @@ Rather than picking one philosophy, [goose](https://github.com/aaif-goose/goose)
 ### For The Architect
 **`/plan` Mode**
 
-When you enter [plan mode](/docs/guides/creating-plans) in the goose CLI, goose shifts into an interactive dialogue. Instead of immediately executing, it asks clarifying questions to understand your project deeply. It might ask about your tech stack preferences, authentication requirements, deployment targets, or how you want to handle error cases. This back and forth continues until goose has enough context to generate a comprehensive, actionable plan.
+When you enter [plan mode](/docs/guides/context-engineering/creating-plans) in the goose CLI, goose shifts into an interactive dialogue. Instead of immediately executing, it asks clarifying questions to understand your project deeply. It might ask about your tech stack preferences, authentication requirements, deployment targets, or how you want to handle error cases. This back and forth continues until goose has enough context to generate a comprehensive, actionable plan.
 
 Plan mode uses a separate planner configuration that you can customize. By setting **`GOOSE_PLANNER_PROVIDER`** and **`GOOSE_PLANNER_MODEL`** [environment variables](/docs/guides/environment-variables), you can use one model for strategic planning and a different model for execution. When you're satisfied with the plan, goose asks if you want to clear the message history and act on it, giving you a clear checkpoint before any code changes happen.
 
 I used this approach recently when converting a static Vite/React project to Next.js. I understood the scope clearly since it's a common migration pattern, so I asked goose to make a comprehensive plan before starting any work. It produced an 11 phase migration plan with specific checkboxes for each step, covering everything from dependency updates to routing changes to component boundaries. Once I approved, I said "yes start" and goose executed methodically, committing after each phase.
 
-[Learn more about creating plans →](/docs/guides/creating-plans)
+[Learn more about creating plans →](/docs/guides/context-engineering/creating-plans)
 
 ### For The Director
 **Instruction Files**

documentation/blog/2026-02-19-gastown-explained-goosetown/index.md

@@ -69,7 +69,7 @@ Here's a real Town Wall snippet from a session where parallel researchers conver
 * **[10:14] researcher-endpoints** - 💡 Found: native endpoint already exists with minimal deps. Alternative path viable.   
 * **[10:15] researcher-source** - ✅ Done. Confirmed: native path requires zero new dependencies. Recommending pivot.
 
-Goosetown operates on 4 components: [skills](/docs/guides/context-engineering/using-skills), [subagents](/docs/guides/subagents), [beads](https://github.com/steveyegge/beads), and a [gtwall](https://github.com/aaif-goose/goosetown/blob/main/gtwall).
+Goosetown operates on 4 components: [skills](/docs/guides/context-engineering/using-skills), [subagents](/docs/guides/context-engineering/subagents), [beads](https://github.com/steveyegge/beads), and a [gtwall](https://github.com/aaif-goose/goosetown/blob/main/gtwall).
 
 ### Skills
 
@@ -77,7 +77,7 @@ Goosetown operates on 4 components: [skills](/docs/guides/context-engineering/us
 
 ### Subagents
 
-Instead of doing everything in one long conversation that eventually hits a "context cliff," Goosetown uses [subagents](/docs/guides/subagents), ephemeral agent instances. These are triggered by the [summon extension](/docs/mcp/summon-mcp), using `delegate()` to hand off work to a fresh agent instance. They do the work in their own clean context and return a summary, keeping your main session fast and focused.
+Instead of doing everything in one long conversation that eventually hits a "context cliff," Goosetown uses [subagents](/docs/guides/context-engineering/subagents), ephemeral agent instances. These are triggered by the [summon extension](/docs/mcp/summon-mcp), using `delegate()` to hand off work to a fresh agent instance. They do the work in their own clean context and return a summary, keeping your main session fast and focused.
 
 ### Beads
 

documentation/blog/2026-05-04-officeqa-minimax-m25/index.md

@@ -7,6 +7,8 @@ authors:
 
 Quick highlight: [Sentient AGI](https://x.com/SentientAGI/status/2046967422004154739) recently shared with us some results with a challenge called "Grounded Reasoning" where teams tackled the Databricks OfficeQA benchmark using the MiniMax (2.5) open model.
 
+<!-- truncate -->
+
 Highlights from the linked article:
 
 > * Using goose with [MiniMax M2.5](https://www.minimax.io/) on the [OfficeQA benchmark from Databricks](https://www.databricks.com/blog/officeqa), we're seeing results approaching frontier model performance for **1/30th of the cost**.

documentation/blog/2026-05-05-goose-as-conductor/index.md

@@ -16,7 +16,7 @@ That's what orchestration gives you. Instead of feeding goose one task at a time
 
 ## What is orchestration?
 
-If you've used [subagents](/docs/guides/subagents) before, you already know how to delegate work to independent AI instances. Orchestration is the layer above that — the part that decides _who_ does _what_ and _when_. Instead of one goose session doing everything sequentially, orchestration lets you:
+If you've used [subagents](/docs/guides/context-engineering/subagents) before, you already know how to delegate work to independent AI instances. Orchestration is the layer above that — the part that decides _who_ does _what_ and _when_. Instead of one goose session doing everything sequentially, orchestration lets you:
 
 - **Decompose** a complex task into independent subtasks
 - **Delegate** each subtask to a separate agent (subagent, ACP provider, or another goose instance)
@@ -43,7 +43,7 @@ Orchestration doesn't replace subagents or subrecipes — it builds on them:
 
 | Layer | What it does |
 |-------|-------------|
-| [Subagents](/docs/guides/subagents) (delegate) | Spin up independent sub-tasks |
+| [Subagents](/docs/guides/context-engineering/subagents) (delegate) | Spin up independent sub-tasks |
 | Async delegates | Run subagents in the background, collect results later |
 | [ACP providers](/docs/guides/acp-providers) | Bring in external agents (Claude Code, Codex, Amp) |
 | **Orchestration** | Coordinate all of the above into structured workflows |

documentation/docs/getting-started/using-extensions.md

@@ -28,7 +28,7 @@ goose includes several built-in extensions you can start using out of the box:
 - [Auto Visualiser](/docs/mcp/autovisualiser-mcp): Automatically generates graphical data visualizations in conversations.
 
 :::warning Access Control
-goose operates autonomously by default. Combined with the Developer extension's tools, this means goose can execute commands and modify files without your approval. If you want more control over this behavior, you can configure the [goose permission mode](/docs/guides/goose-permissions), [tool permissions](/docs/guides/managing-tools/tool-permissions), and [.gooseignore files](/docs/guides/using-gooseignore). See [Configuring Access Controls](/docs/mcp/developer-mcp#configuring-access-controls) for a brief overview.
+goose operates autonomously by default. Combined with the Developer extension's tools, this means goose can execute commands and modify files without your approval. If you want more control over this behavior, you can configure the [goose permission mode](/docs/guides/managing-tools/goose-permissions), [tool permissions](/docs/guides/managing-tools/tool-permissions), and [.gooseignore files](/docs/guides/context-engineering/using-gooseignore). See [Configuring Access Controls](/docs/mcp/developer-mcp#configuring-access-controls) for a brief overview.
 :::
 
 ### Built-in Platform Extensions

documentation/docs/guides/acp-providers.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 46
+sidebar_position: 9
 title: ACP Providers
 sidebar_label: ACP Providers
 description: Use ACP agents like Claude Code and Codex as goose providers with extension support

documentation/docs/guides/cli-providers.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 45
+sidebar_position: 8
 title: CLI Providers
 sidebar_label: CLI Providers
 description: Use Claude Code, Codex, Cursor Agent, or Gemini CLI subscriptions in goose

documentation/docs/guides/codebase-analysis.md

@@ -114,10 +114,10 @@ If the analysis results exceed 1000 lines, the tool returns a warning message in
 - **Use `force=true`** to bypass the warning and see the full output (may consume significant conversation context)
 - **Narrow your scope** by analyzing a specific subdirectory or file
 - **Reduce depth** with `max_depth=1` or `max_depth=2` for directories
-- **Delegate to a [subagent](/docs/guides/subagents)** to analyze and summarize without filling your conversation history, for example: "Use a subagent to analyze the entire src/ directory and summarize the main components"
+- **Delegate to a [subagent](/docs/guides/context-engineering/subagents)** to analyze and summarize without filling your conversation history, for example: "Use a subagent to analyze the entire src/ directory and summarize the main components"
 
 ### Performance Tips
 
 - Start with smaller scopes (specific files or subdirectories) before analyzing entire projects
 - Use `max_depth=1` or `max_depth=2` to limit directory traversal depth
-- Use [`.gooseignore`](/docs/guides/using-gooseignore) and `.gitignore` files to exclude unnecessary files from analysis (like `node_modules/`, build artifacts, or sensitive files)
+- Use [`.gooseignore`](/docs/guides/context-engineering/using-gooseignore) and `.gitignore` files to exclude unnecessary files from analysis (like `node_modules/`, build artifacts, or sensitive files)

documentation/docs/guides/config-files.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 85
+sidebar_position: 10
 title: Configuration Files
 sidebar_label: Configuration Files
 ---
@@ -19,7 +19,7 @@ The configuration files allow you to set default behaviors, configure language m
 - **permission.yaml** - Tool permission levels configured via `goose configure`
 - **secrets.yaml** - API keys and secrets (when goose is using [file-based secret storage](#security-considerations))
 - **permissions/tool_permissions.json** - Runtime permission decisions (auto-managed)
-- **prompts/** - Customized [prompt templates](/docs/guides/prompt-templates)
+- **prompts/** - Customized [prompt templates](/docs/guides/context-engineering/prompt-templates)
 
 In addition to editing configuration files directly, many settings can be managed from goose Desktop and goose CLI:
 - **goose Desktop**: From the `Settings` page and the bottom toolbar
@@ -35,9 +35,9 @@ The following settings can be configured at the root level of your config.yaml f
 | `GOOSE_MODEL` | Default model to use | Model name (e.g., "claude-3.5-sonnet", "gpt-4") | None | Yes |
 | `GOOSE_TEMPERATURE` | Model response randomness | Float between 0.0 and 1.0 | Model-specific | No |
 | `GOOSE_MAX_TOKENS` | Maximum number of tokens for each model response (truncates longer responses) | Positive integer | Model-specific | No |
-| `GOOSE_MODE` | [Tool execution behavior](/docs/guides/goose-permissions) | "auto", "approve", "chat", "smart_approve" | "auto" | No |
+| `GOOSE_MODE` | [Tool execution behavior](/docs/guides/managing-tools/goose-permissions) | "auto", "approve", "chat", "smart_approve" | "auto" | No |
 | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 | No |
-| `GOOSE_PLANNER_PROVIDER` | Provider for [planning mode](/docs/guides/creating-plans) | Same as `GOOSE_PROVIDER` options | Falls back to `GOOSE_PROVIDER` | No |
+| `GOOSE_PLANNER_PROVIDER` | Provider for [planning mode](/docs/guides/context-engineering/creating-plans) | Same as `GOOSE_PROVIDER` options | Falls back to `GOOSE_PROVIDER` | No |
 | `GOOSE_PLANNER_MODEL` | Model for planning mode | Model name | Falls back to `GOOSE_MODEL` | No |
 | `GOOSE_TOOLSHIM` | Enable tool interpretation | true/false | false | No |
 | `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Model for tool interpretation | Model name (e.g., "llama3.2") | System default | No |

documentation/docs/guides/context-engineering/creating-plans.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 87
+sidebar_position: 2
 title: Creating Plans Before Working
 sidebar_label: Creating Plans
 ---
@@ -39,7 +39,7 @@ You can combine planning mode with a different default execution model to balanc
 :::
 
 :::tip Customize Plan Format
-You can also customize how goose creates plans by editing the `plan.md` [prompt template](/docs/guides/prompt-templates).
+You can also customize how goose creates plans by editing the `plan.md` [prompt template](/docs/guides/context-engineering/prompt-templates).
 :::
 
 ### Set goose planner environment variables

documentation/docs/guides/context-engineering/hooks.md

@@ -1,6 +1,6 @@
 ---
 title: Hooks
-sidebar_position: 4
+sidebar_position: 5
 sidebar_label: Hooks
 ---
 
@@ -8,7 +8,7 @@ sidebar_label: Hooks
 
 Hooks let you run your own scripts when key events happen during a goose session. Use hooks to log activity, send notifications, format files after edits, run checks after shell commands, or integrate goose with local workflows without writing a custom extension.
 
-goose follows the [Open Plugins hooks specification](https://open-plugins.com/agent-builders/components/hooks). Hooks are discovered from plugins on disk and run as shell commands when matching lifecycle events fire.
+goose follows the [Open Plugins hooks specification](https://open-plugins.com/agent-builders/components/hooks). Hooks are discovered from [plugins](/docs/guides/context-engineering/plugins) on disk and run as shell commands when matching lifecycle events fire.
 
 :::warning Run trusted hooks only
 Hooks execute local commands on your machine. Only install or create hooks from sources you trust, and review hook scripts before enabling them.
@@ -16,7 +16,7 @@ Hooks execute local commands on your machine. Only install or create hooks from
 
 ## Where Hooks Live
 
-A hook belongs to a plugin directory. goose discovers plugins from these locations:
+A hook belongs to a [plugin](/docs/guides/context-engineering/plugins) directory. goose discovers plugins from these locations:
 
 | Scope | Location |
 |---|---|

documentation/docs/guides/context-engineering/index.mdx

@@ -25,15 +25,45 @@ import styles from '@site/src/components/Card/styles.module.css';
       description="Create reusable instruction sets containing workflows, scripts, and other resources that goose can load on demand."
       link="/docs/guides/context-engineering/using-skills"
     />
+    <Card 
+      title="Plugins"
+      description="Install, update, and manage packages that extend goose with skills, hooks, and other reusable components."
+      link="/docs/guides/context-engineering/plugins"
+    />
+    <Card 
+      title="Hooks"
+      description="Run scripts when goose starts sessions, submits prompts, calls tools, edits files, or executes shell commands."
+      link="/docs/guides/context-engineering/hooks"
+    />
     <Card 
       title="Custom Slash Commands"
       description="Create custom shortcuts to quickly run reusable instructions in any chat session with simple slash commands."
       link="/docs/guides/context-engineering/slash-commands"
     />
+    <Card 
+      title="Prompt Templates"
+      description="Customize the built-in prompts that define how goose responds, plans, compacts context, and creates recipes."
+      link="/docs/guides/context-engineering/prompt-templates"
+    />
+    <Card 
+      title="Subagents"
+      description="Delegate focused tasks to isolated goose instances that can run sequentially or in parallel."
+      link="/docs/guides/context-engineering/subagents"
+    />
+    <Card 
+      title="Using gooseignore"
+      description="Prevent goose from accessing sensitive files and directories by defining global or project-specific ignore rules."
+      link="/docs/guides/context-engineering/using-gooseignore"
+    />
+    <Card 
+      title="Creating Plans"
+      description="Use planning mode to break complex work into clear, manageable steps before goose starts implementation."
+      link="/docs/guides/context-engineering/creating-plans"
+    />
     <Card 
       title="Persistent Instructions"
       description="Inject critical reminders into goose's working memory every turn. Ideal for security guardrails and behavioral rules that must never be forgotten."
-      link="/docs/guides/using-persistent-instructions"
+      link="/docs/guides/context-engineering/using-persistent-instructions"
     />
     <Card 
       title="Memory Extension"
@@ -66,5 +96,10 @@ import styles from '@site/src/components/Card/styles.module.css';
       description="Why do AI agents forget? Learn how context windows, tokens, and goose help you manage memory and long conversations."
       link="/blog/2025/08/18/understanding-context-windows"
     />
+    <Card
+      title="Hooks: run your own scripts on every goose event"
+      description="Learn how lifecycle hooks let you react to session, prompt, tool, file, and shell events with your own scripts."
+      link="/blog/2026/05/14/goose-hooks"
+    />
   </div>
 </div>

documentation/docs/guides/context-engineering/plugins.md

@@ -0,0 +1,216 @@
+---
+title: Plugins
+sidebar_position: 6
+sidebar_label: Plugins
+---
+
+# Plugins
+
+Plugins are packages that extend goose with reusable components. A plugin can provide [skills](/docs/guides/context-engineering/using-skills), [hooks](/docs/guides/context-engineering/hooks), or both.
+
+Use plugins when you want to install, share, or update a bundle of goose functionality instead of copying individual files into your local skills or hooks directories.
+
+:::warning Install trusted plugins only
+Plugins can include instructions that goose may load and hooks that execute local commands. Install plugins only from sources you trust, and review plugin contents before enabling them.
+:::
+
+## What Plugins Can Provide
+
+| Component | What it does |
+|---|---|
+| Skills | Reusable instructions and supporting files that teach goose how to perform a task or follow a workflow. |
+| Hooks | Local commands that run when lifecycle events happen during a goose session. |
+
+A plugin is the container. Skills and hooks are components inside that container.
+
+## Plugin Structure
+
+A plugin is a directory with a plugin manifest and optional component directories. A plugin that includes both skills and hooks can look like this:
+
+```text
+my-plugin/
+├── plugin.json
+├── skills/
+│   └── review/
+│       └── SKILL.md
+├── hooks/
+│   └── hooks.json
+└── scripts/
+    └── notify.sh
+```
+
+The plugin manifest identifies the plugin:
+
+```json title="plugin.json"
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "Reusable skills and hooks for my team"
+}
+```
+
+### Add a Skill to a Plugin
+
+To add a skill to a plugin, place a skill directory under the plugin's `skills/` directory. Each skill directory contains a `SKILL.md` file:
+
+```text
+my-plugin/
+└── skills/
+    └── review/
+        └── SKILL.md
+```
+
+```markdown title="skills/review/SKILL.md"
+---
+name: review
+description: Review code changes for correctness, maintainability, and test coverage
+---
+
+Review the code changes. Prioritize correctness issues, security concerns, missing tests, and maintainability risks. Be direct and suggest concrete fixes.
+```
+
+For Open Plugins, goose namespaces imported skill names with the plugin name. The `review` skill in `my-plugin` is loaded as `my-plugin:review`.
+
+### Add a Hook to a Plugin
+
+To add a hook to a plugin, create `hooks/hooks.json` and map lifecycle events to commands:
+
+```text
+my-plugin/
+├── hooks/
+│   └── hooks.json
+└── scripts/
+    └── notify.sh
+```
+
+```json title="hooks/hooks.json"
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/scripts/notify.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Hook commands receive the event payload as JSON on stdin. Use `${PLUGIN_ROOT}` to reference files inside the plugin directory.
+
+For supported events, payload details, and more hook examples, see the [Hooks guide](/docs/guides/context-engineering/hooks).
+
+## Plugin Locations
+
+goose discovers plugins from these locations:
+
+| Plugin type | Location | Notes |
+|---|---|---|
+| User plugin | `~/.agents/plugins/<plugin-name>/` | Includes plugins installed with `goose plugin install` and plugins manually copied into your user plugins directory. |
+| Project plugin | `<project>/.agents/plugins/<plugin-name>/` | Available when goose is working in that project. |
+
+Installed and manually placed user plugins use the same user plugins directory. Installed plugins include metadata created by `goose plugin install`; only installed git-backed plugins can be updated with `goose plugin update`.
+
+## Install a Plugin
+
+Install a plugin from a git repository with:
+
+```bash
+goose plugin install https://github.com/example/my-goose-plugin.git
+```
+
+The install command clones the repository, detects the plugin format, copies it into the plugins directory, and reports the imported components.
+
+Example output:
+
+```text
+✓ Installed open-plugins plugin 'my-plugin' (1.0.0)
+  Source: https://github.com/example/my-goose-plugin.git
+  Location: /Users/you/.agents/plugins/my-plugin
+  Imported skills:
+    - my-plugin:review
+    - my-plugin:test-plan
+```
+
+## Auto-Update a Plugin
+
+To let goose check a plugin for updates automatically, install it with `--auto-update`:
+
+```bash
+goose plugin install --auto-update https://github.com/example/my-goose-plugin.git
+```
+
+When auto-update is enabled, goose checks that plugin for updates before plugin skills are loaded. Auto-update checks are rate-limited, so goose does not clone the repository on every session start.
+
+If an auto-update fails, goose logs the failure and continues using the currently installed plugin.
+
+:::note
+Auto-update is available for git-backed plugins installed with `goose plugin install --auto-update`. Plugins copied manually into `.agents/plugins/` are discovered, but they are not managed by the plugin update command.
+:::
+
+## Update a Plugin Manually
+
+To update a git-backed plugin on demand, run:
+
+```bash
+goose plugin update <plugin-name>
+```
+
+For example:
+
+```bash
+goose plugin update my-plugin
+```
+
+The update command fetches the plugin from its original git source, replaces the installed copy, and preserves whether auto-update was enabled for that plugin.
+
+## Disable a Plugin
+
+To disable a plugin globally, add its name to `disabledPlugins` in your user goose settings file:
+
+```json title="~/.config/goose/settings.json"
+{
+  "disabledPlugins": ["my-plugin"]
+}
+```
+
+For project-specific settings, use:
+
+```text
+<project>/.config/goose/settings.json
+```
+
+For local-only project settings that should not be shared with teammates, use:
+
+```text
+<project>/.config/goose/settings.local.json
+```
+
+A disabled plugin is skipped during plugin discovery, so its skills are not loaded and its hooks do not run.
+
+## Plugin Formats
+
+goose supports these plugin formats:
+
+| Format | Common files | Notes |
+|---|---|---|
+| Open Plugins | `plugin.json`, `.plugin/plugin.json`, `.goose-plugin/plugin.json`, `skills/`, `hooks/hooks.json` | Supports Open Plugins skills and hooks. |
+| Gemini extensions | `gemini-extension.json`, `skills/` | Supports skills from Gemini-style extension repositories. |
+
+For Open Plugins, imported skill names are namespaced with the plugin name, such as `my-plugin:review`. Use that full name when explicitly loading a plugin-provided skill. Gemini extension skills keep the skill name from `SKILL.md`; goose does not prefix them with the extension name.
+
+Open Plugins can use `plugin.json` at the plugin root, `.plugin/plugin.json`, or `.goose-plugin/plugin.json`. Hook-only Open Plugins can be discovered from `hooks/hooks.json`; if no manifest is present, goose infers the plugin name from the source or directory name.
+
+## When to Use Plugins, Skills, or Hooks
+
+| Use | Best fit |
+|---|---|
+| Package and distribute reusable goose components | Plugin |
+| Teach goose a reusable procedure or domain-specific workflow | Skill |
+| Run a local command when goose session events happen | Hook |
+
+Plugins are for packaging and distribution. Skills and hooks define the behavior goose can use once the plugin is installed or discovered.

documentation/docs/guides/context-engineering/prompt-templates.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 86
+sidebar_position: 6
 title: Customizing Prompt Templates
 sidebar_label: Prompt Templates
 description: Learn how to customize the prompt templates that define goose's behavior in different situations

documentation/docs/guides/context-engineering/subagents.mdx

@@ -1,6 +1,6 @@
 ---
 title: Subagents
-sidebar_position: 50
+sidebar_position: 2
 sidebar_label: Subagents
 ---
 
@@ -24,7 +24,7 @@ Subagents are independent instances that execute tasks while keeping your main c
 ## How to Use Subagents
 
 :::tip Autonomous Subagent Creation
-goose can autonomously decide to use subagents when it determines they would be beneficial for your task - you don't always need to explicitly request them. This happens automatically in autonomous [permission mode](/docs/guides/goose-permissions) (the default). Subagents are disabled in manual approval, smart approval, and chat-only modes.
+goose can autonomously decide to use subagents when it determines they would be beneficial for your task - you don't always need to explicitly request them. This happens automatically in autonomous [permission mode](/docs/guides/managing-tools/goose-permissions) (the default). Subagents are disabled in manual approval, smart approval, and chat-only modes.
 :::
 
 To use subagents, ask goose to delegate tasks using natural language. goose automatically decides when to spawn subagents and handles their lifecycle. You can:
@@ -277,7 +277,7 @@ Subagents use the following pre-configured settings, but you can override any de
 | **Return Mode** | All subagent information provided in main session | Specify how much detail you want in your prompt |
 
 :::tip Advanced Customization
-You can also customize subagent behavior by editing the `subagent_system.md` [prompt template](/docs/guides/prompt-templates).
+You can also customize subagent behavior by editing the `subagent_system.md` [prompt template](/docs/guides/context-engineering/prompt-templates).
 :::
 
 ### Customizing Settings in Prompts

documentation/docs/guides/context-engineering/using-gooseignore.md

@@ -1,7 +1,7 @@
 ---
 title: Prevent goose from Accessing Files
 sidebar_label: Using gooseignore
-sidebar_position: 80
+sidebar_position: 9
 ---
 
 

documentation/docs/guides/context-engineering/using-persistent-instructions.md

@@ -1,6 +1,6 @@
 ---
 title: Persistent Instructions
-sidebar_position: 12
+sidebar_position: 8
 sidebar_label: Persistent Instructions
 ---
 

documentation/docs/guides/context-engineering/using-skills.md

@@ -1,7 +1,7 @@
 ---
-title: Using Skills
-sidebar_position: 2
-sidebar_label: Using Skills
+title: Agent Skills
+sidebar_position: 3
+sidebar_label: Agent Skills
 ---
 
 Skills are reusable sets of instructions and resources that teach goose how to perform specific tasks. A skill can range from a simple checklist to a detailed workflow with domain expertise, and can include supporting files like scripts or templates. Example use cases include deployment procedures, code review checklists, and API integration guides.
@@ -25,10 +25,11 @@ goose skills are compatible with Claude Desktop and other [agents that support A
 
 ## Skill Locations
 
-Skills can be stored globally or per-project:
+Skills can be stored globally, per-project, or in installed plugins:
 
 1. `~/.agents/skills/` — Global skills, available in all sessions
 2. `.agents/skills/` — Project-level skills, scoped to the current project
+3. `~/.agents/plugins/<plugin-name>/` — Skills provided by installed [plugins](/docs/guides/context-engineering/plugins)
 
 Place a `SKILL.md` file inside a named subdirectory. For example, a global skill called
 `code-review` goes in `~/.agents/skills/code-review/SKILL.md`.
@@ -84,7 +85,11 @@ When reviewing code, check each of these areas:
 - [ ] SQL queries are parameterized
 ```
 
-### Supporting Files
+## Skills from Plugins
+
+Skills can also come from installed [plugins](/docs/guides/context-engineering/plugins). Plugin-provided skills are discovered at session startup and work like other skills. For Open Plugins, skill names are namespaced with the plugin name, such as `my-plugin:review`. Use that full name when explicitly loading a plugin-provided skill.
+
+## Supporting Files
 
 Skills can include supporting files like scripts, templates, or configuration files. Place them in the skill directory:
 

documentation/docs/guides/desktop-navigation.md

@@ -1,5 +1,4 @@
 ---
-sidebar_position: 16
 title: Customizing the Sidebar
 sidebar_label: Customizing the Sidebar
 description: Personalize how you navigate goose Desktop by changing the sidebar's look, position, and behavior

documentation/docs/guides/environment-variables.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 95
+sidebar_position: 11
 title: Environment Variables
 sidebar_label: Environment Variables
 ---
@@ -164,7 +164,7 @@ To see Claude's thinking output in the **CLI**, you also need to set `GOOSE_CLI_
 
 ### Planning Mode Configuration
 
-These variables control goose's [planning functionality](/docs/guides/creating-plans).
+These variables control goose's [planning functionality](/docs/guides/context-engineering/creating-plans).
 
 | Variable | Purpose | Values | Default |
 |----------|---------|---------|---------|
@@ -228,8 +228,8 @@ These variables control how goose manages conversation sessions and context.
 |----------|---------|---------|---------|
 | `GOOSE_CONTEXT_STRATEGY` | Controls how goose handles context limit exceeded situations | "summarize", "truncate", "clear", "prompt" | "prompt" (interactive), "summarize" (headless) |
 | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 |
-| `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/subagents) to complete before timeout. Can be overridden by [`settings.max_turns`](/docs/guides/recipes/recipe-reference#settings) in recipes or subagent tool calls. | Integer (e.g., 25) | 25 |
-| `GOOSE_MAX_BACKGROUND_TASKS` | Sets the maximum number of concurrent background [subagent](/docs/guides/subagents) tasks goose can run at once | Integer (e.g., 1, 5, 10) | 5 |
+| `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/context-engineering/subagents) to complete before timeout. Can be overridden by [`settings.max_turns`](/docs/guides/recipes/recipe-reference#settings) in recipes or subagent tool calls. | Integer (e.g., 25) | 25 |
+| `GOOSE_MAX_BACKGROUND_TASKS` | Sets the maximum number of concurrent background [subagent](/docs/guides/context-engineering/subagents) tasks goose can run at once | Integer (e.g., 1, 5, 10) | 5 |
 | `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/context-engineering/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints"]` |
 | `GOOSE_DISABLE_SESSION_NAMING` | Disables automatic AI-generated session naming; avoids the background model call and keeps the default "CLI Session" (goose CLI) or "New Chat" (goose Desktop) | "1", "true" (case-insensitive) to enable | false |
 | `GOOSE_DISABLE_TOOL_CALL_SUMMARY` | Disables the per-tool-call AI-generated summary title, keeping the fallback title instead. Saves one provider call per tool invocation. | "1", "true" (case-insensitive) to enable | false |
@@ -243,8 +243,8 @@ These variables control how goose manages conversation sessions and context.
 | `GOOSE_CLI_SHOW_COST` | Toggles display of model cost estimates in CLI output | "1", "true" (case-insensitive) to enable | false |
 | `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically summarizes your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0) | 0.8 |
 | `GOOSE_TOOL_CALL_CUTOFF` | Number of tool calls to keep in full detail before summarizing older tool outputs to help maintain efficient context usage  | Integer (e.g., 5, 10, 20) | 10 |
-| `GOOSE_MOIM_MESSAGE_TEXT` | Injects persistent text into goose's [working memory](/docs/guides/using-persistent-instructions) every turn. Useful for behavioral guardrails or persistent reminders. | Any text string | Not set |
-| `GOOSE_MOIM_MESSAGE_FILE` | Path to a file whose contents are injected into goose's [working memory](/docs/guides/using-persistent-instructions) every turn. Supports `~/`. Max 64 KB per file. | File path | Not set |
+| `GOOSE_MOIM_MESSAGE_TEXT` | Injects persistent text into goose's [working memory](/docs/guides/context-engineering/using-persistent-instructions) every turn. Useful for behavioral guardrails or persistent reminders. | Any text string | Not set |
+| `GOOSE_MOIM_MESSAGE_FILE` | Path to a file whose contents are injected into goose's [working memory](/docs/guides/context-engineering/using-persistent-instructions) every turn. Supports `~/`. Max 64 KB per file. | File path | Not set |
 
 **Examples**
 
@@ -317,7 +317,7 @@ These variables allow you to override the default context window size (token lim
 |----------|---------|---------|---------|
 | `GOOSE_CONTEXT_LIMIT` | Override context limit for the main model | Integer (number of tokens) | Model-specific default or 128,000 |
 | `GOOSE_INPUT_LIMIT` | Override input prompt limit for ollama requests (maps to `num_ctx`) | Integer (number of tokens) | Falls back to `GOOSE_CONTEXT_LIMIT` or model default |
-| `GOOSE_PLANNER_CONTEXT_LIMIT` | Override context limit for the [planner model](/docs/guides/creating-plans) | Integer (number of tokens) | Falls back to `GOOSE_CONTEXT_LIMIT` or model default |
+| `GOOSE_PLANNER_CONTEXT_LIMIT` | Override context limit for the [planner model](/docs/guides/context-engineering/creating-plans) | Integer (number of tokens) | Falls back to `GOOSE_CONTEXT_LIMIT` or model default |
 
 **Examples**
 
@@ -335,7 +335,7 @@ For more details and examples, see [Model Context Limit Overrides](/docs/guides/
 
 ## Tool Configuration
 
-These variables control how goose handles [tool execution](/docs/guides/goose-permissions) and [tool management](/docs/guides/managing-tools/).
+These variables control how goose handles [tool execution](/docs/guides/managing-tools/goose-permissions) and [tool management](/docs/guides/managing-tools/).
 
 | Variable | Purpose | Values | Default |
 |----------|---------|---------|---------|

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 35
+sidebar_position: 7
 title: CLI Commands
 sidebar_label: CLI Commands
 toc_max_heading_level: 4
@@ -507,6 +507,30 @@ goose recipe help
 
 ---
 
+#### plugin
+Install and update git-backed plugins that provide skills or other Open Plugins components.
+
+**Commands:**
+- **`install [OPTIONS] <URL>`**: Install a plugin from a git repository URL
+  - **`--auto-update`**: Automatically check for updates before plugin skills are loaded
+- **`update <NAME>`**: Update an installed git-backed plugin by name
+
+**Usage:**
+```bash
+# Install a plugin from a git repository
+goose plugin install https://github.com/example/my-goose-plugin.git
+
+# Install a plugin and enable automatic update checks
+goose plugin install --auto-update https://github.com/example/my-goose-plugin.git
+
+# Update an installed plugin manually
+goose plugin update my-plugin
+```
+
+Installed plugins are stored under `~/.agents/plugins/<plugin-name>/`. For more about plugin-provided skills, hooks, and update behavior, see the [Plugins guide](/docs/guides/context-engineering/plugins).
+
+---
+
 #### schedule
 Automate recipes by running them on a [schedule](/docs/guides/recipes/session-recipes.md#schedule-recipe).
 

documentation/docs/guides/managing-projects.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 15
+sidebar_position: 5
 title: Managing Projects
 sidebar_label: Managing Projects
 ---

documentation/docs/guides/managing-tools/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Managing Tools",
-  "position": 15,
+  "position": 4,
   "link": {
     "type": "doc",
     "id": "guides/managing-tools/index"

documentation/docs/guides/managing-tools/index.md

@@ -15,6 +15,11 @@ import styles from '@site/src/components/Card/styles.module.css';
 <div className={styles.categorySection}>
   <h2 className={styles.categoryTitle}>📚 Documentation & Guides</h2>
   <div className={styles.cardGrid}>
+    <Card 
+      title="goose Permissions"
+      description="Choose how much autonomy goose has when using tools, editing files, and taking action in a session."
+      link="/docs/guides/managing-tools/goose-permissions"
+    />
     <Card 
       title="Tool Permissions"
       description="Configure fine-grained permissions to control which tools goose can use and when, ensuring secure and controlled automation."
@@ -25,11 +30,6 @@ import styles from '@site/src/components/Card/styles.module.css';
       description="Customize how tool interactions are displayed, from detailed verbose output to clean concise summaries."
       link="/docs/guides/managing-tools/adjust-tool-output"
     />
-    <Card 
-      title="Hooks"
-      description="Run scripts when goose starts sessions, submits prompts, calls tools, edits files, or executes shell commands."
-      link="/docs/guides/managing-tools/hooks"
-    />
     <Card 
       title="Code Mode"
       description="Programmatic approach that discovers and calls MCP tools on demand."
@@ -61,10 +61,6 @@ import styles from '@site/src/components/Card/styles.module.css';
       description="Technical deep-dive into the challenges of tool calling with open-source models and the research behind toolshim solutions."
       link="/blog/2025/04/11/finetuning-toolshim"
     />
-    <Card
-      title="Hooks: run your own scripts on every goose event"
-      description="Learn how lifecycle hooks let you react to session, prompt, tool, file, and shell events with your own scripts."
-      link="/blog/2026/05/14/goose-hooks"
-    />
+
   </div>
 </div>

documentation/docs/guides/managing-tools/tool-permissions.md

@@ -28,7 +28,7 @@ goose performs best with fewer than 25 total tools enabled across all extensions
 
 ## Permission Levels
 
-Tool permissions work alongside [goose permission modes](/docs/guides/goose-permissions). The mode sets the default behavior, while tool permissions let you override the behavior of specific tools.
+Tool permissions work alongside [goose permission modes](/docs/guides/managing-tools/goose-permissions). The mode sets the default behavior, while tool permissions let you override the behavior of specific tools.
 
 Each tool can be set to one of three permission levels:
 

documentation/docs/guides/multi-model/index.mdx

@@ -21,12 +21,12 @@ import VideoCarousel from '@site/src/components/VideoCarousel';
     <Card 
       title="Planner + Execution Model Setup"
       description="Use a dedicated planner model for strategic reasoning and a separate default model for execution."
-      link="/docs/guides/creating-plans"
+      link="/docs/guides/context-engineering/creating-plans"
     />
     <Card 
       title="Creating Plans Before Working"
       description="Manual planning mode that optionally uses a dedicated model to break complex projects into detailed, actionable steps."
-      link="/docs/guides/creating-plans"
+      link="/docs/guides/context-engineering/creating-plans"
     />
     <Card 
       title="Planning Complex Tasks"

documentation/docs/guides/recipes/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Recipes",
-  "position": 5,
+  "position": 3,
   "link": {
     "type": "doc",
     "id": "guides/recipes/index"

documentation/docs/guides/recipes/session-recipes.md

@@ -181,7 +181,7 @@ You can turn your current goose session into a reusable recipe that includes the
 </Tabs>
 
 :::tip Customize Recipe Generation
-You can customize how goose generates recipes by editing the `recipe.md` [prompt template](/docs/guides/prompt-templates).
+You can customize how goose generates recipes by editing the `recipe.md` [prompt template](/docs/guides/context-engineering/prompt-templates).
 :::
 
 ## Edit Recipe

documentation/docs/guides/security/adversary-mode.md

@@ -85,4 +85,4 @@ Some tool names you might want to add:
 ## See Also
 
 - [Prompt Injection Detection](/docs/guides/security/prompt-injection-detection) — pattern-based detection (complementary, always-on when enabled)
-- [goose Permission Modes](/docs/guides/goose-permissions) — control goose's autonomy level
+- [goose Permission Modes](/docs/guides/managing-tools/goose-permissions) — control goose's autonomy level

documentation/docs/guides/security/prompt-injection-detection.md

@@ -128,5 +128,5 @@ If you want to run your own classification endpoint, see the [Classification API
 
 ## See Also
 
-- [goose Permission Modes](/docs/guides/goose-permissions) - Control goose's autonomy level
+- [goose Permission Modes](/docs/guides/managing-tools/goose-permissions) - Control goose's autonomy level
 - [Managing Tool Permissions](/docs/guides/managing-tools/tool-permissions) - Fine-grained tool control

documentation/docs/guides/sessions/in-session-actions.md

@@ -333,7 +333,7 @@ You can change some settings during a session and they will take effect immediat
   | **Working Directory** | <FolderDot className="inline" size={16} /> directory switcher | New sessions (after restart) |
   | [**Enabled Extensions**](/docs/getting-started/using-extensions#change-extensions-mid-session) | <Puzzle className="inline" size={16} /> icon | Current session only |
   | [**Model**](/docs/getting-started/providers#configure-provider-and-model) | <Bot className="inline" size={16} /> model switcher | New sessions |
-  | [**goose Mode**](/docs/guides/goose-permissions#configuring-goose-mode) | <Tornado className="inline" size={16} /> mode switcher | New sessions |
+  | [**goose Mode**](/docs/guides/managing-tools/goose-permissions#configuring-goose-mode) | <Tornado className="inline" size={16} /> mode switcher | New sessions |
 
   </TabItem>
   <TabItem value="cli" label="goose CLI">
@@ -343,7 +343,7 @@ You can change some settings during a session and they will take effect immediat
   | Setting | Slash Command | Persistence* |
   |---------|--------------|-------------|
   | [**Enabled Extensions**](/docs/getting-started/using-extensions#change-extensions-mid-session) | `/extension` or `/builtin` | Current session only |
-  | [**goose Mode**](/docs/guides/goose-permissions#configuring-goose-mode) | `/mode [options]` | New sessions |
+  | [**goose Mode**](/docs/guides/managing-tools/goose-permissions#configuring-goose-mode) | `/mode [options]` | New sessions |
 
   :::info
   The CLI supports [additional slash commands](/docs/guides/goose-cli-commands#slash-commands) but doesn't support mid-session changes to the working directory or model.

documentation/docs/guides/sessions/smart-context-management.md

@@ -42,7 +42,7 @@ When you reach the auto-compaction threshold:
   3. Continue the session. Your previous conversation remains visible, but only the compacted conversion is included in the active context for goose.
 
 :::tip Customize Compaction
-You can customize how goose summarizes conversations during compaction by editing the `compaction.md` [prompt template](/docs/guides/prompt-templates).
+You can customize how goose summarizes conversations during compaction by editing the `compaction.md` [prompt template](/docs/guides/context-engineering/prompt-templates).
 :::
 
 :::tip Tool Output Summarization
@@ -293,7 +293,7 @@ Context limits are automatically detected based on your model name, but goose pr
 | Model | Description | Best For | Setting |
 |-------|-------------|----------|---------|
 | **Main** | Set context limit for the main model (also serves as fallback for other models) | LiteLLM proxies, custom models with non-standard names | `GOOSE_CONTEXT_LIMIT` |
-| **Planner** | Set context for [planner models](/docs/guides/creating-plans) | Large planning tasks requiring extensive context | `GOOSE_PLANNER_CONTEXT_LIMIT` |
+| **Planner** | Set context for [planner models](/docs/guides/context-engineering/creating-plans) | Large planning tasks requiring extensive context | `GOOSE_PLANNER_CONTEXT_LIMIT` |
 
 :::info
 This setting only affects the displayed token usage and progress indicators. Actual context management is handled by your LLM, so you may experience more or less usage than the limit you set, regardless of what the display shows.

documentation/docs/guides/tanzu-ai-services.md

@@ -1,5 +1,4 @@
 ---
-sidebar_position: 15
 title: VMware Tanzu Platform
 description: Connect goose to VMware Tanzu Platform AI Services
 ---

documentation/docs/guides/tips.md

@@ -15,7 +15,7 @@ You don't need fancy language or special syntax to prompt goose. Talk with goose
 goose's capabilities are extensible. As an [MCP](https://modelcontextprotocol.io/) client, goose can connect to your apps and services through [extensions](/extensions), allowing it to work across your entire workflow.
 
 ### Choose how much control goose has
-You can customize how much [supervision](/docs/guides/goose-permissions) goose needs. Choose between full autonomy, requiring approval before actions, or simply chatting without any actions.
+You can customize how much [supervision](/docs/guides/managing-tools/goose-permissions) goose needs. Choose between full autonomy, requiring approval before actions, or simply chatting without any actions.
 
 ### Choose the right LLM
 Your experience with goose is shaped by your [choice of LLM](/blog/2025/03/31/goose-benchmark), as it handles all the planning while goose manages the execution. When choosing an LLM, consider its tool support, specific capabilities, and associated costs.
@@ -37,7 +37,7 @@ Consider enabling [Code Mode](/docs/guides/managing-tools/code-mode), an alterna
 Help goose remember how you like to work by using [`.goosehints` or other context files](/docs/guides/context-engineering/using-goosehints) or [skills](/docs/guides/context-engineering/using-skills) for permanent project preferences and the [Memory extension](/docs/mcp/memory-mcp) for things you want goose to dynamically recall later. Both can help save valuable context window space while keeping your preferences available.
 
 ### Protect sensitive files
-goose is often eager to make changes. You can stop it from changing specific files by creating a [.gooseignore](/docs/guides/using-gooseignore) file. In this file, you can list all the file paths you want it to avoid.
+goose is often eager to make changes. You can stop it from changing specific files by creating a [.gooseignore](/docs/guides/context-engineering/using-gooseignore) file. In this file, you can list all the file paths you want it to avoid.
 
 ### Version Control
 Commit your code changes early and often. This allows you to rollback any unexpected changes.
@@ -58,7 +58,7 @@ goose Desktop lets you [customize the sidebar](/docs/guides/desktop-navigation)
 Regularly [update](/docs/guides/updating-goose) goose to benefit from the latest features, bug fixes, and performance improvements.
 
 ### Use a Dedicated Planner Model
-Use [planning mode](/docs/guides/creating-plans) with a dedicated planner model for complex reasoning, while keeping a faster default model for everyday execution.
+Use [planning mode](/docs/guides/context-engineering/creating-plans) with a dedicated planner model for complex reasoning, while keeping a faster default model for everyday execution.
 
 ### Make Recipes Safe to Re-run
 Write [recipes](/docs/guides/recipes/session-recipes) that check your current state before acting, so they can be run multiple times without causing any errors or duplication. 

documentation/docs/guides/updating-goose.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 25
+sidebar_position: 6
 title: Updating goose
 sidebar_label: Updating goose
 ---

documentation/docs/mcp/developer-mcp.md

@@ -193,7 +193,7 @@ The Developer extension provides these tools:
 
 You can layer multiple controls to match your risk tolerance and workflow:
 
-- **[goose Permission Modes](/docs/guides/goose-permissions)** control when goose asks for approval:
+- **[goose Permission Modes](/docs/guides/managing-tools/goose-permissions)** control when goose asks for approval:
 
   | Mode | Description | Use Cases |
   |------|-------------|-----------|
@@ -204,7 +204,7 @@ You can layer multiple controls to match your risk tolerance and workflow:
 
 - **[Tool Permissions](/docs/guides/managing-tools/tool-permissions)** let you set `Always allow`, `Ask before`, and `Never allow` permissions for individual extension tools when in Manual Approval or Smart Approval modes
 
-- **[.gooseignore files](/docs/guides/using-gooseignore)** restrict which files and directories goose can access (`.gitignore` files are fallback)
+- **[.gooseignore files](/docs/guides/context-engineering/using-gooseignore)** restrict which files and directories goose can access (`.gitignore` files are fallback)
 
 :::tip Changing Modes In-Session
 You can change goose permission modes during a session without restarting:
@@ -218,13 +218,13 @@ You might want more control over goose's operations when working with sensitive
 
 Here's an example configuration that enables oversight:
 
-1. **Set the [permission mode](/docs/guides/goose-permissions)** to Smart Approval or Manual Approval:
+1. **Set the [permission mode](/docs/guides/managing-tools/goose-permissions)** to Smart Approval or Manual Approval:
    ```yaml
    # ~/.config/goose/config.yaml
    GOOSE_MODE: smart_approve  # or approve
    ```
 
-2. **Create a [`.gooseignore` file](/docs/guides/using-gooseignore)** in your project to protect sensitive files:
+2. **Create a [`.gooseignore` file](/docs/guides/context-engineering/using-gooseignore)** in your project to protect sensitive files:
    ```
    .env*
    secrets.*

documentation/docs/mcp/summon-mcp.md

@@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem';
 import { PlatformExtensionNote } from '@site/src/components/PlatformExtensionNote';
 import GooseBuiltinInstaller from '@site/src/components/GooseBuiltinInstaller';
 
-The Summon extension lets you load knowledge into goose's context and delegate tasks to [subagents](/docs/guides/subagents). 
+The Summon extension lets you load knowledge into goose's context and delegate tasks to [subagents](/docs/guides/context-engineering/subagents). 
 
 You can load different types of sources:
 - [**Skills**](/docs/guides/context-engineering/using-skills) - Reusable instruction sets that teach goose specific workflows

documentation/docs/mcp/tom-mcp.md

@@ -16,7 +16,7 @@ The Top Of Mind extension injects custom text into goose's working memory every
 Unlike system prompts or [goosehints](/docs/guides/context-engineering/using-goosehints) which can fade from attention as conversations grow, content injected by the tom extension appears fresh in every turn, making it more reliable for critical instructions.
 
 :::tip
-For a complete guide on use cases and best practices, see [Persistent Instructions](/docs/guides/using-persistent-instructions).
+For a complete guide on use cases and best practices, see [Persistent Instructions](/docs/guides/context-engineering/using-persistent-instructions).
 :::
 
 ## Configuration

documentation/docs/tutorials/plan-feature-devcontainer-setup.md

@@ -10,7 +10,7 @@ description: "Learn how to use goose's Plan feature to break down complex tasks
 
 Using goose for large, complex tasks can feel overwhelming, especially when you're unsure of exactly how you want to approach it in advance. I experienced this when I needed to set up a complex development environment for an [API course](https://github.com/LinkedInLearning/java-automated-api-testing-with-rest-assured-5989068) I published. Between Docker configurations, database initialization, devcontainer setup, and GitHub Codespaces integration, there are dozens of moving pieces that need to work together perfectly. One missing configuration or incorrect dependency can derail the entire process.
 
-This tutorial shows you how to use goose's [Plan feature](/docs/guides/creating-plans) to transform a complex devcontainer setup into a systematic, executable roadmap. You'll learn how to brainstorm with goose, refine your requirements, and let goose create both a detailed plan and implementation checklist.
+This tutorial shows you how to use goose's [Plan feature](/docs/guides/context-engineering/creating-plans) to transform a complex devcontainer setup into a systematic, executable roadmap. You'll learn how to brainstorm with goose, refine your requirements, and let goose create both a detailed plan and implementation checklist.
 
 ## What You'll Learn
 
@@ -452,6 +452,6 @@ The key is treating goose as a planning partner, not just a code generator. Give
 - Try this approach with your own complex setup challenges
 - Experiment with different types of planning prompts
 - Share your planning successes with the [goose community](https://discord.gg/goose-oss)
-- Explore how planning integrates with [Subagents](/docs/guides/subagents) for even more sophisticated workflows
+- Explore how planning integrates with [Subagents](/docs/guides/context-engineering/subagents) for even more sophisticated workflows
 
 Remember, the goal is to get the right approach, in the right order, with the right safeguards. That's what makes the difference between a quick fix and a robust, maintainable solution.

documentation/docs/tutorials/subagents.md

@@ -8,7 +8,7 @@ image: /assets/images/tutorial-using-subagents-ef265627024db73e73d80e5799ed0c1a.
 ![](/img/tutorial-using-subagents.png)
 </div>
 
-This tutorial walks you through how to spin up a team of AI [subagents](/docs/guides/subagents/) and guide them through building a fully functional app.
+This tutorial walks you through how to spin up a team of AI [subagents](/docs/guides/context-engineering/subagents/) and guide them through building a fully functional app.
 
 You'll build **AI BriefMe**, an app that generates a structured executive style briefing based on any topic. 
 

documentation/docusaurus.config.ts

@@ -11,6 +11,13 @@ const inkeepApiKey = process.env.INKEEP_API_KEY;
 const inkeepIntegrationId = process.env.INKEEP_INTEGRATION_ID;
 const inkeepOrgId = process.env.INKEEP_ORG_ID;
 
+type SidebarItem = {
+  type?: string;
+  label?: string;
+  items?: SidebarItem[];
+  [key: string]: unknown;
+};
+
 const config: Config = {
   title: "goose | Your open source AI agent",
   tagline: "your local AI agent, automating engineering tasks seamlessly",
@@ -61,6 +68,48 @@ const config: Config = {
       {
         docs: {
           sidebarPath: "./sidebars.ts",
+          async sidebarItemsGenerator(args) {
+            const items = await args.defaultSidebarItemsGenerator(args);
+
+            const contextEngineeringItems = [
+              {
+                type: "doc" as const,
+                id: "mcp/memory-mcp",
+                label: "Memory Extension",
+              },
+              {
+                type: "doc" as const,
+                id: "tutorials/rpi",
+                label: "Research → Plan → Implement",
+              },
+            ];
+
+            const addItemsToCategory = (
+              sidebarItems: SidebarItem[],
+              categoryLabel: string,
+              extraItems: SidebarItem[],
+            ) => {
+              for (const item of sidebarItems) {
+                if (item.type === "category" && item.label === categoryLabel) {
+                  item.items.push(...extraItems);
+                  return true;
+                }
+
+                if (
+                  item.type === "category" &&
+                  addItemsToCategory(item.items, categoryLabel, extraItems)
+                ) {
+                  return true;
+                }
+              }
+
+              return false;
+            };
+
+            addItemsToCategory(items, "Context Engineering", contextEngineeringItems);
+
+            return items;
+          },
         },
         blog: {
           showReadingTime: true,
@@ -178,16 +227,48 @@ const config: Config = {
           },
           {
             from: "/docs/guides/multi-model/creating-plans",
-            to: "/docs/guides/creating-plans",
+            to: "/docs/guides/context-engineering/creating-plans",
+          },
+          {
+            from: "/docs/guides/creating-plans",
+            to: "/docs/guides/context-engineering/creating-plans",
+          },
+          {
+            from: "/docs/guides/using-gooseignore",
+            to: "/docs/guides/context-engineering/using-gooseignore",
           },
           {
             from: "/docs/guides/config-file",
             to: "/docs/guides/config-files",
           },
+          {
+            from: "/docs/guides/using-persistent-instructions",
+            to: "/docs/guides/context-engineering/using-persistent-instructions",
+          },
+          {
+            from: "/docs/guides/subagents",
+            to: "/docs/guides/context-engineering/subagents",
+          },
+          {
+            from: "/docs/guides/prompt-templates",
+            to: "/docs/guides/context-engineering/prompt-templates",
+          },
+          {
+            from: "/docs/guides/goose-permissions",
+            to: "/docs/guides/managing-tools/goose-permissions",
+          },
           {
             from: "/docs/guides/using-goosehints",
             to: "/docs/guides/context-engineering/using-goosehints",
           },
+          {
+            from: "/docs/guides/managing-tools/hooks",
+            to: "/docs/guides/context-engineering/hooks",
+          },
+          {
+            from: "/docs/guides/managing-tools/plugins",
+            to: "/docs/guides/context-engineering/plugins",
+          },
           // MCP tutorial redirects - moved from /docs/tutorials/ to /docs/mcp/
           {
             from: "/docs/tutorials/agentql-mcp",
@@ -331,11 +412,11 @@ const config: Config = {
           },
           {
             from: "/docs/experimental/subagents",
-            to: "/docs/guides/subagents",
+            to: "/docs/guides/context-engineering/subagents",
           },
           {
             from: "/docs/tutorials/lead-worker",
-            to: "/docs/guides/creating-plans",
+            to: "/docs/guides/context-engineering/creating-plans",
           },
         ],
       },

documentation/src/pages/index.tsx

@@ -170,7 +170,7 @@ function FeaturesSection() {
             description={
               <p>
                 Spawn independent{" "}
-                <Link to="/docs/guides/subagents">subagents</Link> to handle
+                <Link to="/docs/guides/context-engineering/subagents">subagents</Link> to handle
                 tasks in parallel — code review, research, file processing —
                 keeping the main conversation clean.
               </p>