docs: add subscription token limits & Goose comparison

Enrichir la section subscription limits (ultimate-guide.md):
- Tableau des budgets tokens par plan (Pro 44K, Max 88-220K)
- Ratio Opus/Sonnet 8-10× documenté explicitement
- Clarification "heures" = temps de traitement, pas tokens
- Lien vers ccusage (outil communautaire de monitoring)
- Note historique sur réductions non annoncées (Oct 2025)

Nouvelle section Goose dans ai-ecosystem.md:
- Comparaison technique Claude Code vs Goose (7 critères)
- Stats GitHub (15K+ stars, 350+ contributors)
- Use cases et trade-offs honnêtes
- Hardware requirements selon LLM
- Quick start avec commandes d'installation

Sources: Perplexity research (Jan 2026), official Anthropic docs,
community reports (Reddit, GitHub issues, HN).

Co-Authored-By: Claude <noreply@anthropic.com>

guide/ai-ecosystem.md

@@ -20,6 +20,7 @@
 - [9. Cost & Subscription Strategy](#9-cost--subscription-strategy)
 - [10. Claude Cowork (Research Preview)](#10-claude-cowork-research-preview)
 - [11. AI Coding Agents Matrix](#11-ai-coding-agents-matrix)
+- [11.1 Goose: Open-Source Alternative (Block)](#111-goose-open-source-alternative-block)
 - [12. Context Packing Tools](#12-context-packing-tools)
 - [Appendix: Ready-to-Use Prompts](#appendix-ready-to-use-prompts)
 - [Alternative Providers (Community Workarounds)](#alternative-providers-community-workarounds)
@@ -1113,6 +1114,98 @@ An **interactive comparison matrix** of 23 AI coding agents across 11 technical
 
 ---
 
+## 11.1 Goose: Open-Source Alternative (Block)
+
+For developers hitting Claude Code's subscription limits or needing model flexibility, [Goose](https://github.com/block/goose) is a notable open-source alternative worth understanding.
+
+### What Is Goose?
+
+An **on-machine AI coding agent** developed by Block (formerly Square), released under Apache 2.0 license. Unlike Claude Code, Goose runs entirely locally and is **model-agnostic**—it can use Claude, GPT, Gemini, Groq, or any LLM provider.
+
+| Metric | Value (Jan 2026) |
+|--------|------------------|
+| **GitHub Stars** | 15,400+ |
+| **Contributors** | 350+ |
+| **Releases** | 100+ since Jan 2025 |
+| **License** | Apache 2.0 (permissive) |
+| **Primary Language** | Rust (64%) + TypeScript (26%) |
+
+### Claude Code vs Goose: Key Differences
+
+| Aspect | Claude Code | Goose |
+|--------|-------------|-------|
+| **LLM Flexibility** | Claude only | Any LLM (GPT, Gemini, Claude, Groq, local models) |
+| **Deployment** | Cloud (Anthropic servers) | Local only (on your machine) |
+| **Cost Model** | Subscription ($20-$200/mo) | Free + your LLM API costs |
+| **Rate Limits** | Anthropic's weekly/5-hour caps | Your LLM provider's limits |
+| **Token Visibility** | Opaque (no per-prompt tracking) | Full transparency |
+| **MCP Support** | Native (growing ecosystem) | 3,000+ MCP servers available |
+| **Setup Complexity** | Simple (npm install) | Moderate (Rust toolchain, API keys) |
+
+### When to Consider Goose
+
+**Good fit**:
+- You're hitting Claude Code's weekly limits frequently
+- You need model flexibility (e.g., GPT for some tasks, Claude for others)
+- You require full cost visibility and control
+- You work with large, multi-language codebases requiring aggressive refactoring
+- You want offline capability (with local models like Ollama)
+
+**Poor fit**:
+- You want simplicity over flexibility
+- You prefer fixed monthly cost vs. variable API billing
+- You value Claude's specific reasoning capabilities and can't substitute
+- You don't want to manage LLM API credentials
+
+### Trade-offs
+
+| Goose Advantage | Goose Limitation |
+|-----------------|------------------|
+| No subscription limits | LLM API costs can escalate unpredictably |
+| Model choice | Requires self-managed API keys |
+| Full token transparency | No built-in cross-session memory |
+| Open source (contribute back) | Smaller user base, fewer tutorials |
+| Offline with local models | Local models inferior for complex tasks |
+
+### Hardware Requirements
+
+Goose itself is lightweight (Rust binary). The requirements depend on your LLM choice:
+
+| LLM Type | Requirements |
+|----------|-------------|
+| **Cloud APIs** (Claude, GPT, Gemini) | Minimal (just network access) |
+| **Local models** (Ollama, etc.) | 16-32GB RAM, GPU recommended for larger models |
+
+### Quick Start
+
+```bash
+# macOS
+brew install goose
+
+# Or via cargo
+cargo install goose-cli
+
+# Configure LLM provider
+goose configure
+```
+
+See [Goose Quickstart](https://block.github.io/goose/docs/quickstart/) for detailed setup.
+
+### Positioning
+
+Goose is **not a replacement** for Claude Code—it's an alternative with different trade-offs. The right choice depends on your priorities:
+
+| Priority | Choose |
+|----------|--------|
+| Simplicity, Claude's reasoning | Claude Code |
+| Cost control, model flexibility | Goose |
+| Fixed monthly budget | Claude Code subscription |
+| Pay-per-use, no limits | Goose + API |
+
+For most developers already invested in Claude Code workflows, the switching cost is significant. Goose is most valuable for teams needing model diversity or developers frequently hitting Claude Code's limits.
+
+---
+
 ## 12. Context Packing Tools
 
 When working with LLMs on large codebases, **context packing** refers to techniques for extracting and feeding relevant code context to the model efficiently.

guide/ultimate-guide.md

@@ -1936,23 +1936,41 @@ Monthly cost estimate: $50-$200 for 5-10 developers
 
 **How Subscription Limits Work**
 
-Unlike API usage (pay-per-token), subscriptions use a different model:
+Unlike API usage (pay-per-token), subscriptions use a hybrid model that's deliberately opaque:
 
 | Concept | Description |
 |---------|-------------|
-| **Message windows** | Limits reset periodically (e.g., every few hours), not daily |
-| **Hybrid counting** | Advertised as "messages" but actual capacity varies by message length, attachments, and context size |
-| **Weekly caps** | Higher tiers may have weekly limits to prevent continuous 24/7 usage |
-| **Model weighting** | Opus consumes quota faster than Sonnet; Haiku is lightest |
+| **5-hour rolling window** | Primary limit; resets when you send next message after 5 hours lapse |
+| **Weekly aggregate cap** | Secondary limit; resets every 7 days. Both apply simultaneously |
+| **Hybrid counting** | Advertised as "messages" but actual capacity is token-based, varying by code complexity, file size, and context |
+| **Model weighting** | **Opus consumes 8-10× more quota than Sonnet** for equivalent work |
+
+**Approximate Token Budgets by Plan** (Jan 2026, community-verified)
+
+| Plan | 5-Hour Token Budget | Weekly Sonnet Hours | Weekly Opus Hours | Claude Code Access |
+|------|---------------------|---------------------|-------------------|-------------------|
+| **Free** | 0 | 0 | 0 | ❌ None |
+| **Pro** ($20/mo) | ~44,000 tokens | 40-80 hours | N/A (Sonnet only) | ✅ Limited |
+| **Max 5x** ($100/mo) | ~88,000-220,000 tokens | 140-280 hours | 15-35 hours | ✅ Full |
+| **Max 20x** ($200/mo) | ~220,000+ tokens | 240-480 hours | 24-40 hours | ✅ Full |
+
+> **Warning**: These are community-measured estimates. Anthropic does not publish exact token limits, and limits have been reduced without announcement (notably Oct 2025). The 8-10× Opus/Sonnet ratio means Max 20x users get only ~24-40 Opus hours weekly despite paying $200/month.
+
+**Why "Hours" Are Misleading**
+
+The term "hours of Sonnet 4" refers to **elapsed wall-clock time** during active processing, not calendar hours. This is not directly convertible to tokens without knowing:
+- Code complexity (larger files = higher per-token overhead)
+- Tool usage (Bash execution adds ~245 input tokens per call; text editor adds ~700)
+- Context re-reads and caching misses
 
 **Tier-Specific Strategies**
 
 | If you have... | Recommended approach |
 |----------------|---------------------|
+| **Pro plan** | Sonnet only; batch sessions, avoid context bloat |
 | **Limited Opus quota** | OpusPlan essential: Opus for planning, Sonnet for execution |
-| **Moderate quota** | Sonnet default, Opus only for architecture/complex debugging |
-| **Generous quota** | More Opus freedom, but still monitor weekly usage |
-| **Unlimited/high tier** | Use Opus freely, focus on productivity over optimization |
+| **Max 5x** | Sonnet default, Opus only for architecture/complex debugging |
+| **Max 20x** | More Opus freedom, but still monitor weekly usage (24-40h goes fast) |
 
 **The Pro User Pattern** (validated by community):
 
@@ -1970,8 +1988,12 @@ This is exactly what OpusPlan mode does automatically (see Section 2.3).
 /status    # Shows current session: cost, context %, model
 ```
 
+Anthropic provides no in-app real-time usage metrics. Community tools like [`ccusage`](https://github.com/ryoppippi/ccusage) help track token consumption across sessions.
+
 For subscription usage history: Check your [Anthropic Console](https://console.anthropic.com/settings/usage) or Claude.ai settings.
 
+**Historical Note**: In October 2025, users reported significant undocumented limit reductions coinciding with Sonnet 4.5's release. Pro users who previously sustained 40-80 Sonnet hours weekly reported hitting limits after only 6-8 hours. Anthropic acknowledged the limits but did not explain the discrepancy.
+
 ### Context Poisoning (Bleeding)
 
 **Definition**: When information from one task contaminates another.

machine-readable/reference.yaml

@@ -78,7 +78,10 @@ deep_dive:
   context_triage: 1448
   session_vs_memory: 1481
   fresh_context_pattern: 1525
-  subscription_limits: 1914
+  subscription_limits: 1933
+  subscription_token_budgets: 1948
+  subscription_opus_ratio: 1946
+  subscription_monitoring: 1985
   plan_mode: 2100
   rewind: 2278
   mental_model: 2360
@@ -174,7 +177,9 @@ deep_dive:
   ai_ecosystem_workflows: 10590
   ai_ecosystem_integration: 10716
   ai_ecosystem_detailed: "guide/ai-ecosystem.md"
-  ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1114"
+  ai_ecosystem_goose: "guide/ai-ecosystem.md:1116"
+  ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:1132"
+  ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1208"
   ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:449"
   ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:959"
   voice_refine_skill: "examples/skills/voice-refine/SKILL.md"