Add configurable GOOSE_DOCS_ROOT for air-gapped docs access (#10294)

documentation/docs/guides/config-files.md

@@ -61,6 +61,7 @@ The following settings can be configured at the root level of your config.yaml f
 | `GOOSE_CLI_DARK_THEME` | Custom syntax highlighting theme for dark mode | [bat theme name](https://github.com/sharkdp/bat#adding-new-themes) | "zenburn" | No |
 | `GOOSE_CLI_SHOW_COST` | Show estimated cost for token use in the CLI | true/false | false | No |
 | `GOOSE_ALLOWLIST` | URL for allowed extensions | Valid URL | None | No |
+| `GOOSE_DOCS_ROOT` | Documentation root used by `goose-doc-guide` (e.g. for offline/air-gapped docs) | Local path or HTTP(S) URL containing `goose-docs-map.md` and `docs/` | `https://goose-docs.ai` | No |
 | `GOOSE_RECIPE_GITHUB_REPO` | GitHub repository for recipes | Format: "org/repo" | None | No |
 | `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically compacts your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0)| 0.8 | No |
 | `SECURITY_PROMPT_ENABLED` | Enable [prompt injection detection](/docs/guides/security/prompt-injection-detection) to identify potentially harmful commands | true/false | false | No |
@@ -98,6 +99,9 @@ GOOSE_CLI_MIN_PRIORITY: 0.2
 # Recipe Configuration
 GOOSE_RECIPE_GITHUB_REPO: "aaif-goose/goose-recipes"
 
+# Documentation Configuration
+GOOSE_DOCS_ROOT: "/path/to/goose-docs"
+
 # Search Path Configuration
 GOOSE_SEARCH_PATHS:
   - "/usr/local/bin"

documentation/docs/guides/environment-variables.md

@@ -508,6 +508,14 @@ export GOOSE_RECIPE_RETRY_TIMEOUT_SECONDS=300
 export GOOSE_RECIPE_ON_FAILURE_TIMEOUT_SECONDS=60
 ```
 
+## Documentation Configuration
+
+This variable controls where the `goose-doc-guide` skill reads goose documentation from.
+
+| Variable | Purpose | Values | Default |
+|----------|---------|---------|---------|
+| `GOOSE_DOCS_ROOT` | Documentation root for the `goose-doc-guide` skill, used for [offline/air-gapped docs](/docs/guides/offline-docs) | Local path or HTTP(S) URL containing `goose-docs-map.md` and `docs/` | `https://goose-docs.ai` |
+
 ## Development & Testing
 
 These variables are primarily used for development, testing, and debugging goose itself.

documentation/docs/guides/offline-docs.md

@@ -0,0 +1,86 @@
+---
+title: Offline / Air-gapped Docs
+sidebar_position: 95
+sidebar_label: Offline Docs
+---
+
+# Offline / Air-gapped Docs
+
+The `goose-doc-guide` skill reads official goose documentation before answering
+goose-specific questions. By default it reads from `https://goose-docs.ai`. In
+an offline or air-gapped environment, point goose at a **local copy** instead by
+setting `GOOSE_DOCS_ROOT`.
+
+- If `GOOSE_DOCS_ROOT` is set (in `config.yaml` or the environment), goose uses
+  it as the docs root — either a local filesystem path or an HTTP(S) URL.
+- If it is not set, goose falls back to `https://goose-docs.ai`.
+
+When the root is a local path, goose reads the docs with its file tools; no
+network access is required.
+
+## Docs layout
+
+A docs root contains a docs map and a `docs/` tree:
+
+```
+<docs-root>/
+├── goose-docs-map.md
+└── docs/
+    ├── getting-started/...
+    └── guides/...
+```
+
+`goose-docs-map.md` is the index the skill searches first; every page it reads
+is referenced by a path listed there.
+
+## Building a local docs root
+
+Build the docs from a goose checkout using the same version as your goose
+binary, so the docs match the runtime. The standard documentation build already
+produces everything goose needs — a `goose-docs-map.md` index and a `docs/` tree
+of markdown files — so no custom tooling is required:
+
+```bash
+git checkout v1.41.0   # match your goose binary version
+cd documentation
+npm run build
+```
+
+This writes the docs root to `documentation/build/`, containing:
+
+```
+build/
+├── goose-docs-map.md
+└── docs/
+    ├── getting-started/...
+    └── guides/...
+```
+
+`npm run build` requires registry access, so run it in an online environment.
+Then copy the resulting `build/` directory to your air-gapped target location
+(for example `/opt/goose-docs`) and point `GOOSE_DOCS_ROOT` at it.
+
+## Configuring goose
+
+Set `GOOSE_DOCS_ROOT` in `config.yaml`:
+
+```yaml
+GOOSE_DOCS_ROOT: "/opt/goose-docs"
+```
+
+Or via the environment:
+
+```bash
+export GOOSE_DOCS_ROOT=/opt/goose-docs
+```
+
+For a managed distribution, bake the docs tree into your image and set
+`GOOSE_DOCS_ROOT` in the shipped `config.yaml` or launcher environment.
+
+## Notes
+
+- Documentation links in goose's answers always render as canonical
+  `https://goose-docs.ai/...` URLs, even when read locally.
+- A custom HTTP(S) mirror also works: set `GOOSE_DOCS_ROOT` to its root URL.
+- For MCP extension runtime issues offline, see
+  [Airgapped/Offline Environment Issues](/docs/troubleshooting/known-issues#airgappedoffline-environment-issues).

documentation/docs/troubleshooting/known-issues.md

@@ -507,6 +507,9 @@ goose Desktop uses **"shims"** (packaged versions of `npx` and `uvx`) that autom
 
 4. **Require more changes**: In a corporate proxy environment or airgapped environment where the above doesn't work, it is recommended that you customize and package up goose Desktop with shims/config that will work given the network constraints you have (for example, TLS certificate limitations, [proxy configuration](/docs/guides/environment-variables#network-configuration), inability to download required content etc).
 
+#### Documentation access:
+The `goose-doc-guide` skill reads goose documentation from `https://goose-docs.ai` by default, which is unavailable offline. To have goose read from a local copy of the docs instead, see [Offline / Air-gapped Docs](/docs/guides/offline-docs).
+
 ---
 ### Need Further Help?