Add configurable GOOSE_DOCS_ROOT for air-gapped docs access by alexhancock · Pull Request #10294 · aaif-goose/goose

alexhancock · 2026-07-06T23:45:52Z

Resolve the goose-doc-guide docs root from the GOOSE_DOCS_ROOT config value (falling back to https://goose-docs.ai), substituting it into the builtin skill via a {{GOOSE_DOCS_ROOT}} placeholder.

Summary

Make it possible for goose to read the docs locally in air-gapped environments

Testing

Seeing help from @soolmuk

Related Issues

#9981

Screenshots/Demos (for UX changes)

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 57932e0c5c

ℹ️ 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 · 2026-07-06T23:48:57Z

+shell/file tools; when it is not set or is an HTTP(S) URL fetch them from the
+canonical location which is https://goose-docs.ai. Everything below refers to


Honor HTTP docs roots instead of forcing canonical

When GOOSE_DOCS_ROOT is set to an internal HTTP(S) mirror, this instruction tells the agent to fetch from https://goose-docs.ai instead of the configured root. In an air-gapped network that only exposes a mirror, goose-doc-guide will still attempt the public site and fail or ignore the mirror; the HTTP(S) case should use <docs-root> just like the local-path case.

Useful? React with 👍 / 👎.

github-actions · 2026-07-06T23:49:04Z

Documentation preview deployed: https://pr-10294.goose-pr-previews-poc.pages.dev

soolmuk · 2026-07-07T11:29:31Z

Tested on macOS and everything worked as expected.

One small suggestion: instead of placing everything directly under build/, would it make sense to put the generated documentation output under a dedicated subdirectory such as build/goose-docs/?

That would make it clearer that these files are the generated goose docs artifacts, and it would also make copying or packaging the output easier.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d01049914d

ℹ️ 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 · 2026-07-13T19:52:46Z

+rm -rf "$DOCS_ROOT"
+mkdir -p "$DOCS_ROOT/docs"
+cp static/goose-docs-map.md "$DOCS_ROOT/goose-docs-map.md"
+cp -r docs/getting-started docs/guides "$DOCS_ROOT/docs/"


Export MDX pages under the map's .md paths

When building a local docs root from source, this copies the raw docs/guides tree, but documentation/scripts/generate-docs-map.js records MDX-backed pages using .md paths via file.replace('.mdx', '.md'). For a map entry such as docs/guides/context-engineering/subagents.md, the copied local tree contains only subagents.mdx, and the skill is instructed to read only exact paths from the map, so offline/air-gapped lookup fails for those guides. The copy step needs to export or rename MDX pages consistently with the generated map.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 75d1fcc302

ℹ️ 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 · 2026-07-13T21:17:36Z

+#!/usr/bin/env bash
+set -euo pipefail
+
+GOOSE_VERSION="${1:-v1.41.0}"


Default the docs export to the current version

When an air-gapped user copies this script without passing an explicit version, it checks out v1.41.0 even though this checkout's workspace version is 1.42.0, so the generated local docs root can silently describe an older goose than the binary the paragraph says to match. Please default to the current checkout/release version, or make the version argument required, so offline docs don't serve stale schema and command references by default.

Useful? React with 👍 / 👎.

soolmuk · 2026-07-14T10:53:18Z

Feedback on the build script in `offline-docs.md`

The proposed script in offline-docs.md still requires npm ci (which needs registry access), so it can't be run in an air-gapped environment either — it must be run online beforehand regardless.

Given that documentation/README.md on main already documents npm run build as the standard way to generate the build/ directory, and the build output already includes the markdown source files (not just HTML), users could simply:

Run npm run build (already documented in the README)
Point GOOSE_DOCS_ROOT at the build/ directory

This is simpler (single command), already documented, and consistent with the existing workflow. The custom script with generate-docs-map.js + manual cp adds a parallel path that users have to learn, when the standard npm run build already produces the files goose needs.

alexhancock · 2026-07-17T14:48:46Z

Feedback on the build script in offline-docs.md

The proposed script in offline-docs.md still requires npm ci (which needs registry access), so it can't be run in an air-gapped environment either — it must be run online beforehand regardless.

Given that documentation/README.md on main already documents npm run build as the standard way to generate the build/ directory, and the build output already includes the markdown source files (not just HTML), users could simply:

Run npm run build (already documented in the README)

Point GOOSE_DOCS_ROOT at the build/ directory

This is simpler (single command), already documented, and consistent with the existing workflow. The custom script with generate-docs-map.js + manual cp adds a parallel path that users have to learn, when the standard npm run build already produces the files goose needs.

Updated to just use npm run build and then GOOSE_DOCS_ROOT can be pointed at the build/ directory

Resolve the goose-doc-guide docs root from the GOOSE_DOCS_ROOT config value (falling back to https://goose-docs.ai), substituting it into the builtin skill via a {{GOOSE_DOCS_ROOT}} placeholder.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c91fcd42e0

ℹ️ 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 · 2026-07-24T18:49:19Z

+produces everything goose needs — a `goose-docs-map.md` index and a `docs/` tree
+of markdown files — so no custom tooling is required:


Provide a Markdown docs-root export

For air-gapped users who follow this guide, GOOSE_DOCS_ROOT will point at documentation/build, but the documented build script runs docusaurus build (documentation/package.json:8), which produces HTML pages under build/docs while the docs map still points the skill at docs/*.md paths (documentation/scripts/generate-docs-map.js:71). Fresh evidence in the current diff is that the guide now instructs copying the Docusaurus build output, so goose-doc-guide cannot read the exact Markdown paths from the map unless the build/export step also emits those files.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-07-24T18:49:19Z

+    let docs_root = Config::global()
+        .get_goose_docs_root()?
+        .unwrap_or_else(|| DEFAULT_GOOSE_DOCS_ROOT.to_string());


Add self-test coverage for docs-root loading

This adds the GOOSE_DOCS_ROOT feature, but the commit leaves goose-self-test.yaml unchanged, so the first-person integration suite never exercises a configured local docs root or verifies that the builtin skill receives the substituted path. The repo guidance requires updating the self-test recipe when adding features, which would catch regressions in this new offline-docs path.

AGENTS.md reference: AGENTS.md:L71-L71

Useful? React with 👍 / 👎.

jamadeo · 2026-07-24T20:57:07Z

 - Running existing recipes (just run them directly)

+The docs root for this session is `{{GOOSE_DOCS_ROOT}}`. It may be a local
+filesystem path or an HTTP(S) URL. When it is a local path read files with the


I would guess that the agent knows enough at this point how to choose between read vs fetch, as long as remote urls have the protocol

* origin/main: (24 commits) upgrade to rmcp 2.0 (#10584) chore: opus5 support (including adaptive thinking) (#10686) fix(desktop): use shell working directory on initial launch (#10655) fix(providers): enable inventory refresh for OpenRouter model picker (#10641) Add configurable GOOSE_DOCS_ROOT for air-gapped docs access (#10294) fix(i18n): fix Korean translation errors, untranslated entries, and terminology consistency (#10667) fix(acp): preserve read lines and reload tool output (#10662) fix(acp): surface tool call output in CLI and Desktop (#10654) fix overlong function names in provider requests (#10659) fix (desktop): preserve ACP tool call update fields (#10653) feat: support latest Gemini models (#10630) Merge commit from fork feat (acp): Gate tool-call label enrichment on ACP client capability (#10644) fix(session): use configured session manager for tool summaries (#10628) refactor (acp): simplify ACP tool-call handling and fix chain summaries (#10599) fix: omit disabled OpenRouter reasoning (#10517) enhance the uniffi API layer (#10427) remove sampling from smoke test (#10639) rebuild canonical model db (#10633) fix(ui): clear stale pending ACP connection after terminal recovery failure (#10552) ... # Conflicts: # ui/desktop/src/i18n/messages/ko.json

chatgpt-codex-connector Bot reviewed Jul 6, 2026

View reviewed changes

DOsinga assigned alexhancock and unassigned alexhancock Jul 8, 2026

alexhancock force-pushed the air-gapped-docs-minimal branch 2 times, most recently from 73a74b9 to d010499 Compare July 13, 2026 19:49

chatgpt-codex-connector Bot reviewed Jul 13, 2026

View reviewed changes

Add configurable GOOSE_DOCS_ROOT for air-gapped docs access

c91fcd4

Resolve the goose-doc-guide docs root from the GOOSE_DOCS_ROOT config value (falling back to https://goose-docs.ai), substituting it into the builtin skill via a {{GOOSE_DOCS_ROOT}} placeholder.

alexhancock force-pushed the air-gapped-docs-minimal branch from cca9505 to c91fcd4 Compare July 24, 2026 18:44

chatgpt-codex-connector Bot reviewed Jul 24, 2026

View reviewed changes

jamadeo approved these changes Jul 24, 2026

View reviewed changes

michaelneale approved these changes Jul 25, 2026

View reviewed changes

alexhancock added this pull request to the merge queue Jul 26, 2026

Merged via the queue into main with commit cdea920 Jul 26, 2026
28 checks passed

alexhancock deleted the air-gapped-docs-minimal branch July 26, 2026 12:49

github-actions Bot mentioned this pull request Jul 29, 2026

chore(release): release version 1.45.0 #10787

Closed

DOsinga mentioned this pull request Jul 31, 2026

Make goose-doc-guide usable in air-gapped environments #9981

Closed

BrewTestBot mentioned this pull request Aug 12, 2026

block-goose-cli 1.46.0 Homebrew/homebrew-core#298471

Merged

		shell/file tools; when it is not set or is an HTTP(S) URL fetch them from the
		canonical location which is https://goose-docs.ai. Everything below refers to

		produces everything goose needs — a `goose-docs-map.md` index and a `docs/` tree
		of markdown files — so no custom tooling is required:

Uh oh!

Conversation

alexhancock commented Jul 6, 2026

Summary

Testing

Related Issues

Screenshots/Demos (for UX changes)

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 6, 2026

Uh oh!

soolmuk commented Jul 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

soolmuk commented Jul 14, 2026

Feedback on the build script in offline-docs.md

Uh oh!

alexhancock commented Jul 17, 2026

Feedback on the build script in offline-docs.md

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

jamadeo Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Feedback on the build script in `offline-docs.md`

Feedback on the build script in `offline-docs.md`

jamadeo Jul 24, 2026 •

edited

Loading