@roomi-fields/notebooklm-mcp 1.5.7 → 1.5.9

package/docs/archive/auto-discovery-complet.md

@@ -1,906 +0,0 @@
-# Auto-Discovery Notebooks - Cahier des charges complet
-
-## 0. Vision & Contexte stratégique
-
-### 0.1 Problème actuel
-
-Les utilisateurs de MCP NotebookLM doivent **manuellement** :
-- Nommer chaque notebook
-- Inventer des tags pertinents
-- Écrire des descriptions
-- Deviner quand interroger quel notebook
-
-**Résultat** : Bibliothèque mal organisée, discovery impossible, friction maximale.
-
-### 0.2 Solution : Progressive Disclosure autonome
-
-Inspiré par **Claude Skills best practices** ([doc officielle](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns)), ce système permet une **découverte progressive et autonome** des ressources documentaires.
-
-**Architecture en 3 niveaux** :
-
-**Niveau 0 - Startup (ultra-léger)** :
-```
-library.json chargé en mémoire
-├── cnv-pratique-essentiels: "Manuel CNV couvrant 4 étapes..."
-├── n8n-workflows-api: "Documentation complète API n8n..."
-└── react-hooks-guide: "Guide React Hooks et state management..."
-```
-*Coût : ~500 tokens, instantané*
-
-**Niveau 1 - Matching contextuel** :
-```
-User: "Je veux automatiser Gmail avec n8n"
-→ Scan metadata (tags: ["n8n", "gmail", "automation"])
-→ Match: "n8n-workflows-api" (score: 95%)
-→ Décision : interroger ce notebook
-```
-*Coût : 0 query NotebookLM (juste matching local)*
-
-**Niveau 2 - Query profonde** :
-```
-→ Query NotebookLM: "Comment utiliser le node Gmail dans n8n?"
-→ Réponse précise depuis documentation
-```
-*Coût : 1 query NotebookLM (rate-limited mais ciblée)*
-
-### 0.3 Bénéfice clé : Découverte autonome
-
-**Avant (manuel)** :
-```
-User → "Utilise le notebook X" → Claude query X
-```
-*L'humain doit savoir quel notebook utiliser*
-
-**Après (autonome)** :
-```
-User → "Automatise Gmail" → Système découvre automatiquement → Query notebook pertinent
-```
-*L'orchestrateur (Claude/n8n/Cursor) découvre seul les ressources pertinentes*
-
-### 0.4 Cas d'usage orchestrateurs
-
-#### Claude Code - Workflow autonome
-
-```
-1. User: "Build a Gmail spam filter workflow with n8n"
-
-2. Claude (discovery interne):
-   - Scan library metadata
-   - Match tags: ["n8n", "gmail", "workflows"]
-   - Trouve: "n8n-workflows-api"
-
-3. Claude (query ciblée):
-   - "How does Gmail integration work in n8n?"
-   - NotebookLM → réponse précise
-
-4. Claude (implémentation):
-   - Code le workflow avec infos exactes
-   - Zéro hallucination
-```
-
-**Sans auto-discovery** : Claude devrait lire tous les notebooks (coûteux) ou demander à l'utilisateur (friction).
-
-#### n8n - Automation intelligente
-
-```yaml
-HTTP Request: GET /notebooks/match?task=gmail automation
-→ Retourne: notebook pertinent
-
-HTTP Request: POST /notebooks/{id}/ask
-→ Query: "What Gmail triggers are available?"
-→ Response: documentation précise
-
-Function Node:
-→ Parse response → Configure Gmail node automatiquement
-```
-
-**Bénéfice** : n8n peut **auto-découvrir** la documentation nécessaire sans intervention humaine.
-
-#### Cursor / IDEs - Contextual matching
-
-```typescript
-// Developer demande
-"How do I use the n8n API to create a workflow?"
-
-// IDE via MCP
-find_relevant_notebook({ task: "n8n API workflow creation" })
-→ Match: "n8n-workflows-api"
-
-// Query automatique
-ask_notebook({ question: "API endpoint for workflow creation?" })
-→ Response avec citations sources
-```
-
-### 0.5 Avantage compétitif
-
-**Feature killer unique** :
-- ❌ PleasePrompto : pas d'auto-discovery
-- ❌ khengyun : pas d'auto-discovery  
-- ✅ **roomi-fields : SEUL avec auto-discovery autonome**
-
-**Impact produit** :
-- Friction = 0 (30 secondes vs 5 minutes par notebook)
-- Discovery autonome (orchestrateurs self-serve)
-- Library auto-organisée (scalable à 50+ notebooks)
-
-### 0.6 Documentation publique à produire
-
-**README.md** doit inclure :
-```markdown
-## 🔍 Auto-Discovery : Self-Organizing Documentation
-
-The **only MCP NotebookLM server** with autonomous resource discovery.
-
-Add notebook → System auto-generates metadata → Orchestrators discover resources autonomously.
-
-Perfect for:
-- ✅ Teams with 10+ documentation notebooks
-- ✅ n8n workflows needing dynamic doc access
-- ✅ Claude Code autonomous research
-- ✅ Onboarding new developers
-```
-
-**API docs** doit expliquer :
-- Progressive disclosure pattern (3 niveaux)
-- Comment orchestrateurs utilisent le matching
-- Économie de rate limits Google
-
----
-
-## 1. Spécifications techniques
-
-### 1.1 Modifications du schema
-
-#### Fichier `src/types/notebook.ts`
-
-```typescript
-interface Notebook {
-  id: string;
-  url: string;
-  name: string;              // 3 mots max, kebab-case
-  description: string;       // 2 phrases, 150 chars max
-  tags: string[];            // 8-10 keywords
-  created_at: string;
-  last_queried?: string;
-  auto_generated: boolean;   // NOUVEAU : indique si metadata auto-générée
-}
-```
-
-#### Fichier `src/library/library-manager.ts`
-
-**Ajouter méthode de validation :**
-
-```typescript
-validateMetadata(metadata: NotebookMetadata): void {
-  // Vérifie :
-  // - name: kebab-case, 3 mots max, pas de spaces, pas d'espaces
-  // - description: <= 150 chars
-  // - tags: 8-10 éléments
-  // Throw error avec message précis si invalide
-}
-```
-
----
-
-### 1.2 Nouveau module Auto-Discovery
-
-#### Créer `src/auto-discovery/auto-discovery.ts`
-
-```typescript
-class AutoDiscovery {
-  constructor(private notebookClient: NotebookLMClient) {}
-
-  /**
-   * Query le notebook pour obtenir ses métadonnées
-   * Retry automatique en cas d'échec (max 2 fois)
-   */
-  async discoverMetadata(notebookUrl: string, maxRetries = 2): Promise<NotebookMetadata> {
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      try {
-        // 1. Ouvre le notebook via notebookClient
-        // 2. Envoie le prompt (voir generatePrompt())
-        // 3. Parse la réponse JSON (voir parseResponse())
-        // 4. Valide le format (voir validateMetadata())
-        // 5. Retourne metadata
-        return await this._discover(notebookUrl);
-      } catch (error) {
-        if (attempt === maxRetries) throw error;
-        await this.delay(2000); // Wait 2s before retry
-      }
-    }
-  }
-
-  /**
-   * Parse et valide la réponse JSON de NotebookLM
-   */
-  private parseResponse(response: string): NotebookMetadata {
-    // 1. Nettoie markdown code blocks si présents
-    let cleaned = response.replace(/```json\n?/g, '').replace(/```\n?/g, '').trim();
-    
-    // 2. Parse JSON
-    const parsed = JSON.parse(cleaned);
-    
-    // 3. Valide structure
-    this.validateMetadata(parsed);
-    
-    return parsed;
-  }
-
-  /**
-   * Valide que la metadata respecte les règles
-   */
-  private validateMetadata(metadata: NotebookMetadata): void {
-    // name: kebab-case, 3 mots max
-    const nameRegex = /^[a-z0-9]+(-[a-z0-9]+){0,2}$/;
-    if (!nameRegex.test(metadata.name)) {
-      throw new Error(`Invalid name format: "${metadata.name}". Must be kebab-case, 3 words max.`);
-    }
-
-    // description: <= 150 chars
-    if (metadata.description.length > 150) {
-      throw new Error(`Description too long: ${metadata.description.length} chars (max 150)`);
-    }
-
-    // tags: 8-10 éléments
-    if (metadata.tags.length < 8 || metadata.tags.length > 10) {
-      throw new Error(`Invalid tags count: ${metadata.tags.length} (must be 8-10)`);
-    }
-  }
-
-  /**
-   * Génère le prompt pour NotebookLM
-   */
-  private generatePrompt(): string {
-    return `Analyze your complete content and respond ONLY in this JSON format:
-
-{
-  "name": "example-notebook-name",
-  "description": "First sentence describes main topic. Second sentence adds key details.",
-  "tags": ["keyword1", "keyword2", "keyword3", "keyword4", "keyword5", "keyword6", "keyword7", "keyword8"]
-}
-
-Rules:
-- name: 3 words maximum, kebab-case format (e.g., "react-hooks-guide", "n8n-api-docs")
-- description: exactly 2 sentences, total length under 150 characters
-- tags: between 8 and 10 keywords covering:
-  * Core concepts (3-4 tags like "react", "hooks", "state")
-  * Actions/verbs (2-3 tags like "debugging", "testing")
-  * Use contexts (2-3 tags like "frontend", "api", "automation")
-
-OUTPUT ONLY VALID JSON. NO OTHER TEXT.`;
-  }
-
-  private delay(ms: number): Promise<void> {
-    return new Promise(resolve => setTimeout(resolve, ms));
-  }
-}
-```
-
----
-
-### 1.3 Nouvelle route HTTP
-
-#### Modifier `src/http/routes/notebooks.ts`
-
-```typescript
-router.post('/notebooks/auto-discover', async (req, res) => {
-  try {
-    const { url } = req.body;
-    
-    // Validation
-    if (!url || !url.includes('notebooklm.google.com')) {
-      return res.status(400).json({ 
-        error: 'Invalid NotebookLM URL',
-        expected: 'https://notebooklm.google.com/notebook/...'
-      });
-    }
-
-    // 1. Auto-discover metadata
-    const autoDiscovery = new AutoDiscovery(notebookClient);
-    const metadata = await autoDiscovery.discoverMetadata(url);
-
-    // 2. Créer notebook avec metadata
-    const notebook = await libraryManager.addNotebook({
-      url,
-      ...metadata,
-      auto_generated: true
-    });
-
-    // 3. Retourner résultat
-    res.json({
-      success: true,
-      notebook,
-      message: 'Notebook auto-discovered and added to library'
-    });
-
-  } catch (error) {
-    // Gestion erreurs détaillée
-    if (error.message.includes('Invalid name format')) {
-      return res.status(500).json({ 
-        error: 'NotebookLM returned invalid metadata format',
-        details: error.message
-      });
-    }
-    
-    res.status(500).json({ 
-      error: error.message,
-      hint: 'NotebookLM might have returned invalid format. Try again.'
-    });
-  }
-});
-```
-
----
-
-### 1.4 Gestion des erreurs
-
-| Cas d'erreur | Code HTTP | Message |
-|--------------|-----------|---------|
-| URL invalide | 400 | "Invalid NotebookLM URL" |
-| Notebook inaccessible | 404 | "Notebook not found or not accessible" |
-| Réponse NotebookLM invalide | 500 | "NotebookLM returned invalid format" |
-| Timeout NotebookLM | 504 | "NotebookLM query timeout (>30s)" |
-| Format JSON invalide | 500 | "Could not parse NotebookLM response" |
-| Validation metadata échouée | 500 | "Generated metadata is invalid: [details]" |
-
----
-
-## 2. Tests
-
-### 2.1 Tests unitaires
-
-#### Créer `tests/auto-discovery.test.ts`
-
-```typescript
-describe('AutoDiscovery', () => {
-  let autoDiscovery: AutoDiscovery;
-  
-  beforeEach(() => {
-    autoDiscovery = new AutoDiscovery(mockNotebookClient);
-  });
-
-  test('should parse valid JSON response', () => {
-    const response = `{
-      "name": "test-notebook-name",
-      "description": "Test description sentence one. Test description sentence two.",
-      "tags": ["tag1", "tag2", "tag3", "tag4", "tag5", "tag6", "tag7", "tag8"]
-    }`;
-    
-    const metadata = autoDiscovery.parseResponse(response);
-    expect(metadata.name).toBe('test-notebook-name');
-    expect(metadata.tags).toHaveLength(8);
-  });
-
-  test('should reject invalid name format (spaces)', () => {
-    const response = `{"name": "Invalid Name With Spaces", "description": "...", "tags": [...]}`;
-    expect(() => autoDiscovery.parseResponse(response)).toThrow('Invalid name format');
-  });
-
-  test('should reject invalid name format (too many words)', () => {
-    const response = `{"name": "too-many-words-in-name", ...}`;
-    expect(() => autoDiscovery.parseResponse(response)).toThrow('Invalid name format');
-  });
-
-  test('should reject too few tags', () => {
-    const response = `{"name": "valid-name", "description": "...", "tags": ["tag1", "tag2"]}`;
-    expect(() => autoDiscovery.parseResponse(response)).toThrow('Invalid tags count');
-  });
-
-  test('should reject too many tags', () => {
-    const response = `{"tags": ["t1","t2","t3","t4","t5","t6","t7","t8","t9","t10","t11"], ...}`;
-    expect(() => autoDiscovery.parseResponse(response)).toThrow('Invalid tags count');
-  });
-
-  test('should clean markdown code blocks', () => {
-    const response = "```json\n{\"name\": \"test\", ...}\n```";
-    const metadata = autoDiscovery.parseResponse(response);
-    expect(metadata.name).toBe('test');
-  });
-
-  test('should retry on failure', async () => {
-    // Mock failure then success
-    mockNotebookClient.query
-      .mockRejectedValueOnce(new Error('Timeout'))
-      .mockResolvedValueOnce('{"name": "test", ...}');
-    
-    const metadata = await autoDiscovery.discoverMetadata('url');
-    expect(metadata.name).toBe('test');
-  });
-});
-```
-
-### 2.2 Test PowerShell
-
-#### Créer `deployment/scripts/test-auto-discovery.ps1`
-
-```powershell
-# Test auto-discovery endpoint
-$url = "http://localhost:3000/notebooks/auto-discover"
-$body = @{
-    url = "https://notebooklm.google.com/notebook/test-123"
-} | ConvertTo-Json
-
-Write-Host "Testing auto-discovery endpoint..." -ForegroundColor Cyan
-
-try {
-    $response = Invoke-RestMethod -Uri $url -Method POST -Body $body -ContentType "application/json"
-    
-    Write-Host "✓ Auto-discovery successful" -ForegroundColor Green
-    Write-Host "  Name: $($response.notebook.name)" -ForegroundColor White
-    Write-Host "  Description: $($response.notebook.description)" -ForegroundColor White
-    Write-Host "  Tags: $($response.notebook.tags -join ', ')" -ForegroundColor White
-    Write-Host "  Auto-generated: $($response.notebook.auto_generated)" -ForegroundColor White
-    
-} catch {
-    Write-Host "✗ Test failed: $($_.Exception.Message)" -ForegroundColor Red
-    exit 1
-}
-```
-
----
-
-## 3. Documentation
-
-### 3.1 Mettre à jour `README.md`
-
-**Ajouter section après "HTTP REST API" :**
-
-```markdown
-## 🔍 Auto-Discovery : Self-Organizing Documentation
-
-NotebookLM MCP is the **only MCP server** with autonomous resource discovery.
-
-### How it works
-
-**1. Add notebook** (zero manual metadata):
-```bash
-curl -X POST http://localhost:3000/notebooks/auto-discover \
-  -H "Content-Type: application/json" \
-  -d '{"url": "https://notebooklm.google.com/notebook/YOUR_ID"}'
-```
-
-**2. System queries NotebookLM** to auto-generate:
-- Kebab-case name (3 words max)
-- Concise description (2 sentences)
-- Relevant tags (8-10 keywords)
-
-**3. Orchestrators discover autonomously**:
-- Claude Code finds relevant docs without prompting
-- n8n workflows auto-select documentation
-- Cursor matches context to notebooks
-
-### Progressive disclosure pattern
-
-Inspired by [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns):
-
-- **Level 0** (startup): Lightweight metadata loaded (~500 tokens)
-- **Level 1** (matching): Local tag/description search (0 NotebookLM queries)
-- **Level 2** (deep query): Targeted NotebookLM query only when needed
-
-### Why this matters
-
-**Before**: Manual library management, orchestrators can't discover resources autonomously
-
-**After**: Self-organizing library, autonomous documentation discovery
-
-Perfect for:
-- ✅ Teams with 10+ documentation notebooks
-- ✅ n8n workflows needing dynamic doc access
-- ✅ Claude Code autonomous research
-- ✅ Onboarding new developers without manual setup
-
-### Example workflow
-
-```bash
-# 1. Add documentation notebooks (auto-discover metadata)
-curl -X POST /notebooks/auto-discover -d '{"url": "https://notebooklm.google.com/notebook/n8n-docs"}'
-curl -X POST /notebooks/auto-discover -d '{"url": "https://notebooklm.google.com/notebook/react-guide"}'
-
-# 2. Claude Code autonomously discovers relevant notebook
-User: "Build Gmail automation with n8n"
-→ System matches: "n8n-docs" (tags: ["n8n", "gmail", "automation"])
-→ Query NotebookLM: "Gmail node configuration?"
-→ Claude implements with accurate info
-
-# 3. Zero hallucinations, zero manual intervention
-```
-```
-
-### 3.2 Mettre à jour `deployment/docs/03-API.md`
-
-**Ajouter section :**
-
-```markdown
-### POST `/notebooks/auto-discover`
-
-Automatically generate notebook metadata by querying NotebookLM itself.
-
-**Request:**
-```json
-{
-  "url": "https://notebooklm.google.com/notebook/abc123"
-}
-```
-
-**Response (Success):**
-```json
-{
-  "success": true,
-  "notebook": {
-    "id": "generated-uuid",
-    "url": "https://notebooklm.google.com/notebook/abc123",
-    "name": "cnv-pratique-essentiels",
-    "description": "Manuel CNV couvrant 4 étapes fondamentales. Inclut exercices d'auto-empathie et écoute.",
-    "tags": [
-      "cnv",
-      "empathie",
-      "communication",
-      "besoins",
-      "sentiments",
-      "demandes",
-      "conflits",
-      "authenticité"
-    ],
-    "auto_generated": true,
-    "created_at": "2025-01-23T10:00:00Z"
-  },
-  "message": "Notebook auto-discovered and added to library"
-}
-```
-
-**Response (Error):**
-```json
-{
-  "error": "NotebookLM returned invalid metadata format",
-  "details": "Invalid name format: \"Invalid Name\". Must be kebab-case, 3 words max."
-}
-```
-
-**Errors:**
-- `400 Bad Request`: Invalid URL format
-- `404 Not Found`: Notebook not accessible
-- `500 Internal Server Error`: NotebookLM query failed or returned invalid format
-- `504 Gateway Timeout`: NotebookLM query timeout (>30s)
-
-**How it works:**
-
-1. System opens the specified notebook
-2. Sends prompt to NotebookLM asking it to analyze its own content
-3. NotebookLM responds with JSON containing name, description, and tags
-4. System validates the metadata format
-5. Saves notebook to library with auto-generated metadata
-
-**Progressive Disclosure Pattern:**
-
-This endpoint enables the **Level 0** of progressive disclosure:
-- Metadata stored locally (lightweight, ~100 bytes per notebook)
-- Loaded at startup for instant matching
-- Deep queries to NotebookLM only when notebook is selected
-
-Orchestrators (Claude Code, n8n, Cursor) can scan all notebook metadata without rate limit concerns, then query NotebookLM only for the most relevant notebook.
-```
-
-### 3.3 Créer `deployment/docs/07-AUTO-DISCOVERY.md`
-
-**Nouveau document dédié :**
-
-```markdown
-# Auto-Discovery Pattern
-
-## Overview
-
-Auto-Discovery enables autonomous resource discovery for AI orchestrators. Instead of manually cataloging notebooks, the system queries NotebookLM to generate its own metadata.
-
-## Architecture
-
-### Three-Level Progressive Disclosure
-
-**Level 0 - Metadata Registry (Lightweight)**
-```
-library.json: 5KB for 50 notebooks
-├── Loaded at startup
-├── Cached in memory
-└── Zero NotebookLM queries
-```
-
-**Level 1 - Contextual Matching (Local)**
-```
-User query → Tag/description matching → Relevant notebooks
-Example: "gmail automation" → Match tags: ["gmail", "n8n", "automation"]
-Cost: 0 NotebookLM queries (local only)
-```
-
-**Level 2 - Deep Query (Rate-Limited)**
-```
-Selected notebook → Query NotebookLM → Precise answer
-Cost: 1 NotebookLM query (rate-limited by Google)
-```
-
-## For Orchestrators
-
-### Claude Code
-
-```typescript
-// Autonomous workflow
-User: "Build n8n Gmail workflow"
-
-// Claude internally:
-1. Scan library metadata (instant)
-2. Match: "n8n-workflows-api" (tags: ["n8n", "gmail"])
-3. Query NotebookLM: "Gmail node configuration?"
-4. Implement with accurate info
-```
-
-### n8n
-
-```yaml
-# Workflow node
-HTTP Request: GET /notebooks/match?task=gmail automation
-→ Returns: relevant notebook
-
-HTTP Request: POST /notebooks/{id}/ask
-→ Query: "Available Gmail triggers?"
-→ Response: precise documentation
-```
-
-### Cursor / IDEs
-
-```typescript
-// Context-aware matching
-Developer: "How to use n8n API?"
-→ MCP: find_relevant_notebook({ task: "n8n API" })
-→ Match: "n8n-workflows-api"
-→ Query notebook for details
-```
-
-## Metadata Generation
-
-### Prompt to NotebookLM
-
-The system sends this prompt to each notebook:
-
-```
-Analyze your complete content and respond ONLY in JSON format:
-{
-  "name": "kebab-case-name",
-  "description": "Two sentences max.",
-  "tags": ["8-10", "keywords", "covering", "concepts", "actions", "contexts"]
-}
-```
-
-### Validation Rules
-
-- **name**: 3 words max, kebab-case, no spaces
-- **description**: 2 sentences, under 150 chars
-- **tags**: 8-10 keywords (concepts + actions + contexts)
-
-### Example Generated Metadata
-
-```json
-{
-  "name": "n8n-workflows-api",
-  "description": "Complete n8n API documentation covering workflow creation and node configuration. Includes authentication, webhooks, and error handling.",
-  "tags": [
-    "n8n",
-    "api",
-    "workflows",
-    "automation",
-    "webhooks",
-    "nodes",
-    "integration",
-    "documentation"
-  ]
-}
-```
-
-## Benefits
-
-### For Users
-- **Zero friction**: 30 seconds to add notebook (vs 5 minutes manual)
-- **No metadata expertise**: System generates relevant tags automatically
-- **Scalable**: Works with 1 or 100 notebooks
-
-### For Orchestrators
-- **Autonomous discovery**: Find relevant docs without human guidance
-- **Token efficient**: Metadata scan costs ~500 tokens (vs 50k+ full read)
-- **Rate limit preservation**: 1 query per notebook add (vs N queries per research)
-
-### For Product
-- **Unique feature**: Only NotebookLM MCP with auto-discovery
-- **Better UX**: Frictionless notebook management
-- **Competitive advantage**: Clear differentiator vs other implementations
-
-## Comparison with Claude Skills
-
-| Aspect | Claude Skills | NotebookLM Auto-Discovery |
-|--------|---------------|---------------------------|
-| Metadata source | SKILL.md file | NotebookLM query |
-| Access cost | Free (local files) | Rate-limited (Google API) |
-| Content depth | Full docs bundled | Query on-demand |
-| Discovery pattern | Read files progressively | Match → Query if needed |
-| Update mechanism | Edit files | Re-query notebook |
-
-**Key difference**: Skills are free/local, Notebooks are rate-limited/remote
-→ **Auto-Discovery optimizes for minimal queries via smart metadata matching**
-
-## Error Handling
-
-### Common Issues
-
-**Invalid metadata format**:
-```json
-{
-  "error": "Invalid name format",
-  "details": "Must be kebab-case, 3 words max"
-}
-```
-→ System retries with same prompt (max 2 retries)
-
-**NotebookLM timeout**:
-```json
-{
-  "error": "NotebookLM query timeout",
-  "hint": "Try again in a few seconds"
-}
-```
-→ Rate limit hit, wait and retry
-
-**Notebook not accessible**:
-```json
-{
-  "error": "Notebook not found",
-  "hint": "Check notebook URL and sharing settings"
-}
-```
-→ Verify notebook is shared with "Anyone with link"
-
-## Future Enhancements
-
-### Phase 2: Smart Refresh
-```typescript
-PATCH /notebooks/:id/refresh
-→ Re-query NotebookLM to update metadata if content changed
-```
-
-### Phase 3: Semantic Matching
-```typescript
-GET /notebooks/match?query=gmail&semantic=true
-→ Use embeddings for advanced matching beyond tags
-```
-
-### Phase 4: Usage Analytics
-```typescript
-GET /notebooks/:id/related
-→ "Notebooks often queried together"
-```
-```
-
----
-
-## 4. Ordre d'implémentation
-
-1. **Schema** : Modifier `src/types/notebook.ts` (5 min)
-2. **Auto-discovery classe** : Créer `src/auto-discovery/auto-discovery.ts` avec prompt et validation (30 min)
-3. **Route HTTP** : Ajouter endpoint `/auto-discover` dans `src/http/routes/notebooks.ts` (20 min)
-4. **Validation** : Ajouter méthode `validateMetadata` dans library-manager (15 min)
-5. **Tests unitaires** : Créer `tests/auto-discovery.test.ts` (20 min)
-6. **Test PowerShell** : Créer script `test-auto-discovery.ps1` (10 min)
-7. **Documentation** : Mettre à jour README, API docs, créer doc auto-discovery (25 min)
-8. **Test manuel** : Valider avec vrai notebook NotebookLM (10 min)
-
-**Durée totale estimée : ~2h15**
-
----
-
-## 5. Livrables attendus
-
-### Code
-- [ ] `src/types/notebook.ts` modifié (ajout champ `auto_generated`)
-- [ ] `src/auto-discovery/auto-discovery.ts` créé (classe complète avec prompt)
-- [ ] `src/http/routes/notebooks.ts` modifié (nouveau endpoint POST `/auto-discover`)
-- [ ] `src/library/library-manager.ts` modifié (méthode `validateMetadata`)
-
-### Tests
-- [ ] `tests/auto-discovery.test.ts` créé (tous les tests passent)
-- [ ] `deployment/scripts/test-auto-discovery.ps1` créé (test manuel automatisé)
-- [ ] Test manuel avec vrai notebook NotebookLM validé
-
-### Documentation
-- [ ] `README.md` section "Auto-Discovery" ajoutée
-- [ ] `deployment/docs/03-API.md` endpoint `/auto-discover` documenté
-- [ ] `deployment/docs/07-AUTO-DISCOVERY.md` créé (doc complète pattern)
-- [ ] Exemples curl inclus dans documentation
-
-### Validation
-- [ ] Endpoint fonctionne avec notebook réel
-- [ ] Format JSON validé (name kebab-case, description 150 chars, 8-10 tags)
-- [ ] Erreurs bien gérées avec messages clairs
-- [ ] Retry logic fonctionne (2 tentatives max)
-- [ ] Tests PowerShell passent
-
----
-
-## 6. Critères d'acceptation
-
-✅ **Fonctionnel**
-- L'endpoint `/notebooks/auto-discover` retourne metadata valide
-- Le prompt NotebookLM génère JSON conforme aux règles
-- Les metadata sont sauvegardées correctement dans library.json
-- Les erreurs sont gérées avec messages explicites
-- Le retry logic fonctionne (max 2 tentatives, wait 2s)
-
-✅ **Qualité code**
-- TypeScript avec types stricts (pas de `any`)
-- Tests unitaires couvrent cas principaux (valid, invalid, retry)
-- Validation stricte des metadata (throw errors précis)
-- Code commenté pour parties critiques (prompt, validation)
-
-✅ **Documentation**
-- README explique clairement la feature et son avantage unique
-- API doc complète avec exemples request/response
-- Doc dédiée explique le pattern progressive disclosure
-- Exemples curl testables fournis
-
-✅ **User Experience**
-- Message de succès clair avec metadata générée affichée
-- Messages d'erreur explicites avec hints pour résoudre
-- Temps de réponse acceptable (< 30 secondes typical)
-
----
-
-## 7. Notes importantes
-
-⚠️ **Rate limits Google** : NotebookLM a des limites quotidiennes par compte Google. Le retry logic (max 2 tentatives, wait 2s) aide mais ne résout pas le rate limit. Documenter clairement dans l'API.
-
-⚠️ **Format JSON strict** : NotebookLM peut wrapper le JSON dans des code blocks markdown (```json\n...\n```). Le parser DOIT nettoyer avant parse, sinon échec garanti.
-
-⚠️ **Validation stricte** : Mieux rejeter metadata invalide que d'accepter data corrompue. Throw errors avec messages précis pour aider au debug.
-
-⚠️ **Prompt critique** : Le prompt est LA pièce maîtresse. Il doit être ultra-clair, pas d'ambiguïté. Tested avec un vrai notebook avant implémentation.
-
-💡 **Feature unique** : Aucun autre MCP NotebookLM n'a l'auto-discovery → avantage compétitif majeur. À mettre en avant dans toute la communication (README, doc, réseaux sociaux).
-
-💡 **Documentation = Produit** : La doc publique (README, API docs) doit expliquer le "pourquoi" (progressive disclosure, autonomous discovery) pas juste le "comment" (endpoint technique). C'est ce qui différencie d'une simple API.
-
----
-
-## 8. Après l'implémentation
-
-### Communication externe
-
-**GitHub** :
-- Release notes v1.3.0 : "Auto-Discovery feature"
-- README badge : "🔍 Auto-Discovery"
-
-**LinkedIn / X / Reddit** :
-```
-🚀 New feature: Auto-Discovery for NotebookLM MCP
-
-Add a notebook URL → System auto-generates metadata → AI orchestrators discover resources autonomously.
-
-The ONLY NotebookLM MCP with progressive disclosure pattern.
-
-Perfect for teams with 10+ documentation notebooks.
-
-[Link to repo]
-```
-
-**Dev.to article** :
-"Building Self-Organizing Documentation Libraries with NotebookLM MCP"
-
-### Metrics à suivre
-
-- **Adoption** : % utilisateurs qui utilisent `/auto-discover` vs ajout manuel
-- **Accuracy** : % metadata valides générées (target >95%)
-- **Performance** : Temps moyen de discovery (target <20s)
-- **Error rate** : % échecs (rate limit, invalid format, etc.)
-
-### Next iterations
-
-**Phase 2** : Smart refresh (PATCH `/notebooks/:id/refresh`)
-**Phase 3** : Semantic matching (embeddings)
-**Phase 4** : Usage analytics (notebooks related, popular tags)
-
----
-
-**Ce cahier des charges est complet et prêt pour Claude Code.**