feat: add air-gapped docs bundle support

[soolmuk]

Summary

Closes #9981.

Adds support for publishing an air-gapped goose docs bundle and configuring goose-doc-guide to read from a local or mirrored docs root.

This lets users in restricted or offline environments download goose-docs.tar.gz, extract it, and point GOOSE_DOCS_ROOT at the extracted goose-docs/ directory.

What changed

Docs bundle

Adds a docs bundle generator:

• documentation/scripts/generate-docs-bundle.js
• documentation/scripts/generate-docs-bundle.test.js

The generated archive has this layout:

goose-docs/
  goose-docs-map.md
  docs/
    getting-started/
    guides/

The bundle includes goose-docs-map.md and the docs sections used by goose-doc-guide.

MDX files are normalized to .md paths inside the archive so they match docs map entries.

Release assets

Adds a docs-bundle job to:

• .github/workflows/release.yml
• .github/workflows/canary.yml

The job:

1. installs documentation dependencies
2. regenerates goose-docs-map.md
3. builds documentation/goose-docs.tar.gz
4. uploads it as the goose-docs artifact

The upload step uses if-no-files-found: error so missing docs bundles fail the workflow instead of silently warning.

goose-doc-guide

Updates the built-in goose-doc-guide skill to resolve docs in this order:

1. Use GOOSE_DOCS_ROOT from goose config.yaml if configured and non-empty
2. Otherwise fall back to https://goose-docs.ai

GOOSE_DOCS_ROOT may point to either:

• a local extracted docs bundle
• an HTTP(S) docs mirror root

The skill still requires reading goose-docs-map.md first and only using exact paths listed in the map.

When local docs are used, final documentation links are converted to canonical https://goose-docs.ai/... URLs so local filesystem paths are not exposed in answers.

Config docs

Documents GOOSE_DOCS_ROOT in the config files guide as a config-file setting:

GOOSE_DOCS_ROOT: "/path/to/goose-docs"

Verification

Ran documentation tests:

cd documentation && npm test

Result:

18 passed

Generated docs map and bundle:

cd documentation
node scripts/generate-docs-map.js
node scripts/generate-docs-bundle.js

Verified archive layout:

goose-docs/
goose-docs/goose-docs-map.md
goose-docs/docs/

Extracted the archive and verified all docs map paths resolve inside the extracted bundle:

Verified 63 docs map paths exist under goose-docs/.

Ran Rust verification:

cargo fmt
cargo test -p goose config::base::tests::get_goose_docs_root -- --nocapture
cargo test -p goose skills::tests::docs_root_config_instruction -- --nocapture
cargo check -p goose

Validated workflow YAML and whitespace:

ruby -e 'require "yaml"; ARGV.each { |file| YAML.load_file(file); puts "parsed #{file}" }' \
  .github/workflows/release.yml \
  .github/workflows/canary.yml

git diff --check

Ran CodeRabbit review on the final squashed commit and addressed the reported feedback.

Notes

This PR does not add installer automation. Users or administrators who need offline docs should download goose-docs.tar.gz, extract it, and point GOOSE_DOCS_ROOT at the extracted goose-docs/ directory.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7693fc5ed6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Let docs-only pushes refresh the docs bundle

This new release artifact is inside a workflow whose trigger still ignores documentation/** (lines 5-9), and GitHub's workflow docs state that when branch and path filters are both defined the run only starts when both are satisfied (https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore). On a docs-only push to main, the entire canary workflow is skipped, so docs-bundle never rebuilds and the published goose-docs.tar.gz stays stale until a non-docs change lands; the same pattern exists in release.yml for release branches.

Useful? React with 👍 / 👎.

[soolmuk]

Thanks for the thorough review! This is actually already handled.

docs-bundle.yml is a standalone reusable workflow with its own on.push trigger that explicitly fires on documentation/** changes to main and release/* branches:

on:
  workflow_call:          # called from canary.yml / release.yml
    inputs:
      force_build: ...
  push:                    # independent trigger for docs-only pushes
    branches:
      - main
      - "release/*"
    paths:
      - "documentation/**"
  workflow_dispatch:

So the two scenarios are covered independently:

Scenario	Execution path	Docs bundle built?
docs-only push to main	docs-bundle.yml own on.push trigger	✅ Yes
Canary release (code change)	canary.yml → docs-bundle job (force_build: true)	✅ Yes
Tag release	release.yml → docs-bundle job (force_build: true)	✅ Yes

When a docs-only push lands on main, canary.yml is indeed skipped due to paths-ignore: ["documentation/**"], but docs-bundle.yml runs on its own and rebuilds + republishes goose-docs.tar.gz to the canary release. The paths-ignore in canary.yml is intentional — it avoids running the full canary pipeline (CLI build, desktop bundles, etc.) when only documentation changed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c371cf211c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Update the platform-extension snapshot

Changing this builtin skill description also changes the text that SkillsClient::get_instructions injects into the all-platform-extension system prompt, but crates/goose/src/agents/snapshots/goose__agents__prompt_manager__tests__all_platform_extensions.snap still expects the old “MUST fetch relevant goose docs” wording at line 127. With snapshots checked, cargo test -p goose agents::prompt_manager::tests::test_all_platform_extensions will fail until the snapshot is regenerated or updated.

Useful? React with 👍 / 👎.

[itxaiohanglover]

Good addition! The docs-bundle workflow for air-gapped environments is useful for organizations that can't access external docs. Clean CI integration.