Create NotebookLM integration skill for automated documentation updates

[coisa]

Objective

Create a NotebookLM skill (with reference implementation guidance from skills.sh/giuseppe-trisciuoglio/developer-kit/notebooklm) and a documentation skill that keeps the PHP Fast Forward documentation notebooks synchronized from repository docs changes.

Current Limitation

Agents currently have no standardized way to push documentation updates directly into NotebookLM, and there is no consistent strategy for selecting the right notebook per repository. This increases drift between repo docs and centralized knowledge stores, especially in non-fast-forward consumer repos where no default notebook exists.

Proposed Work

• Add a new skill (and/or reference package) in php-fast-forward/dev-tools for interacting with NotebookLM APIs for documentation updates.
• Add a companion documentation skill to collect source paths and trigger notebook updates from docs/release/wikidata changes.
• Define a deterministic notebook selection strategy:
  • Preferred: repository-specific local config (e.g., .github/notebooklm.json or equivalent skill config).
  • Fallback 1: Fast Forward org default notebook for php-fast-forward repositories.
  • Fallback 2: explicit --notebook-id / FF_NOTEBOOK_ID when no local config exists.
  • Fallback 3: interactive/manual prompt for a verified notebook ID in CI-disabled/ambiguous environments.
• For non-fast-forward consumer repositories, require an explicit external notebook target in repo config or CI secret, so the consumer owns its documentation notebook while still reusing the same skill.
• Include secure authentication guidance in the skill (token/credentials naming, secret handling, redaction and no logging).
• Define expected update payload structure (doc path, heading title, summary, source link, related PR/issue metadata).
• Include retry and idempotency behavior (skip unchanged docs, hash-based change detection, safe retries on transient failures).

Scope

• In-scope: skill design, configuration model for notebook selection, docs sync trigger contract.
• In-scope: documentation and reference workflow for local/CI execution.
• Out-of-scope: final production rollout of all consumers and notebooks in this first issue.

Non-goals

• No direct UI changes in NotebookLM itself.
• No full API migration from existing docs workflow; this issue only covers initial skill and sync strategy.
• No guarantee of automatic notebook discovery when no configuration is available.

Suggested Implementation Plan

1. Define skill metadata and interface in .agents/skills/notebooklm/:
   • resolveTargetNotebook()
   • loadRepositoryNotebookConfig()
   • collectDocumentationInputs()
   • publishDocumentSummaryToNotebook()
2. Create skill reference template with inputs:
   • --notebook-id, --notebook-family, --repo-slug, --dry-run, --force-update.
3. Add docs skill (docs-notebook-sync or similar) that inspects documentation changes and invokes NotebookLM sync.
4. Add fallback matrix and security notes:
   • Linux/macOS/Windows installation path,
   • credential missing behavior,
   • non-fast-forward repository guidance.

Acceptance Criteria

Delivery Criteria

• A NotebookLM interaction skill reference is created in php-fast-forward/dev-tools (or clearly planned).
• A documentation-specific skill exists to synchronize documentation updates into NotebookLM from supported repo paths.
• Notebook selection strategy is deterministic, auditable, and supports explicit repo-level override.
• Non-fast-forward repos can define their own NotebookLM target without hardcoding Fast Forward notebooks.

Functional Criteria

• Skill supports at least:
  • explicit notebook ID via config/arg/env,
  • repository defaulting rules for fast-forward repos,
  • safe fallback when no notebook can be resolved.
• Credentials are passed through existing secret/config patterns and are not committed.
• Documentation update workflow produces reproducible payload shape and includes source references.

Documentation / Content Criteria

• MUST: The affected documentation or content MUST follow the repository's existing information architecture and naming conventions.
• MUST: Related navigation, cross-links, or synchronized outputs MUST be updated when the change affects them.
• MUST: Examples, commands, and file paths MUST remain accurate for the current repository behavior.
• MUST: The update MUST avoid duplicating content that should live in a single canonical location.

Open Questions

• Confirm preferred config file path for notebook selection (e.g., .github/notebooklm.json versus .codex/notebooklm.json) to avoid collisions with existing tooling.

Related Work

• Related to issue #350 (component preference/curation) because both topics concern implementation dependency/tool selection policy.