fix(antigravity): Add overload recovery flow

Add a Unix activation script, Antigravity-specific installer guidance,
and cross-platform recovery documentation so users can reduce the
live skill set when truncation or context overload appears.

Regenerate the canonical bundle/catalog artifacts after merging the
stale goldrush-api removal so main stays release-ready.

Refs #381

tools/bin/install.js

@@ -236,6 +236,23 @@ function installForTarget(tempDir, target) {
   console.log(`  ✓ Installed to ${target.path}`);
 }
 
+function getPostInstallMessages(targets) {
+  const messages = [
+    "Pick a bundle in docs/users/bundles.md and use @skill-name in your AI assistant.",
+  ];
+
+  if (targets.some((target) => target.name === "Antigravity")) {
+    messages.push(
+      "If Antigravity hits context/truncation limits, see docs/users/agent-overload-recovery.md",
+    );
+    messages.push(
+      "For clone-based installs, use scripts/activate-skills.sh or scripts/activate-skills.bat",
+    );
+  }
+
+  return messages;
+}
+
 function main() {
   const opts = parseArgs();
   const { tagArg, versionArg } = opts;
@@ -280,9 +297,9 @@ function main() {
       installForTarget(tempDir, target);
     }
 
-    console.log(
-      "\nPick a bundle in docs/users/bundles.md and use @skill-name in your AI assistant.",
-    );
+    for (const message of getPostInstallMessages(targets)) {
+      console.log(`\n${message}`);
+    }
   } finally {
     try {
       if (fs.existsSync(tempDir)) {
@@ -304,6 +321,7 @@ if (require.main === module) {
 
 module.exports = {
   copyRecursiveSync,
+  getPostInstallMessages,
   installSkillsIntoTarget,
   installForTarget,
   main,

tools/scripts/tests/activate_skills_shell.test.js

@@ -0,0 +1,64 @@
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const repoRoot = path.resolve(__dirname, "../..", "..");
+const scriptPath = path.join(repoRoot, "scripts", "activate-skills.sh");
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "activate-skills-shell-"));
+const baseDir = path.join(root, "antigravity");
+const repoSkills = path.join(root, "repo-skills");
+
+function makeSkill(skillId) {
+  const skillDir = path.join(repoSkills, skillId);
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(skillDir, "SKILL.md"),
+    `---\nname: ${skillId}\ndescription: test skill\ncategory: testing\nrisk: safe\nsource: community\ndate_added: "2026-03-22"\n---\n`,
+    "utf8",
+  );
+}
+
+try {
+  makeSkill("brainstorming");
+  makeSkill("systematic-debugging");
+  makeSkill("custom-skill");
+
+  const result = spawnSync(
+    "bash",
+    [scriptPath, "--clear", "brainstorming", "custom-skill"],
+    {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        AG_BASE_DIR: baseDir,
+        AG_REPO_SKILLS_DIR: repoSkills,
+        AG_PYTHON_BIN: "python3",
+      },
+      encoding: "utf8",
+    },
+  );
+
+  assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+  assert.ok(
+    fs.existsSync(path.join(baseDir, "skills", "brainstorming", "SKILL.md")),
+    "brainstorming should be activated into the live skills directory",
+  );
+  assert.ok(
+    fs.existsSync(path.join(baseDir, "skills", "custom-skill", "SKILL.md")),
+    "literal safe skill ids should be activated from the library",
+  );
+  assert.ok(
+    fs.existsSync(path.join(baseDir, "skills_library", "brainstorming", "SKILL.md")),
+    "repo skills should be synced into the backing library",
+  );
+  assert.match(
+    result.stdout,
+    /Done! Antigravity skills are now activated\./,
+    "script should report successful activation",
+  );
+} finally {
+  fs.rmSync(root, { recursive: true, force: true });
+}

tools/scripts/tests/installer_antigravity_guidance.test.js

@@ -0,0 +1,31 @@
+const assert = require("assert");
+const path = require("path");
+
+const installer = require(path.resolve(__dirname, "..", "..", "bin", "install.js"));
+
+const antigravityMessages = installer.getPostInstallMessages([
+  { name: "Antigravity", path: "/tmp/.gemini/antigravity/skills" },
+]);
+
+assert.ok(
+  antigravityMessages.some((message) => message.includes("agent-overload-recovery.md")),
+  "Antigravity installs should point users to the overload recovery guide",
+);
+assert.ok(
+  antigravityMessages.some((message) => message.includes("activate-skills.sh")),
+  "Antigravity installs should mention the Unix activation flow",
+);
+assert.ok(
+  antigravityMessages.some((message) => message.includes("activate-skills.bat")),
+  "Antigravity installs should mention the Windows activation flow",
+);
+
+const codexMessages = installer.getPostInstallMessages([
+  { name: "Codex CLI", path: "/tmp/.codex/skills" },
+]);
+
+assert.strictEqual(
+  codexMessages.some((message) => message.includes("agent-overload-recovery.md")),
+  false,
+  "Non-Antigravity installs should not emit the Antigravity-specific overload hint",
+);

tools/scripts/tests/run-test-suite.js

@@ -8,10 +8,12 @@ const ENABLED_VALUES = new Set(["1", "true", "yes", "on"]);
 const TOOL_SCRIPTS = path.join("tools", "scripts");
 const TOOL_TESTS = path.join(TOOL_SCRIPTS, "tests");
 const LOCAL_TEST_COMMANDS = [
+    [path.join(TOOL_TESTS, "activate_skills_shell.test.js")],
     [path.join(TOOL_TESTS, "activate_skills_batch_security.test.js")],
     [path.join(TOOL_TESTS, "automation_workflows.test.js")],
     [path.join(TOOL_TESTS, "build_catalog_bundles.test.js")],
     [path.join(TOOL_TESTS, "claude_plugin_marketplace.test.js")],
+    [path.join(TOOL_TESTS, "installer_antigravity_guidance.test.js")],
     [path.join(TOOL_TESTS, "jetski_gemini_loader.test.cjs")],
     [path.join(TOOL_TESTS, "npm_package_contents.test.js")],
     [path.join(TOOL_TESTS, "setup_web_sync.test.js")],