docs(goose): add gnt integration guide

[uuzzrm]

What & why

Closes #81.

Add a Goose integration guide for gnt-brain’s remote MCP extension, including the current streamable_http config shape, env_keys secret handling, and Goose’s .goosehints / persistent-instructions options. The companion TOOLS.md carries the existing check_action-first policy so connecting the tools also documents when an agent must stop for a human verdict.

Test plan

• Checked the extension fields against Goose’s current configuration guide and extension manager source.
• Ran documentation assertions for the config path, transport, secret placeholder, persistent-instructions setting, and all five gnt-brain tools.
• Ran git diff --check; no credential-like literal was present.
• Documentation-only change; no runtime test suite is applicable.
• AI assistance: I used AI assistance to research the current Goose configuration contract and draft the documentation, then reviewed the final diff and ran the checks above.

Before you open this

• Commits are signed off (git commit -s) — see CONTRIBUTING.md's DCO section.
• Functionally correct: the documentation was checked against Goose’s current configuration and source.
• No dead code — this is a documentation-only change.
• Non-trivial logic (a new branch, a parser, anything security- or money-adjacent) has a test. A one-line change doesn’t need one; a new code path does not apply here.
• If this touches anything multi-tenant (rules, connectors, MCP keys, billing), it respects org/tenant isolation — this only documents an existing remote MCP connection and keeps the key out of the repo.
• Matches this repo’s existing patterns, following integrations/openclaw/.
• If this touches apps/cli/src/prebrain/extraction/, the PR description includes the recall/precision numbers from bun run eval:extraction -- --mode cloud. (Not applicable.)

Summary by CodeRabbit

• Documentation
  • Added setup instructions for connecting Goose to gnt-brain through a streamable HTTP MCP extension.
  • Documented secure API key configuration, credential handling, and connection verification.
  • Added guidance for loading project-specific tool instructions.
  • Documented authorization checks and how to handle blocked, unclear, or approval-required actions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a5ce7942-a56e-4bc7-95bb-79364fff2dd3

📥 Commits

Reviewing files that changed from the base of the PR and between de2c42b and 2379bab.

📒 Files selected for processing (2)

• integrations/goose/CONNECT.md
• integrations/goose/TOOLS.md

🚧 Files skipped from review as they are similar to previous changes (2)

• integrations/goose/TOOLS.md
• integrations/goose/CONNECT.md

---

📝 Walkthrough

Walkthrough

Adds Goose integration documentation for connecting to gnt-brain through MCP. It documents credential handling, instruction loading, verification, troubleshooting, and required authorization checks before side-effectful actions.

Changes

Goose integration

Layer / File(s)	Summary
Goose connection setup integrations/goose/CONNECT.md	Documents the streamable HTTP MCP configuration, GNT_MCP_KEY handling, TOOLS.md loading, connection verification, and troubleshooting.
gnt-brain action governance integrations/goose/TOOLS.md	Defines check_action usage, policy lookup, fail-closed handling, blocked outcomes, and human-approval requirements.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to 2379b

This documentation-only change adds a Goose integration guide and tool-use guidance without introducing runtime behavior; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: lukaadzic

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the Goose integration guide added by this pull request.
Description check	✅ Passed	The description covers the required What & why, Test plan, and checklist sections with relevant details and completed checks.
Linked Issues check	✅ Passed	The pull request adds the requested Goose CONNECT.md and instructions documentation, including the real MCP configuration and check_action discipline [#81].
Out of Scope Changes check	✅ Passed	The changes are limited to Goose integration documentation and directly support the linked issue objectives [#81].
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

integrations/goose/TOOLS.md (1)

3-4: 🔒 Security & Privacy | 🔵 Trivial

Enforce and bind check_action outside prompt text.

This file is loaded as Goose hints or persistent instructions. Goose injects that text into model context; it does not itself prevent a model or another client from skipping check_action. Confirm that the action executor or MCP gateway rejects side-effectful calls without a matching authorization check. Bind the approval to the exact recipient, amount, target, and scope so an allowed result cannot be reused for a different action. (github.com)

Also applies to: 11-19

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@integrations/goose/TOOLS.md` around lines 3 - 4, Update the action execution
or MCP gateway path referenced by the Goose instructions to enforce check_action
for every side-effectful call, rather than relying on prompt text. Require an
allowed result bound to the exact recipient, amount, target, and scope of the
requested action, and reject missing, mismatched, or reused authorization before
execution.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@integrations/goose/CONNECT.md`:
- Around line 77-78: Update the troubleshooting guidance near the extension-load
instructions to state that GNT_MCP_KEY may be available either in Goose’s
inherited environment or its secret storage, with the environment checked first
and secret storage used as fallback. Retain the YAML indentation check and
warning not to include the raw key in bug reports.
- Around line 39-41: Update the GNT_MCP_KEY setup examples in CONNECT.md to
include equivalent PowerShell and cmd.exe commands alongside the existing Bash
form, or explicitly state that the examples require Bash; ensure Windows users
can set the variable using their native shells.
- Around line 15-28: Update the gnt-brain extension configuration to add an
explicit available_tools allowlist containing the five documented tools, while
preserving the existing check_action guidance in TOOLS.md and all other
connection settings.

---

Nitpick comments:
In `@integrations/goose/TOOLS.md`:
- Around line 3-4: Update the action execution or MCP gateway path referenced by
the Goose instructions to enforce check_action for every side-effectful call,
rather than relying on prompt text. Require an allowed result bound to the exact
recipient, amount, target, and scope of the requested action, and reject
missing, mismatched, or reused authorization before execution.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 11fea695-ffc0-439f-871b-20115afc1bff

📥 Commits

Reviewing files that changed from the base of the PR and between 9a8f63f and de2c42b.

📒 Files selected for processing (2)

• integrations/goose/CONNECT.md
• integrations/goose/TOOLS.md

[uuzzrm]

Thanks for the review. The configuration/documentation findings are addressed in 0a1bcfd:

• added an explicit available_tools allowlist for the five documented MCP tools;
• added Bash, PowerShell, and cmd.exe examples for GNT_MCP_KEY and the persistent-instructions file;
• documented Goose's inherited-environment-first, secret-storage fallback for env_keys;
• made the action-binding requirement explicit in TOOLS.md, including exact-action binding, fresh checks when details change, and fail-closed handling for missing or unclear verdicts.

The focused documentation check passes for the five-tool allowlist, all three shell forms, the credential fallback, and the executor-boundary wording.

One boundary is intentional: this PR only adds the Goose integration and its guidance. The gnt MCP server does not own Goose's downstream side-effect executor, so a documentation/configuration PR cannot enforce arbitrary external actions at that layer. TOOLS.md now calls that out explicitly; an executor-level authorization contract would be a separate implementation change.