Merge commit '1ae927a7db' into dev

surfsense_backend/app/capabilities/core/access/rest.py

@@ -71,6 +71,7 @@ class CapabilitySummary(BaseModel):
 
     name: str
     description: str
+    docs_url: str | None = None
     input_schema: dict
     output_schema: dict
     # Empty list = free (billing disabled or an unmetered verb).
@@ -145,6 +146,7 @@ def _register_capabilities_list(
             CapabilitySummary(
                 name=capability.name,
                 description=capability.description,
+                docs_url=capability.docs_url,
                 input_schema=capability.input_schema.model_json_schema(),
                 output_schema=capability.output_schema.model_json_schema(),
             ),

surfsense_backend/app/capabilities/core/types.py

@@ -62,3 +62,4 @@ class Capability:
     output_schema: type[BaseModel]
     executor: Executor
     billing_unit: BillingUnit | None
+    docs_url: str | None = None

surfsense_backend/app/capabilities/google_maps/reviews/definition.py

@@ -10,15 +10,14 @@ from app.capabilities.google_maps.reviews.schemas import ReviewsInput, ReviewsOu
 GOOGLE_MAPS_REVIEWS = Capability(
     name="google_maps.reviews",
     description=(
-        "Fetch public reviews for one or more Google Maps places. Give it place "
-        "URLs or place IDs; returns structured review items with author, text, "
-        "star rating, like count, owner response, and timestamps. Use it to "
-        "gauge sentiment or pull recent feedback on specific places."
+        "Fetch public Google Maps reviews with authors, ratings, text, and "
+        "owner responses. Use urls or place IDs."
     ),
     input_schema=ReviewsInput,
     output_schema=ReviewsOutput,
     executor=build_reviews_executor(),
     billing_unit=BillingUnit.GOOGLE_MAPS_REVIEW,
+    docs_url="/docs/connectors/native/google-maps",
 )
 
 register_capability(GOOGLE_MAPS_REVIEWS)

surfsense_backend/app/capabilities/google_maps/scrape/definition.py

@@ -11,17 +11,14 @@ from app.capabilities.google_maps.scrape.schemas import ScrapeInput, ScrapeOutpu
 GOOGLE_MAPS_SCRAPE = Capability(
     name="google_maps.scrape",
     description=(
-        "Scrape public Google Maps places. Give it search queries (optionally "
-        "scoped by location), Google Maps URLs, or place IDs, and it returns "
-        "structured place items — name, address, category, phone, website, "
-        "rating, review count, coordinates, and opening hours. Set "
-        "include_details for richer detail-page fields, or max_reviews/"
-        "max_images to attach reviews and photos per place."
+        "Scrape public Google Maps places, details, reviews, and photos. Use "
+        "search_queries, urls, or place IDs."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),
     billing_unit=BillingUnit.GOOGLE_MAPS_PLACE,
+    docs_url="/docs/connectors/native/google-maps",
 )
 
 register_capability(GOOGLE_MAPS_SCRAPE)

surfsense_backend/app/capabilities/google_search/scrape/definition.py

@@ -10,16 +10,14 @@ from app.capabilities.google_search.scrape.schemas import ScrapeInput, ScrapeOut
 GOOGLE_SEARCH_SCRAPE = Capability(
     name="google_search.scrape",
     description=(
-        "Search Google and return structured results. Give it search terms "
-        "(optionally scoped by country/language or to a single site) or full "
-        "Google Search URLs, and it returns SERP items — organic results "
-        "(title, url, description), related queries, people-also-ask, and any "
-        "AI overview. Use max_pages_per_query to page deeper."
+        "Search Google and return structured SERP results. Use search_queries "
+        "or Google Search URLs."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),
     billing_unit=BillingUnit.GOOGLE_SEARCH_SERP,
+    docs_url="/docs/connectors/native/google-search",
 )
 
 register_capability(GOOGLE_SEARCH_SCRAPE)

surfsense_backend/app/capabilities/reddit/scrape/definition.py

@@ -10,16 +10,14 @@ from app.capabilities.reddit.scrape.schemas import ScrapeInput, ScrapeOutput
 REDDIT_SCRAPE = Capability(
     name="reddit.scrape",
     description=(
-        "Scrape public Reddit data. Give it Reddit URLs (post, subreddit, or "
-        "user) and/or search terms, and it returns structured items — posts "
-        "(title, body, score, comment count, subreddit, author), their comments, "
-        "and community/user metadata. Use search_queries (optionally scoped to a "
-        "community) to discover posts, or urls to pull a known post/subreddit/user."
+        "Scrape public Reddit posts, comments, and metadata. Use urls or "
+        "search_queries."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),
     billing_unit=BillingUnit.REDDIT_ITEM,
+    docs_url="/docs/connectors/native/reddit",
 )
 
 register_capability(REDDIT_SCRAPE)

surfsense_backend/app/capabilities/web/crawl/definition.py

@@ -9,29 +9,14 @@ from app.capabilities.web.crawl.schemas import CrawlInput, CrawlOutput
 WEB_CRAWL = Capability(
     name="web.crawl",
     description=(
-        "Scrape a single web page or crawl a whole website. Give it one or more "
-        "startUrls. Set maxCrawlDepth=0 to fetch just those URLs, or higher to "
-        "also follow the links on each page (depth 1 = the start pages plus the "
-        "pages they link to, and so on) — staying on the same site and stopping "
-        "at maxCrawlPages. On a deeper crawl, narrow which links are followed with "
-        "includeUrlPatterns / excludeUrlPatterns (regexes). Returns one item per "
-        "fetched page with clean markdown content, metadata (title, description), "
-        "crawl provenance, every link with its anchor text and kind "
-        "(internal/external/social/email/tel — use the text/context to tie a "
-        "profile URL to a person or company), and contact signals (emails, phone "
-        "numbers, social profiles). The site-wide contacts summary deduplicates "
-        "them with provenance: siteWide=true marks footer/header values (the "
-        "company's own contacts) vs page-local finds (e.g. team members' "
-        "profiles). Useful for lead generation and competitive intelligence; "
-        "contact details often live on about/contact/privacy pages, so crawl "
-        "with maxCrawlDepth >= 1 to surface them. JS-rendered pages are loaded "
-        "in a real browser and auto-scrolled, so lazy-loaded listings "
-        "(directories, infinite-scroll feeds) are captured too."
+        "Scrape pages or crawl websites for clean markdown, links, metadata, "
+        "and contact signals. Use startUrls and crawl-depth controls."
     ),
     input_schema=CrawlInput,
     output_schema=CrawlOutput,
     executor=build_crawl_executor(),
     billing_unit=BillingUnit.WEB_CRAWL,
+    docs_url="/docs/connectors/native/web-crawl",
 )
 
 register_capability(WEB_CRAWL)

surfsense_backend/app/capabilities/youtube/comments/definition.py

@@ -10,15 +10,14 @@ from app.capabilities.youtube.comments.schemas import CommentsInput, CommentsOut
 YOUTUBE_COMMENTS = Capability(
     name="youtube.comments",
     description=(
-        "Fetch public comments (and their replies) for one or more YouTube "
-        "videos. Give it the video URLs; returns structured comment items with "
-        "author, text, like count, reply relationships, and timestamps. Use it "
-        "to gauge sentiment or pull discussion on specific videos."
+        "Fetch public YouTube comments and replies with authors, text, likes, "
+        "and timestamps. Use video URLs."
     ),
     input_schema=CommentsInput,
     output_schema=CommentsOutput,
     executor=build_comments_executor(),
     billing_unit=BillingUnit.YOUTUBE_COMMENT,
+    docs_url="/docs/connectors/native/youtube",
 )
 
 register_capability(YOUTUBE_COMMENTS)

surfsense_backend/app/capabilities/youtube/scrape/definition.py

@@ -10,16 +10,14 @@ from app.capabilities.youtube.scrape.schemas import ScrapeInput, ScrapeOutput
 YOUTUBE_SCRAPE = Capability(
     name="youtube.scrape",
     description=(
-        "Scrape public YouTube data. Give it YouTube URLs (video, channel, "
-        "playlist, shorts, or hashtag) and/or search queries, and it returns "
-        "structured video items — title, views, likes, publish date, channel "
-        "info, description, and optionally subtitles. Use search_queries to "
-        "discover videos, or urls to pull a known video/channel/playlist."
+        "Scrape public YouTube videos, channels, playlists, and subtitles. Use "
+        "urls or search_queries."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
     executor=build_scrape_executor(),
     billing_unit=BillingUnit.YOUTUBE_VIDEO,
+    docs_url="/docs/connectors/native/youtube",
 )
 
 register_capability(YOUTUBE_SCRAPE)