Added goose doc map md file for goose agent to find relevant doc easily. by lifeizhou-ap · Pull Request #6598 · block/goose

lifeizhou-ap · 2026-01-21T01:13:01Z

Summary

Added goose doc map md file for goose agent to find relevant doc easily for user to understand how to use goose and goose features. The map md file only includes the "Get Started" and "Guides" Section.

This is the prerequisite change for this PR #6534

Type of Change

AI Assistance

This PR was created or reviewed with AI assistance

Testing

Unit test and local testing

lifeizhou-ap · 2026-01-21T01:13:56Z

documentation/package.json

    "write-heading-ids": "docusaurus write-heading-ids",
+    "test": "node --test scripts/*.test.js",
    "typecheck": "tsc",
-    "generate-detail-pages": "node scripts/generate-detail-pages.js",


this js file is not referenced anywhere

Copilot

Pull request overview

This PR adds a documentation map generation system that creates a structured overview of goose documentation files. The system scans markdown files in the docs directory, extracts titles and headings, and generates a consolidated map file that can be used for navigation or context.

Changes:

Added a Node.js script to generate a documentation map from markdown files
Added unit tests for the map generation logic using Node's built-in test runner
Added a bash verification script to ensure the docs map is generated during builds
Integrated the generation into the npm build process and CI workflow

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
documentation/scripts/generate-docs-map.js	Main script that scans docs directory and generates markdown map
documentation/scripts/generate-docs-map.test.js	Unit tests for title and heading extraction functions
documentation/scripts/verify-build.sh	Bash script to verify docs map exists in build output
documentation/package.json	Added gray-matter dependency and test/build script updates
documentation/package-lock.json	Lock file updates for new dependency
documentation/.gitignore	Excludes generated docs map from version control
.github/workflows/deploy-docs-and-extensions.yml	Runs tests and verification during deployment

Files not reviewed (1)

documentation/package-lock.json: Language not supported

Copilot · 2026-01-21T01:16:23Z

documentation/scripts/generate-docs-map.js

+    { name: 'Guides', pattern: 'guides/**/*.{md,mdx}' },
+  ];
+
+  let output = `# Goose Documentation Map


The title uses "Goose" (uppercase) which violates the project naming convention. According to the project guidelines, in documentation files, the project should always be referred to as "goose" (lowercase), never "Goose" (even at the start of sentences). Change this to "# goose Documentation Map".

Copilot · 2026-01-21T01:16:24Z

documentation/scripts/generate-docs-map.js

+          continue;
+        }
+        const headings = getHeadings(content);
+        const urlPath = `docs/${file.replace('.mdx', '.md')}`;


The replacement logic only handles '.mdx' to '.md' conversion but doesn't handle files that are already '.md'. This could result in incorrect URLs for .md files. Use .replace(/\.mdx?$/, '.md') instead to handle both .md and .mdx extensions correctly.

Suggested change

const urlPath = `docs/${file.replace('.mdx', '.md')}`;

const urlPath = `docs/${file.replace(/\.mdx?$/, '.md')}`;

not sure why we need regex here? are they the same thing? @copilot

Copilot · 2026-01-21T01:16:24Z

documentation/package.json

    "@docusaurus/tsconfig": "3.7.0",
    "@docusaurus/types": "3.7.0",
+    "gray-matter": "^4.0.3",
    "js-yaml": "^4.1.1",


The package 'globby' is used but not declared as a dependency in package.json. While it's currently available as a transitive dependency through other packages, this is fragile as it could break if those packages change their dependencies. Add 'globby' explicitly to devDependencies to ensure it remains available.

Suggested change

"js-yaml": "^4.1.1",

"js-yaml": "^4.1.1",

"globby": "^13.2.2",

github-actions · 2026-01-21T01:17:56Z

PR Preview Action v1.6.3
🚀 View preview at https://block.github.io/goose/pr-preview/pr-6598/
Built to branch `gh-pages` at 2026-01-21 03:56 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Copilot

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

documentation/package-lock.json: Language not supported

.github/workflows/deploy-docs-and-extensions.yml

Copilot · 2026-01-21T02:51:08Z

documentation/scripts/generate-docs-map.js

+        output += `### [${title}](${urlPath})\n\n`;
+        if (headings) output += `${headings}\n\n`;
+      } catch (err) {
+        console.warn(`[generate-docs-map] Warning: Could not process ${file}, skipping`);


The error is caught but the actual error details are not logged. Consider logging the error object to help with debugging, for example: console.warn([generate-docs-map] Warning: Could not process ${file}, skipping, err)

Suggested change

console.warn(`[generate-docs-map] Warning: Could not process ${file}, skipping`);

console.warn(`[generate-docs-map] Warning: Could not process ${file}, skipping`, err);

Copilot · 2026-01-21T02:51:08Z

documentation/scripts/generate-docs-map.js

+
+// Run main if executed directly
+if (require.main === module) {
+  main();


The async main function is called without error handling. If it fails, the process may not exit with an error code, causing CI to pass when it should fail. Consider using: main().catch(err => { console.error(err); process.exit(1); })

Suggested change

main();

main().catch((err) => {

console.error('[generate-docs-map] Error running main:', err);

process.exit(1);

});

without the catch, it still exit with non zero error code

Copilot

Pull request overview

Copilot reviewed 7 out of 9 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

documentation/package-lock.json: Language not supported

Copilot · 2026-01-21T03:50:08Z

documentation/scripts/generate-docs-map.js

+
+// Run main if executed directly
+if (require.main === module) {
+  main();


The script lacks error handling for async main function. If main() throws an error, it will result in an unhandled promise rejection. Consider wrapping the main() call in a try-catch or adding .catch() to handle errors properly and exit with a non-zero status code on failure.

Suggested change

main();

main().catch((err) => {

console.error('[generate-docs-map] Failed to generate docs map:', err);

process.exit(1);

});

…ovider * 'main' of github.com:block/goose: increase worker threads for ci (#6614) docs: todo tutorial update (#6613) Added goose doc map md file for goose agent to find relevant doc easily. (#6598) add back goose branding to home (#6617) fix: actually set the working dir for extensions from session (#6612) Multi chat (#6428) Lifei/fixed accumulated token count (#6587) Dont show MCP UI/Apps until tool is approved (#6492) docs: max tokens config (#6596) User configurable templates (#6420) docs: http proxy environment variables (#6594) feat: exclude subagent tool from code_execution filtering (#6531)

* main: increase worker threads for ci (#6614) docs: todo tutorial update (#6613) Added goose doc map md file for goose agent to find relevant doc easily. (#6598) add back goose branding to home (#6617) fix: actually set the working dir for extensions from session (#6612) Multi chat (#6428) Lifei/fixed accumulated token count (#6587) Dont show MCP UI/Apps until tool is approved (#6492) docs: max tokens config (#6596) User configurable templates (#6420) docs: http proxy environment variables (#6594) feat: exclude subagent tool from code_execution filtering (#6531) Fix path for global agent skills (#6591) recipes: add mcp server (#6552) feat(gcp-vertex): add model list with org policy filtering (#6393) chore: encourage extension searching (#6582) blog: mobile apps consolidation and roadmap (#6580) chore: remove unused dependencies in cargo.toml (#6561) resolved all the extensions to load in cli (#6464)

* main: increase worker threads for ci (#6614) docs: todo tutorial update (#6613) Added goose doc map md file for goose agent to find relevant doc easily. (#6598)

* main: increase worker threads for ci (#6614) docs: todo tutorial update (#6613) Added goose doc map md file for goose agent to find relevant doc easily. (#6598) add back goose branding to home (#6617) fix: actually set the working dir for extensions from session (#6612) Multi chat (#6428) Lifei/fixed accumulated token count (#6587) Dont show MCP UI/Apps until tool is approved (#6492)

* main: (41 commits) chore: tweak release docs (#6571) fix(goose): propagate session_id across providers and MCP (#6584) increase worker threads for ci (#6614) docs: todo tutorial update (#6613) Added goose doc map md file for goose agent to find relevant doc easily. (#6598) add back goose branding to home (#6617) fix: actually set the working dir for extensions from session (#6612) Multi chat (#6428) Lifei/fixed accumulated token count (#6587) Dont show MCP UI/Apps until tool is approved (#6492) docs: max tokens config (#6596) User configurable templates (#6420) docs: http proxy environment variables (#6594) feat: exclude subagent tool from code_execution filtering (#6531) Fix path for global agent skills (#6591) recipes: add mcp server (#6552) feat(gcp-vertex): add model list with org policy filtering (#6393) chore: encourage extension searching (#6582) blog: mobile apps consolidation and roadmap (#6580) chore: remove unused dependencies in cargo.toml (#6561) ...

* main: (68 commits) fix(docs): use dynamic import for globby ESM module (#6636) chore: trigger CI Document tab completion (#6635) Install goose-mcp crate dependencies (#6632) feat(goose): standardize agent-session-id for session correlation (#6626) chore: tweak release docs (#6571) fix(goose): propagate session_id across providers and MCP (#6584) increase worker threads for ci (#6614) docs: todo tutorial update (#6613) Added goose doc map md file for goose agent to find relevant doc easily. (#6598) add back goose branding to home (#6617) fix: actually set the working dir for extensions from session (#6612) Multi chat (#6428) Lifei/fixed accumulated token count (#6587) Dont show MCP UI/Apps until tool is approved (#6492) docs: max tokens config (#6596) User configurable templates (#6420) docs: http proxy environment variables (#6594) feat: exclude subagent tool from code_execution filtering (#6531) Fix path for global agent skills (#6591) ...

…ly. (block#6598) Signed-off-by: fbalicchia <fbalicchia@cuebiq.com>

…ly. (block#6598)

lifeizhou-ap added 2 commits January 21, 2026 12:11

generated goose doc map md file

b9e5d76

added test for goose doc map

cac1381

lifeizhou-ap requested a review from a team as a code owner January 21, 2026 01:13

Copilot AI review requested due to automatic review settings January 21, 2026 01:13

Copilot started reviewing on behalf of lifeizhou-ap January 21, 2026 01:13 View session

lifeizhou-ap commented Jan 21, 2026

View reviewed changes

Copilot AI reviewed Jan 21, 2026

View reviewed changes

lifeizhou-ap added 2 commits January 21, 2026 12:19

npm audit fix

c0d3d21

added missing package

3e5442e

Copilot AI review requested due to automatic review settings January 21, 2026 02:46

Copilot started reviewing on behalf of lifeizhou-ap January 21, 2026 02:47 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

lifeizhou-ap added 2 commits January 21, 2026 14:34

fixing wrong import

34f17e2

log error message

966166a

Copilot AI review requested due to automatic review settings January 21, 2026 03:46

Copilot started reviewing on behalf of lifeizhou-ap January 21, 2026 03:47 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

removed accidentally created file

36a5607

lifeizhou-ap changed the title ~~Lifei/goose doc only~~ Added goose doc map md file for goose agent to find relevant doc easily. Jan 21, 2026

lifeizhou-ap mentioned this pull request Jan 21, 2026

feat: Add built-in skill for goose documentation reference #6534

Merged

10 tasks

blackgirlbytes approved these changes Jan 21, 2026

View reviewed changes

lifeizhou-ap merged commit 69d2f8c into main Jan 21, 2026
28 of 30 checks passed

lifeizhou-ap deleted the lifei/goose-doc-only branch January 21, 2026 21:49

michaelneale added a commit that referenced this pull request Jan 21, 2026

Merge branch 'main' into vibe-mcp-apps

ddc5495

* main: increase worker threads for ci (#6614) docs: todo tutorial update (#6613) Added goose doc map md file for goose agent to find relevant doc easily. (#6598)

github-actions bot mentioned this pull request Jan 22, 2026

chore(release): release version 1.21.0 (minor) #6634

Merged

fbalicchia pushed a commit to fbalicchia/goose that referenced this pull request Jan 23, 2026

Added goose doc map md file for goose agent to find relevant doc easi…

357d76f

…ly. (block#6598) Signed-off-by: fbalicchia <fbalicchia@cuebiq.com>

raj-subhankar pushed a commit to raj-subhankar/goose that referenced this pull request Feb 14, 2026

Added goose doc map md file for goose agent to find relevant doc easi…

3ebca05

…ly. (block#6598)

	const urlPath = `docs/${file.replace('.mdx', '.md')}`;
	const urlPath = `docs/${file.replace(/\.mdx?$/, '.md')}`;

	"js-yaml": "^4.1.1",
	"js-yaml": "^4.1.1",
	"globby": "^13.2.2",

	console.warn(`[generate-docs-map] Warning: Could not process ${file}, skipping`);
	console.warn(`[generate-docs-map] Warning: Could not process ${file}, skipping`, err);

-  main();
+  main().catch((err) => {
+    console.error('[generate-docs-map] Error running main:', err);
+    process.exit(1);
+  });

Conversation

lifeizhou-ap commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of Change

AI Assistance

Testing

Uh oh!

lifeizhou-ap Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

lifeizhou-ap Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-01-21 03:56 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

lifeizhou-ap Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

lifeizhou-ap commented Jan 21, 2026 •

edited

Loading

github-actions bot commented Jan 21, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-01-21 03:56 UTC.
Preview will be ready when the GitHub Pages deployment is complete.