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

docs/users/agent-overload-recovery.md

@@ -0,0 +1,54 @@
+# Antigravity Recovery for Context Overload and Truncation
+
+Use this guide when Antigravity loads too many skills for the current task and starts failing with truncation, context, or trajectory-conversion errors.
+
+Typical symptoms:
+
+- the agent crashes only when a large skills folder is present
+- the error mentions truncation, context conversion, or a trajectory/message that cannot be converted
+- the problem shows up more often on large repositories or long-running tasks
+
+## Linux and macOS fast path
+
+Use the activation scripts to keep the full library archived while exposing only the bundles or skills you need in the live Antigravity directory.
+
+1. Fully close Antigravity.
+2. Clone this repository somewhere local if you do not already have a clone.
+3. Run the activation script from the cloned repository.
+
+Examples:
+
+```bash
+./scripts/activate-skills.sh "Web Wizard" "Integration & APIs"
+./scripts/activate-skills.sh --clear
+./scripts/activate-skills.sh brainstorming systematic-debugging
+```
+
+What the script does:
+
+- syncs the repository `skills/` tree into `~/.gemini/antigravity/skills_library`
+- preserves your full library in the backing store
+- activates only the requested bundles or skill ids into `~/.gemini/antigravity/skills`
+- `--clear` archives the current live directory first, then restores the selected set
+
+Optional environment overrides:
+
+```bash
+AG_BASE_DIR=/custom/antigravity ./scripts/activate-skills.sh --clear Essentials
+AG_REPO_SKILLS_DIR=/path/to/repo/skills ./scripts/activate-skills.sh brainstorming
+```
+
+## Windows recovery
+
+If Antigravity is stuck in a restart loop on Windows, use the Windows-specific recovery guide instead:
+
+- [windows-truncation-recovery.md](windows-truncation-recovery.md)
+
+That guide covers the browser/app storage cleanup needed when the host keeps reopening the same broken session.
+
+## Prevention tips
+
+- start with 3-5 skills from a bundle instead of exposing the full library at once
+- use bundle activation before opening very large repositories
+- keep role-specific stacks active and archive the rest
+- if a host stores broken session state, clear that host state before restoring a smaller active set

docs/users/faq.md

@@ -154,6 +154,14 @@ It includes:
 - the default Antigravity Windows paths to back up first
 - an optional batch script adapted from [issue #274](https://github.com/sickn33/antigravity-awesome-skills/issues/274)
 
+### I hit context overload on Linux or macOS. What should I do?
+
+If Antigravity becomes unstable only when the full skills library is active, switch to the activation flow instead of exposing every skill at once:
+
+- [agent-overload-recovery.md](agent-overload-recovery.md)
+
+That guide shows how to run `scripts/activate-skills.sh` from a cloned copy of this repository so only the bundles or skill ids you need stay active in `~/.gemini/antigravity/skills`.
+
 ### How do I update skills?
 
 Navigate to your skills directory and pull the latest changes:

docs/users/getting-started.md

@@ -142,6 +142,9 @@ A: Yes! Use the **@skill-creator** skill to build your own.
 **Q: What if Antigravity on Windows gets stuck in a truncation crash loop?**
 A: Follow the recovery steps in [windows-truncation-recovery.md](windows-truncation-recovery.md). It explains which Antigravity storage folders to back up and clear, and includes an optional batch helper adapted from [issue #274](https://github.com/sickn33/antigravity-awesome-skills/issues/274).
 
+**Q: What if Antigravity overloads on Linux or macOS when too many skills are active?**
+A: Use the activation flow in [agent-overload-recovery.md](agent-overload-recovery.md). It shows how to run `scripts/activate-skills.sh` from a cloned repo so you can keep the full library archived and activate only the bundles or skills you need in the live Antigravity directory.
+
 **Q: Is this free?**
 A: Yes. Original code and tooling are MIT-licensed, and original documentation/non-code written content is CC BY 4.0. See [../../LICENSE](../../LICENSE) and [../../LICENSE-CONTENT](../../LICENSE-CONTENT).
 

docs/users/usage.md

@@ -40,7 +40,7 @@ Bundles are **recommended lists** of skills grouped by role. They help you decid
 
 ❌ Separate installations  
 ❌ Different download commands  
-❌ Something you need to "activate"
+❌ Something most users need to activate during normal install
 
 ### Example: The "Web Wizard" Bundle