Site knowledge

Site knowledge exposes your customer website corpus to MCP agents — product copy, pricing, docs, policies, in-app UI text indexed from HTTP crawl and session recordings, plus operator-uploaded references (briefs, PDFs, markdown). It is separate from vTilt platform docs (search_docs) and separate from per-visitor replay transcripts (recording_summaries).

The site-knowledge toolset appears automatically when site knowledge is enabled on your pinned project. Enable it under Project → Site Knowledge if the tools are missing from get_context. No enable_toolset step is required once the feature is on.

#How it works

Three capture sources feed one index:

• HTTP crawl — public, externally reachable pages.
• Session-recording DOM — pages reconstructed from session recordings, covering auth-gated / internal pages the crawler can't reach.
• Operator references — uploaded .txt / .md / text-layer .pdf files indexed through the same chunker.

Each capture is cleaned to markdown, chunked, embedded, and stored. The storage is split into three families:

• Latest / serving (site_pages, site_knowledge_chunks, site_page_elements, site_overview) — the current state of each page plus reference chunks. Embeddings + the vector index live here, so semantic search always runs against current content. (site_page_chunks is accepted as a VQL alias for site_knowledge_chunks.)
• History / append-on-change (site_page_versions, site_page_version_chunks) — one row per detected page change, text-only (no embeddings). Powers change history and change→impact attribution.
• Extension (brand profile, mirrored media) — populated during crawl. Event snapshots remain planned.

Dual change signal: a new page version is captured when either content_hash (page text) or elements_hash (the ordered CTA/link/nav fingerprint, by document order + above-fold) changes — so a layout move like "the CTA moved above the fold" is detected even when the copy is identical. site_page_versions.change_kind records which fired (created / content / layout / both).

#The tools

All require analytics:read and site knowledge enabled on the project. Check get_context.features.site_knowledge.

#get_site_overview

Returns the LLM-generated project synopsis, taxonomy JSON, indexed page count, and last update time. Call this first when orienting on an unfamiliar project.

{
  "synopsis": "B2B analytics platform focused on privacy-first web tracking…",
  "taxonomy_json": "{\"product_areas\":[…],\"audiences\":[…]}",
  "page_count": 47,
  "updated_at": "2026-06-24T04:12:00Z"
}

#list_site_pages

Paginated sitemap with crawl metadata.

Returns page_type, version_count, last_changed_at, and last_seen_at per row alongside the title and summary.

Not for: top pages by traffic — use get_kpis or run_query on events.

#get_site_page

Full page metadata plus every content chunk. Provide pathname (e.g. /pricing) or url.

{
  "page": {
    "url": "https://www.example.com/pricing",
    "pathname": "/pricing",
    "title": "Pricing",
    "source": "hybrid",
    "auth_gated": false,
    "summary": "Three-tier SaaS pricing with annual billing…",
    "meta_description": "…",
    "og_title": "Pricing",
    "og_image_url": "https://www.example.com/og/pricing.png",
    "json_ld_types": ["Product", "Offer"],
    "canonical_url": "https://www.example.com/pricing",
    "lang": "en",
    "page_type": "marketing",
    "http_status": 200,
    "chunk_count": 6,
    "version_count": 4,
    "last_changed_at": "2026-06-21T09:00:00Z",
    "last_seen_at": "2026-06-24T04:12:00Z",
    "screenshot_desktop_url": "https://…signed…/pricing-desktop.png",
    "screenshot_mobile_url": "https://…signed…/pricing-mobile.png"
  },
  "chunks": [
    {
      "chunk_index": 0,
      "chunk_kind": "pricing",
      "heading_path": "Pricing > Plans",
      "content": "## Plans\n\nStarter includes…"
    }
  ]
}

screenshot_desktop_url and screenshot_mobile_url are Class B workspace-authenticated URLs for humans to open in a browser (null when that viewport was not captured). Legacy screenshot_url aliases the desktop URL when present. Do not HTTP-fetch these URLs from agent egress (Claude.ai blocks external hosts) — call get_site_page_screenshots for vision pixels. Returns resource_not_found when the pathname was never indexed — try list_site_pages or trigger a re-crawl in the dashboard.

#get_site_page_screenshots

Opt-in agent vision for one crawl screenshot. Pass pathname and viewport (desktop | mobile, default desktop). Optional version_id for a historical shot.

Returns:

1. JSON metadata (pathname, viewport, tile_count, Class B url for humans, images[] with tile dimensions)
2. MCP image content blocks (WebP base64) — the full page, width-scaled ≤1568px and auto-split into up to 6 vertical tiles when tall

Use this when you must see layout / CTAs. Use get_site_page for copy and SEO without loading pixels into context. Tiling improves fidelity; it does not remove host payload/session limits.

#search_site_knowledge

Semantic search over chunk embeddings across crawled pages and uploaded references.

{
  "results": [
    {
      "source": "page",
      "reference_id": null,
      "url": "https://www.example.com/pricing",
      "pathname": "/pricing",
      "title": "Pricing",
      "heading_path": "Pricing > Plans",
      "chunk_kind": "pricing",
      "content": "Starter includes…",
      "distance": 0.12
    }
  ]
}

#list_site_references / get_site_reference

Browse and read operator-uploaded references (.txt / .md / text-layer .pdf). list_site_references returns id, title, filename, status, and chunk counts. get_site_reference takes reference_id and returns metadata plus extracted content when ready.

Not for: short project description / business instructions in settings — use get_site_business_context.

Lower distance = closer semantic match (cosine distance).

#get_site_brand_profile

Resolved brand kit for on-brand creative (emails, ads, reports). No inputs beyond project scope.

#list_page_versions

The change timeline for one page. Provide pathname (required) and optional limit (default 20, max 50). Returns captured versions newest-first with change_kind, human-readable change_summary, content_hash + elements_hash, cta_fingerprint_count, chunk_count, and signed screenshot_desktop_url + screenshot_mobile_url — no chunk text.

#get_page_version

One historical version's full content, CTA fingerprint, and desktop/mobile screenshots. Provide pathname and version_id (both required; get version_id from list_page_versions). Use for restore or "what did the hero say before the change".

#diff_page_versions

Structured before/after between two version ids without pulling full chunk text twice. Provide pathname, version_id_a, and version_id_b. Returns summary, cta_changes[], section_changes[], inferred_change_kind, and both versions' screenshot pairs.

#correlate_page_change_impact

Automated change→impact attribution — compare a metric before vs after a page version's captured_at without hand-rolling VQL.

Returns before / after counts and rates, rate_change_percent, the version's change_summary, and a one-line insight narrative (e.g. "signup_completed rate rose 32% after the hero CTA moved…").

Tip: list_recent_events and run_query also add properties.$site_element_label on $autocapture rows when the crawl index resolves a human button/CTA label.

#get_site_elements

Raw structured element inventory for one page — CTAs, links, forms, buttons, nav, headings, images in document order.

Returns text, href, tag, role, selector, elements_chain, document_order, above_fold, and link health per element. Use it for CRO audits (missing/weak CTA), funnel-gap detection (compare against tracked $autocapture events), and turning a clicked selector / $elements_chain into its human label.

#get_site_business_context

The operator-provided tier-0 business context — short text from project settings (project description + business instructions), as opposed to crawled pages or uploaded reference files. Returns project_description and business_instructions. Use for onboarding, grounding, and on-brand outbound.

Not for: uploaded PDF/md briefs — use list_site_references / get_site_reference / search_site_knowledge with source=reference.

#VQL tables

Site knowledge tables use the same :embed('text') macro as AI memory when site knowledge is enabled. See AI intelligence for macro rules and error codes.

site_page_chunks is accepted as a VQL alias and rewritten to site_knowledge_chunks.

Every table is tenant-scoped — do not add project_id to your WHERE clause.

Change detection → impact attribution: site_page_versions gets one row each time a page's text (content_hash) or layout (elements_hash) changes. Join captured_at against events.timestamp to correlate a site change with a metric shift (e.g. a conversion lift after a CTA moved). site_page_elements inventories the interactive elements on each page for CRO audits and funnel-gap checks.

#Example: semantic search with a source filter

SELECT
  source,
  source_id,
  heading_path,
  chunk_kind,
  content,
  cosineDistance(embedding, :embed('enterprise SSO pricing')) AS distance
FROM site_knowledge_chunks
WHERE source = 'page' AND source_id = '/pricing'
ORDER BY distance ASC
LIMIT 10

#Example: join page content with session behavior

Combine indexed copy with AI memory when analyzing whether visitors read pricing before converting:

SELECT
  s.session_id,
  s.narrative,
  JSONExtractString(s.ai, 'pages_visited') AS pages,
  r.engagement_score,
  r.behavior_pattern
FROM session_summaries s
JOIN recording_summaries r ON r.session_id = s.session_id
WHERE s.started_at > now() - INTERVAL 7 DAY
  AND has(JSONExtractArrayRaw(s.ai, 'pages_visited'), '"/pricing"')
ORDER BY s.started_at DESC
LIMIT 25

For section-level "what did they read on pricing?", query recording_chunks instead — see AI intelligence.

#When to use which surface

#Example agent prompts

#Cost model

#Related

• Site knowledge (guide) — crawl pipeline, sources, dashboard, prerequisites
• Agent skills — the /vtilt:site-knowledge slash-command prompt (full architecture + query patterns)
• AI intelligence — AI memory, recording summaries, :embed() macro
• MCP server overview — authentication, toolsets, and full tool catalog