[Feat]: Gemini adapter polish — sanitization tests, doc template, optional catalog lint

[rosspeili]

Feature Description

Follow-up polish after #223 / PR #229 (to_gemini_tool() returns types.Tool with sanitized names). Core fix and required doc updates land in that PR; this issue tracks regression prevention and contributor guidance so Gemini snippets do not drift back.

Scope

1. Test coverage — extend tests/test_loader.py:

   • Assert finance/wallet_screening → finance_wallet_screening in to_gemini_tool() output
   • Assert return type is google.genai.types.Tool (not dict)

2. Contributor docs — short additions:

   • docs/usage/gemini.md — one paragraph on dispatch: match function_call.name to sanitized name (SkillLoader._sanitize_function_tool_name(manifest["name"])) or adapter-derived name
   • docs/usage/skill_usage_template.md — same rule for new skill catalog Gemini blocks

3. CHANGELOG hygiene — if Fix: to_gemini_tool to return types.Tool object. Fixes #223 #229 only lists under Fixed, add Changed bullet noting to_gemini_tool() return type change (dict → types.Tool) for programmatic callers

4. Guardrail — extend tests/test_registry_docs.py or add tests/test_skill_docs_gemini.py to fail when docs/skills/*.md Gemini sections contain:

   • tool_decl["name"] / gemini_decl["name"] mutation
   • types.Tool(function_declarations=[ manual wrap after to_gemini_tool()
   • function_call.name == bundle["manifest"]["name"] without sanitize (registry IDs with /)

Out of scope

• Re-fixing docs covered in Fix: to_gemini_tool to return types.Tool object. Fixes #223 #229 (agent_loops.md, cli.md, five catalog pages)
• [Feat]: Automated check — skill catalog pages include all five provider Usage Examples #104 (five provider sections present)
• [Docs]: Audit runnable examples for manifest-derived tool name dispatch #178 (examples/*.py dispatch)
• Loader behavior changes

Rationale

#229 fixes the bug and aligns examples; without guardrails, catalog pages and copy-paste snippets can regress (we already had manual types.Tool workarounds in three skill docs). A sanitization test is cheap insurance. An optional markdown lint catches the same failure mode #178 addresses for examples, but for docs/skills/ where agents copy integration code verbatim.

Implementation Idea

Phase 1 (minimal — good first issue)

Add to test_to_gemini_tool:

dummy_bundle = {
    "manifest": {
        "name": "finance/wallet_screening",
        "parameters": {"type": "object", "properties": {}},
    }
}
tool = SkillLoader.to_gemini_tool(dummy_bundle)
assert tool.function_declarations[0].name == "finance_wallet_screening"

Update gemini.md + skill_usage_template.md with canonical dispatch one-liner.

Phase 2

Parametrize over docs/skills/*.md (exclude README); regex or simple string checks for anti-patterns listed above. Grandfather none after #229 doc pass is merged.

Acceptance

• Sanitization test in tests/test_loader.py
• gemini.md + skill_usage_template.md mention sanitized dispatch
• CHANGELOG Changed note if not already in Fix: to_gemini_tool to return types.Tool object. Fixes #223 #229
• (Optional) CI doc lint for Gemini anti-patterns in skill catalog
• Depends on [Bug]: SkillLoader.to_gemini_tool() returns raw dict instead of types.Tool, breaking all Gemini examples #223 / Fix: to_gemini_tool to return types.Tool object. Fixes #223 #229 merged first