docs: consolidate docs to Provably website and cleanup

.github/workflows/ci.yml

@@ -39,15 +39,6 @@ jobs:
       - name: Pytest (e2e)
         run: uv run pytest tests/e2e -q
 
-      - name: Sphinx
-        run: uv run sphinx-build -W -b html docs docs/_build/html
-
-      - name: Upload built docs as artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          name: github-pages
-          path: docs/_build/html
-
       - name: Build package
         run: uv build
 
@@ -70,14 +61,3 @@ jobs:
 
       - name: Smoke-import SDK from runtime image
         run: docker run --rm sourcerykit:runtime
-
-  # deploy-docs:
-  #   runs-on: ubuntu-latest
-  #   needs: lint-and-test
-  #   steps:
-  #     - name: Setup Pages
-  #       uses: actions/configure-pages@v5
-
-  #     - name: Deploy to GitHub Pages
-  #       id: deployment
-  #       uses: actions/deploy-pages@v4

.github/workflows/sync-docs.yml

@@ -0,0 +1,29 @@
+name: Sync Docs to Website
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'cookbooks/**'
+      - 'README.md'
+      - 'CHANGELOG.md'
+      - 'CONTRIBUTING.md'
+      - 'LICENSE.md'
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ secrets.DOCS_SYNC_APP_ID }}
+          private-key: ${{ secrets.DOCS_SYNC_APP_PRIVATE_KEY }}
+          repositories: fe-web
+
+      - uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          repository: ProvablyAI/fe-web
+          event-type: sync-docs
+          client-payload: '{"sha": "${{ github.sha }}"}'

AGENTS.md

@@ -57,7 +57,7 @@ cookbook's README covers its own wiring.
 
 ## The flow at a glance
 
-```
+```bash
 bootstrap_system()              # init: schema, handshake, HTTP interceptor — call first, once
 insert_trusted_endpoint(url)    # allow-list each outbound endpoint
 async_intercept_context(...)    # wrap the tool's HTTP call — records it

Makefile

@@ -15,8 +15,6 @@ UV ?= uv
 PYTEST_ARGS ?= --cov=sourcerykit --cov-report=term-missing --cov-fail-under=60
 RUFF_ARGS ?=
 MYPY_TARGETS ?= src tests
-DOCS_DIR ?= docs
-DOCS_BUILD ?= $(DOCS_DIR)/_build
 
 .DEFAULT_GOAL := help
 
@@ -116,26 +114,20 @@ bump-pr: ## Bump version, commit, push branch (usage: make bump-pr TYPE=beta)
 	git push -u origin HEAD
 
 tag: ## Create and push a version tag from current HEAD
-	VERSION=$$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml) && \
-	CHANGELOG=$$(awk "/^## $$VERSION/{found=1;next} /^## /{if(found)exit} found{print}" CHANGELOG.md | sed '/./,$!d') && \
+	@VERSION=$$(sed -n '/^\[project\]/,/^\[/p' pyproject.toml | sed -n 's/^version = "\(.*\)"/\1/p') && \
+	CHANGELOG=$$(awk "/^## \[?$$VERSION\]?/{found=1;next} /^## /{if(found)exit} found{print}" CHANGELOG.md | sed '/./,$$!d') && \
 	git tag -a v$$VERSION -m "$$CHANGELOG" && \
 	git push origin v$$VERSION
 
-# --- docs -------------------------------------------------------------------
-
-.PHONY: docs
-docs: ## Build Sphinx HTML under docs/_build
-	$(UV) run sphinx-build -W -b html $(DOCS_DIR) $(DOCS_BUILD)
-
 # --- meta workflows ---------------------------------------------------------
 
 .PHONY: check
-check: pre-commit test docs build ## Run the full CI-equivalent gate
+check: pre-commit test build ## Run the full CI-equivalent gate
 
 .PHONY: clean
 clean: ## Remove build artifacts and cache directories
 	rm -rf build/ dist/ *.egg-info src/*.egg-info \
-	       $(DOCS_BUILD) \
+	       docs/_build \
 	       .pytest_cache .ruff_cache .mypy_cache \
 	       .coverage .coverage.* htmlcov coverage.xml
 	find . -type d -name __pycache__ -prune -exec rm -rf {} +

README.md

@@ -78,7 +78,7 @@ export SOURCERYKIT_ORG_ID="..."
 export SOURCERYKIT_POSTGRES_URL="postgresql://user:password@host:5432/db"
 ```
 
-For a full list of CLI commands, check out the [CLI Documentation](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/cli.md) file, or simply run:
+For a full list of CLI commands, check out the [CLI Documentation](https://provably.ai/docs/getting_started/cli) file, or simply run:
 ```bash
 sourcerykit --help
 ```
@@ -154,14 +154,14 @@ async def run_verifiable_agent():
 Want to dig into the details? Check out our documentation and specific guides:
 
 * **Official Documentation:** Visit [provably.ai/docs](https://provably.ai/docs) for the complete reference.
-* [End-to-End Walkthrough](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/example.md) — Get up and running from scratch.
+* [End-to-End Walkthrough](https://provably.ai/docs/getting_started/end-to-end-walkthrough) — Get up and running from scratch.
 * [Cookbooks & Examples](https://github.com/ProvablyAI/sourcerykit/tree/main/cookbooks) — Practical recipes and code samples.
 
 ### Technical Guides
-- [Architecture Overview](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/architecture.md)
-- [HTTP Interception](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/intercept.md)
-- [Managing Trusted Endpoints](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/trusted-endpoints.md)
-- [Handoff Contracts & Evaluation](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/handoff.md)
+- [Architecture Overview](https://provably.ai/docs/pillars/architecture)
+- [HTTP Interception](https://provably.ai/docs/pillars/interceptor)
+- [Managing Trusted Endpoints](https://provably.ai/docs/pillars/trusted-endpoints)
+- [Handoff Contracts & Evaluation](https://provably.ai/docs/pillars/handoff)
 
 
 ## Contributing

cookbooks/README.md

@@ -1,25 +1,26 @@
-# SourceryKit Cookbooks
+# Cookbooks
 
 Runnable examples demonstrating SourceryKit integration with popular agent frameworks.
 
 ## Single-Agent Examples
 
 | Framework | Description | Domain |
 |---|---|---|
-| [OpenAI Agents SDK](openai_agents) | Basic agent with tool interception | Weather |
-| [LangChain](langchain_agent) | LangChain agent integration | Weather |
-| [Claude Agent SDK](claude_agent) | Claude agent integration | Weather |
+| [OpenAI Agents SDK](https://provably.ai/docs/cookbooks/openai_agents) | Basic agent with tool interception | Weather |
+| [LangChain](https://provably.ai/docs/cookbooks/langchain_agent) | LangChain agent integration | Weather |
+| [Claude Agent SDK](https://provably.ai/docs/cookbooks/claude_agent) | Claude agent integration | Weather |
+| [Claude Agent SDK](https://provably.ai/docs/cookbooks/claude_agent_multi_tool) | Multi-tool-call verification | Weather |
 
 ## Multi-Agent Examples
 
 | Framework | Description | Domain | Pattern |
 |---|---|---|---|
-| [LangGraph](langgraph_multi_agent) | Sequential pipeline with conditional routing | Travel agency | Fetcher → Evaluator → Healer |
-| [CrewAI](crewai_multi_agent) | Flow with specialist agents | Invoice auditing | Specialists → Build → Evaluate |
-| [OpenAI Agents SDK](openai_agents_multi_agent) | Orchestrator-driven verification | Customer support | Orchestrator → Specialists → Verify |
+| [LangGraph](https://provably.ai/docs/cookbooks/langgraph_multi_agent) | Sequential pipeline with conditional routing | Travel agency | Fetcher → Evaluator → Healer |
+| [CrewAI](https://provably.ai/docs/cookbooks/crewai_multi_agent) | Flow with specialist agents | Invoice auditing | Specialists → Build → Evaluate |
+| [OpenAI Agents SDK](https://provably.ai/docs/cookbooks/openai_agents_multi_agent) | Orchestrator-driven verification | Customer support | Orchestrator → Specialists → Verify |
 
 ## Choosing an Example
 
-- **Single-agent**: Start with `openai_agents` or `langchain_agent` for basic integration
-- **Multi-agent with healing**: Use `langgraph_multi_agent` for automatic error recovery
-- **Multi-agent with specialists**: Use `crewai_multi_agent` or `openai_agents_multi_agent`
+- **Single-agent:** Start with [openai_agents](https://provably.ai/docs/cookbooks/openai_agents) or [langchain_agent](https://provably.ai/docs/cookbooks/langchain_agent) for basic integration.
+- **Multi-agent with healing:** Use [langgraph_multi_agent](https://provably.ai/docs/cookbooks/langgraph_multi_agent) for automatic error recovery.
+- **Multi-agent with specialists:** Use [crewai_multi_agent](https://provably.ai/docs/cookbooks/crewai_multi_agent) or [openai_agents_multi_agent](https://provably.ai/docs/cookbooks/openai_agents_multi_agent).

cookbooks/claude_agent_multi_tool/README.md

@@ -1,5 +1,4 @@
-# Claude Agent SDK — Multi-Tool-Call Demo
-
+# Claude Agent Multi-Tool
 This example demonstrates SourceryKit's multi-tool-call verification with the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python). The agent calls the **same tool** (`get_weather`) twice with different cities (London and Paris). Each call produces a unique `sourcerykit_ref` (the database row UUID). The agent's claims reference the correct ref for each city, and the SDK maps each claim to the right intercept.
 
 ## How It Works
@@ -8,7 +7,7 @@ This example demonstrates SourceryKit's multi-tool-call verification with the [C
 2. **All-Method Trust Gate**: SourceryKit enforces structural target validation checks against your external network endpoints. The external weather lookup endpoint (`api.open-meteo.com`) is explicitly registered via policy seeds (`insert_trusted_endpoint`) before execution.
 3. **Automated Handoff & Evaluation**: The agent groups `claimed_values` by `sourcerykit_ref` and builds one claim per intercept. Each claim's `call_ref` is set to the corresponding `sourcerykit_ref`, so `build_handoff_payload` resolves each claim to the correct intercept row — even when the same `action_name` appears multiple times.
 
-```
+```bash
 Tool: get_weather(London)            Tool: get_weather(Paris)
   intercept_context → ref_1            intercept_context → ref_2
   return {..., sourcerykit_ref: ref_1}  return {..., sourcerykit_ref: ref_2}

cookbooks/crewai_multi_agent/README.md

@@ -1,10 +1,10 @@
-# CrewAI Multi-Agent — Invoice Auditing with Specialist Agents
+# CrewAI Multi-Agent
 
+## Invoice Auditing with Specialist Agents
 This example demonstrates multi-agent orchestration using [CrewAI](https://github.com/crewAIInc/crewAI) with SourceryKit verification. Three specialist agents each query a different ERP table, with centralized evaluation by the orchestrator.
 
 ## Flow
-
-```
+```bash
 Flow[AuditState]:
 
   @start() run_specialists()
@@ -32,28 +32,33 @@ Flow[AuditState]:
 4. **Evaluation**: The orchestrator evaluates each payload via `evaluate_handoff`. This is the verifier side — the orchestrator never touches raw agent output, only the verifiable payloads.
 5. **Conditional Routing**: If any payload fails verification, a remediation crew produces an incident report analyzing the discrepancy.
 
+## Mock Data Tables
+
+| Specialist | Table | Action Name | Agent ID |
+|---|---|---|---|
+| Amount Validator | invoices | `get_invoice_amount` | `amount_validator` |
+| Vendor Checker | vendors | `get_vendor` | `vendor_checker` |
+| Currency Verifier | currencies | `get_currency` | `currency_verifier` |
+
 ---
 
 ## Environment Configuration
+Before running the system, run the interactive setup wizard to configure your SourceryKit project variables automatically:
 
 ```bash
 sourcerykit init
 ```
 
 > [!IMPORTANT]
-> The wizard only configures **SOURCERYKIT_*** variables. LLM provider keys must be set separately.
+> The wizard only configures **SOURCERYKIT_*** variables. It does **not** configure your LLM provider infrastructure keys. You must set your model provider's environment variables (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) separately.
 
 | Variable | Required | Description |
 |---|---|---|
 | `MODEL_NAME` | **yes** | Targeted model engine name (e.g., `openai/gpt-4o-mini`). |
 
-> [!Note]
-> Ensure your underlying model provider's environment variables—such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`—are also set as required by your CrewAI provider setup.
-
 ---
 
 ## Execution
-
 1. Install dependencies:
    ```bash
    pip install sourcerykit crewai-tools python-dotenv httpx pydantic
@@ -63,16 +68,18 @@ sourcerykit init
    pip install "crewai[anthropic]"    # Anthropic
    pip install "crewai[litellm]"      # OpenRouter / multi-provider via LiteLLM
    ```
-2. Export your LLM-provider keys:
+2. Export your LLM-provider keys into your current shell or place them in a local `.env` file:
    ```bash
    export MODEL_NAME="openai/gpt-4o-mini"
    export OPENAI_API_KEY="sk-..."
    ```
-3. Run:
-   ```bash
-   # Standard validation (PASS)
-   python agent_run.py
+3. Run the example:
+      ```bash
+      # Standard Validation
+      python agent_run.py
+
+      # or
 
-   # Hallucination simulation (CAUGHT → Remediation)
-   python agent_run.py --tamper
+      # Hallucination Simulation
+      python agent_run.py --tamper
    ```

cookbooks/langchain_agent/README.md

@@ -1,5 +1,5 @@
 # LangChain Agent
-This example demonstrates how to integrate SourceryKit with LangChain using agent compilation workflows (create_agent). It showcases automated tool intercept capture, target endpoint allow-list constraints, native structured JSON responses via Pydantic, and backend evaluation loops.
+This example demonstrates how to integrate SourceryKit with [LangChain](https://github.com/langchain-ai/langchain) using agent compilation workflows (create_agent). It showcases automated tool intercept capture, target endpoint allow-list constraints, native structured JSON responses via Pydantic, and backend evaluation loops.
 
 ## How It Works
 1. **HTTP Interception**: The `bootstrap_system()` hook dynamically monitors outbound `httpx` calls, ensuring that network operations generated within the LangChain agent tool loop (`get_current_temperature_london`) are securely logged to your database intercepts table.
@@ -16,17 +16,12 @@ sourcerykit init
 ```
 
 > [!IMPORTANT]
-> The wizard only configures **SOURCERYKIT_*** variables. It does **not** configure your LLM provider infrastructure keys (like `MODEL_NAME` or `OPENROUTER_API_KEY`). Those must still be set up separately in your environment.
-
-You will also need to set these LLM-provider variables manually:
+> The wizard only configures **SOURCERYKIT_*** variables. It does **not** configure your LLM provider infrastructure keys. You must set your model provider's environment variables (e.g. `OPENROUTER_API_KEY`) separately.
 
 | Variable | Required | Description |
 |---|---|---|
 | `MODEL_NAME` | **yes** | Targeted model architecture identifier string passed to create_agent (e.g., `openrouter:openai/gpt-4o-mini`). |
 
-> [!Note]
-> Ensure your underlying model provider's environment variables—such as `OPENROUTER_API_KEY`—are also set as required by your LangChain backend provider setup.
-
 ---
 
 ## Execution

cookbooks/langgraph_multi_agent/README.md

@@ -1,10 +1,10 @@
-# LangGraph Multi-Agent — Travel Agency Flight Status
+# LangGraph Multi-Agent
 
+## Travel Agency Flight Status
 This example demonstrates a multi-agent pipeline using [LangGraph](https://github.com/langchain-ai/langgraph) with SourceryKit verification and conditional routing.
 
 ## Flow
-
-```
+```bash
 START → Fetcher Agent → Build Handoff → Evaluator
                                             │
                          ┌──────────────────┤
@@ -41,35 +41,30 @@ sourcerykit init
 ```
 
 > [!IMPORTANT]
-> The wizard only configures **SOURCERYKIT_*** variables. It does **not** configure your LLM provider infrastructure keys (like `MODEL_NAME` or `OPENROUTER_API_KEY`). Those must still be set up separately in your environment.
-
-You will also need to set these LLM-provider variables manually:
+> The wizard only configures **SOURCERYKIT_*** variables. It does **not** configure your LLM provider infrastructure keys. You must set your model provider's environment variables (e.g. `OPENROUTER_API_KEY`) separately.
 
 | Variable | Required | Description |
 |---|---|---|
 | `MODEL_NAME` | **yes** | Targeted model architecture identifier string passed to create_agent (e.g., `openrouter:openai/gpt-4o-mini`). |
 
-> [!Note]
-> Ensure your underlying model provider's environment variables—such as `OPENROUTER_API_KEY`—are also set as required by your LangChain backend provider setup.
-
 ---
 
 ## Execution
-
 1. Install dependencies:
    ```bash
    pip install sourcerykit langchain langgraph python-dotenv httpx pydantic
    ```
-2. Export your LLM-provider keys:
+2. Export your LLM-provider keys into your current shell or place them in a local `.env` file:
    ```bash
    export MODEL_NAME="openrouter:openai/gpt-4o-mini"
-   export OPENROUTER_API_KEY="sk-or-..."
    ```
-3. Run:
-   ```bash
-   # Standard validation (PASS)
-   python agent_run.py
+3. Run the example:
+      ```bash
+      # Standard Validation
+      python agent_run.py
+
+      # or
 
-   # Hallucination simulation (CAUGHT → Healer)
-   python agent_run.py --tamper
+      # Hallucination Simulation
+      python agent_run.py --tamper
    ```

cookbooks/openai_agents/README.md

@@ -23,9 +23,9 @@ You will also need to set these LLM-provider variables manually:
 
 | Variable | Required | Description |
 |---|---|---|
-| `MODEL_URL` | **yes** | Base URL routing endpoint for the LLM processing interface (e.g., `https://openrouter.ai/api/v1`). |
-| `MODEL_API_KEY` | **yes** | API authentication token for the targeting model processing engine. |
-| `MODEL_NAME` | **yes** | Targeted model engine name (e.g., `openai/gpt-4o-mini`). |
+| `MODEL_URL` | **yes** | Base URL for the LLM provider (e.g., `https://openrouter.ai/api/v1`). |
+| `MODEL_API_KEY` | **yes** | API authentication token for the LLM provider. |
+| `MODEL_NAME` | **yes** | Model name (e.g., `openai/gpt-4o-mini`). |
 
 ---