From 32277e7ed9c17aea744d832b77cc7aa61c8d1772 Mon Sep 17 00:00:00 2001
From: quinnbot-ai <quinnbot.ai@gmail.com>
Date: Tue, 28 Jul 2026 12:57:30 -0700
Subject: [PATCH] docs: allow authenticated browser routing (#58)

Co-authored-by: QuinnBot <quinnbot@proton.me>
---
 AGENTS.md              |  1 +
 bin/fm-brief.sh        |  2 ++
 tests/fm-brief.test.sh | 21 +++++++++++++++++++++
 3 files changed, 24 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 896847a3ea..e91f935607 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -168,6 +168,7 @@ When that section reports its checks still in progress it names exactly what is
 Bootstrap detects first, asks for consent, and installs only after the captain approves in the current session.
 Do not dispatch until the required tools are present and GitHub authentication is good.
 Use `gh-axi` for GitHub, `chrome-devtools-axi` for browser work, and `lavish-axi` for structured decisions or reports; consult current help rather than memorizing flags.
+Machine-level routing policy may override the browser-tool default for authenticated or account sessions.
 A silent bootstrap section needs no action; for any printed actionable diagnostic line, load `bootstrap-diagnostics` and follow its owner procedure.
 `BOOTSTRAP_INFO:` lines are completed no-action facts and do not require loading a skill.
 `secondmate-provisioning` owns startup secondmate sync, liveness, and inherited local-material convergence.
diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh
index a873c84051..d573379db9 100755
--- a/bin/fm-brief.sh
+++ b/bin/fm-brief.sh
@@ -317,6 +317,7 @@ The report is the only thing that survives, so anything worth keeping must be in
 1. Never push to any remote and never open a PR.
 2. Stay inside this worktree; the only files you may write outside it are the report and the status file below.
 3. Use gh-axi for GitHub operations and chrome-devtools-axi for browser operations.
+   Machine-level routing policy may override the browser-tool default for authenticated or account sessions.
 4. Report status by appending one line:
    \`echo "{state}: {one short line}" >> $STATUS_FILE\`
    States: working, needs-decision, blocked, $PAUSED_VERB, done, failed.
@@ -430,6 +431,7 @@ If the top-level path is the primary checkout or not the worktree you were launc
 $RULE1
 2. Stay inside this worktree; modify nothing outside it.
 3. Use gh-axi for GitHub operations and chrome-devtools-axi for browser operations.
+   Machine-level routing policy may override the browser-tool default for authenticated or account sessions.
 4. Report status by appending one line:
    \`echo "{state}: {one short line}" >> $STATUS_FILE\`
    States: working, needs-decision, blocked, $PAUSED_VERB, done, failed.
diff --git a/tests/fm-brief.test.sh b/tests/fm-brief.test.sh
index a348e2d345..10c9172510 100755
--- a/tests/fm-brief.test.sh
+++ b/tests/fm-brief.test.sh
@@ -439,6 +439,26 @@ test_herdr_lab_omission_is_loud_for_ship_and_scout() {
   pass "fm-brief.sh: ship and scout scaffolds make omitted Herdr intent fail-visible"
 }
 
+test_browser_tool_routing_allows_authenticated_session_override() {
+  local home kind id brief
+  home="$TMP_ROOT/browser-routing-home"
+  mkdir -p "$home/data"
+  for kind in ship scout; do
+    id="brief-browser-routing-$kind"
+    if [ "$kind" = scout ]; then
+      FM_HOME="$home" "$ROOT/bin/fm-brief.sh" "$id" firstmate --scout >/dev/null 2>&1
+    else
+      FM_HOME="$home" "$ROOT/bin/fm-brief.sh" "$id" firstmate >/dev/null 2>&1
+    fi
+    brief="$home/data/$id/brief.md"
+    assert_grep "Use gh-axi for GitHub operations and chrome-devtools-axi for browser operations." "$brief" \
+      "$kind brief did not retain chrome-devtools-axi as the browser default"
+    assert_grep "Machine-level routing policy may override the browser-tool default for authenticated or account sessions." "$brief" \
+      "$kind brief did not allow machine-level authenticated-browser routing"
+  done
+  pass "fm-brief.sh: ship and scout briefs allow machine-level authenticated-browser routing"
+}
+
 test_secondmate_no_projects_charter() {
   local home brief status
   home="$TMP_ROOT/no-projects-home"
@@ -723,6 +743,7 @@ test_ship_project_memory_wording
 test_herdr_lab_contract_is_explicit_and_complete
 test_herdr_lab_contract_quotes_foreign_firstmate_path
 test_herdr_lab_omission_is_loud_for_ship_and_scout
+test_browser_tool_routing_allows_authenticated_session_override
 test_herdr_lab_contract_applies_to_scouts_but_not_secondmates
 test_secondmate_no_projects_charter
 test_secondmate_marked_request_reporting_contract