[Mate] Add Knowledge bridge to crawl official documentation

[wachterjohannes]

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues	-
License	MIT

Summary

Introduces a new Mate bridge — symfony/ai-knowledge-mate-extension — that gives agents structured access to official documentation through MCP tools (browse TOC, read pages, substring search). The goal is to replace "guessing from training data" with crawling the actual docs.

This bridge does not ship semantic / vector / RAG search. A SearcherInterface extension seam is provided so a future implementation can plug in embedding-based search without changing the tool surface.

The Symfony bridge ships a built-in SymfonyDocsProvider for symfony/symfony-docs that registers itself when the Knowledge bridge is also installed (interface_exists() guard). The cloned docs branch is auto-detected from the host application's installed Symfony version via Composer\InstalledVersions (probing symfony/framework-bundle → symfony/runtime → symfony/http-kernel → symfony/dependency-injection) and can be pinned explicitly with ai_mate_symfony.docs_branch.

Tools

Tool	Purpose
knowledge-toc	Without arguments: list providers. With a provider: browse its TOC at path (or root).
knowledge-read	Read a documentation page split into RST sections (response is capped — see below).
knowledge-search	Case-insensitive substring search across a provider's chunks (limit capped at 50).

Behavior

• The first call for a provider clones the source repo (git clone --depth 1) into the local cache.
• Subsequent calls hit the cache.
• The cache auto-refreshes once it's older than ai_mate_knowledge.cache_ttl_seconds (default 24h).
• Section-based chunking reuses Symfony\AI\Store\Document\Loader\RstLoader so chunking semantics stay aligned with the Store component.
• Concurrent ensure() calls are safe: a per-provider flock serializes work, and the toc/chunks/metadata JSON files are written atomically (temp + rename).
• Provider names must match ^[a-z0-9][a-z0-9_-]{0,63}$ so they can't escape the cache dir or be used as shell metacharacters.
• A metadata.json is written next to the cache artifacts (provider, synced_at, chunk_count, git revision when available) for debugging.

Adding a custom provider

use Symfony\AI\Mate\Bridge\Knowledge\Provider\DocsProviderInterface;
use Symfony\AI\Mate\Bridge\Knowledge\Service\GitFetcher;

final class MyDocsProvider implements DocsProviderInterface
{
    public function __construct(private GitFetcher $fetcher) {}

    public function getName(): string { return 'my-docs'; }
    public function getTitle(): string { return 'My Docs'; }
    public function getDescription(): string { return 'My project documentation'; }
    public function getFormat(): string { return 'rst'; }

    public function sync(string $cacheDir): string
    {
        $repo = $cacheDir.'/docs';
        $this->fetcher->fetch('https://github.com/me/docs.git', 'main', $repo);

        return $repo.'/index.rst';
    }
}

Tag the service ai_mate.knowledge_provider.

Future-proofing

The chunk model (PageChunk) already matches what Symfony\AI\Store\Document\Vectorizer consumes, and a SearcherInterface seam is exposed so an embedding-based searcher can replace KeywordSearcher without changing the tool surface. An indexer seam (over the JSON cache step) would be the other half — left out for now to keep scope tight (YAGNI).

Test plan

• Knowledge bridge: 39/39 PHPUnit tests pass (services, models, registry, tools, TTL behavior, atomic writes, metadata, provider-name validation, RST edge cases — title aliases, absolute entries, missing files, duplicate entries, glob entries)
• Symfony bridge: 118/118 tests pass (114 pre-existing + 3 SymfonyDocsProvider unit tests covering auto-detection vs. explicit-branch override + 1 end-to-end integration test wiring SymfonyDocsProvider → ProviderRegistry → KnowledgeCache → all three MCP tools against a local bare git repo)
• PHPStan clean on Knowledge bridge
• doctor-rst clean on docs change
• End-to-end: SymfonyDocsProviderIntegrationTest exercises a real git clone from a local bare repo through every tool (knowledge-toc → knowledge-read → knowledge-search) and asserts the cache artifacts (toc.json, chunks.json, metadata.json) land on disk with the expected shape.