docs: add AI comparison docs

website/docs/docs/ai/using.md

@@ -414,4 +414,44 @@ In AI, context is key. The more relevant information you can provide the more ta
 
 ### 3. Use Test Templates
 
-Test Templates reduce the amount of refactoring required after generation. If you start to see a common generation pattern you wish to avoid, update the Test Template to help PactFlow AI generate improved output.
+Test Templates reduce the amount of refactoring required after generation. If you start to see a common generation pattern you wish to avoid, update the Test Template to help PactFlow AI generate improved output.
+
+## Comparing PactFlow AI with Other AI Tools
+
+PactFlow AI is purpose-built for contract testing workflows. While general-purpose AI tools like ChatGPT, GitHub Copilot, and IDE-native assistants (e.g., Windsurf) offer broad utility, they are not optimized for *specific* domains and use cases like contract testing with Pact.
+
+The table below outlines key differences between these tools to help you understand how PactFlow AI can be incorporated into your development process.
+
+### Feature Comparison
+
+| Feature | **PactFlow AI** | **ChatGPT / Claude** | **GitHub Copilot** | **IDE-native AI (e.g., Windsurf)** |
+|--------|------------------|----------------------|--------------------|-------------------------------|
+| **Primary Use Case** | Contract test generation, review, and maintenance | General knowledge, Q&A, prototyping | Inline code suggestions | IDE-embedded assistant for development tasks |
+| **Breadth of Application** | Focused on Pact | Wide range of dev and non-dev tasks | General-purpose coding | Full-stack code, terminal, file editing |
+| **Strength in General Coding** |	❌ Not built for general-purpose coding |	✅ Excellent at most languages and use cases |	✅ Great for scaffolding and boilerplate	| ✅ Helps with app logic, CLI, tests, refactors |
+| **Integration Surface** |	CLI (now), IDE via MCP (coming), UI (planned) |	Chat/web/app with integrations | Deep IDE integration (VS Code, JetBrains), Web/UI |	Native to Cursor, Cline, etc. |
+| **Contract Testing Support** | ✅ Pact-specific knowledge, updated DSLs, test structure and matcher guidance | ❌ Generic or outdated knowledge | ❌ May suggest invalid or old Pact patterns | ❌ No contract testing awareness |
+| **Contract Testing Maintenance** | ✅ Review, update, and fix existing Pact tests | ❌ Prompt-based only | ❌ Suggests code, not test upkeep | ❌ Not designed for test maintenance |
+| **TDD Alignment** | ✅ Encourages scoped, purposeful test creation | ❌ May reinforce ad hoc development | ✅ Scaffolds tests, but not goal-oriented | ⚠️ Speed-optimized, not test-structured |
+| **Human-in-the-loop Design** | ✅ AI suggestions are reviewable and optional | ⚠️ User must prompt and validate output | ✅ Autocomplete with human review | ⚠️ High-speed, low-friction suggestions |
+| **Governance & Control** | ✅ RBAC-aware, CLI and platform-controlled | ⚠️ Black-box models, limited traceability | ⚠️ Limited observability | ⚠️ Tool-dependent privacy and trust model |
+
+### When to Use Each Tool
+
+| Use Case | Recommended Tool |
+|----------|------------------|
+| Creating and maintaining Pact tests | **PactFlow AI** |
+| Prototyping or researching APIs, code patterns | **ChatGPT / Claude** |
+| Writing app logic, scaffolding components or full-stack development in IDE | **GitHub Copilot**, **IDE-native AI tools** |
+
+### Summary
+
+PactFlow AI is not designed to replace general-purpose AI tools. Instead, it complements them by offering deep, current knowledge of contract testing—particularly Pact.
+
+While other tools can help with coding in general, they do not provide guidance on:
+- Pact test quality
+- Over-specification and drift detection
+- DSL correctness and best practices
+- And other contract-testing specific capabilities
+
+For teams working with Pact, PactFlow AI acts as a domain expert—reviewing, generating, and maintaining tests with precision and context.

website/docs/docs/on-premises-2x.md

@@ -0,0 +1,57 @@
+---
+title: PactFlow On-Premises Architecture
+sidebar_label: Architecture
+---
+
+## System architecture
+
+### Minimum requirements
+
+* An application server capable of running Docker
+* PostgreSQL database
+* Redis cache
+* SAML IDP for SSO
+* PactFlow license file
+
+### Recommended architecture
+
+* Deploy to a service designed for Docker container orchestration (ECS, Fargate, Kubernetes etc.)
+
+### Example AWS deployment using ECS
+
+![System architecture](/img/saas-architecture-2x.png)
+
+## Internal architecture
+
+The PactFlow On-Premises application is distributed as a Docker image. It is based on the open source [Pact Broker](https://github.com/pact-foundation/pact_broker), which is a Ruby application.
+
+### Application user requirements
+
+The PactFlow application does not need any elevated privileges to run. It runs under the user `app`.
+
+### Application port
+
+The PactFlow application runs on port `9292` by default. This can be configured by setting the [PACTFLOW_HTTP_PORT](/docs/on-premises/environment-variables#pactflow_http_port) environment variable.
+
+### Healthcheck endpoint
+
+A healthcheck endpoint for use by a Docker container managment service is available at `http://<HOST>/diagnostic/status/heartbeat`. No authentication is required. This endpoint does not make a connection to the database. You can use this check to confirm your load balancer targets are healthy.
+
+If the healthcheck is running from inside the container, make sure to use the port defined in the environment variable `$PACTFLOW_HTTP_PORT`, which defaults to `9292`. You can use `supervisorctl` to perform the healthcheck request.
+
+An example healthcheck configuration for Docker Compose:
+
+```yaml
+healthcheck:
+  test: ["supervisorctl", "status", "haproxy", "marko", "pactflow"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+```
+
+To check the connection to the database, use the endpoint `/diagnostic/status/dependencies`. This endpoint should not be used by Docker container managment services, as unrelated database issues might cause the Docker container to churn.
+
+### License file
+
+PactFlow on-premises version requires a license file to run. [Contact us](https://support.smartbear.com/pactflow/message/) if you have not
+received one when your account was setup. See the [section on licenses for installation instructions](/docs/on-premises/license).

website/docs/docs/on-premises-2x/authentication.md

@@ -0,0 +1,16 @@
+---
+title: Authentication
+---
+
+## User interface
+
+The PactFlow On-Premises application currently supports single sign for SAML identity providers. It supports both IDP and SP initiated log in.
+
+Any user who is able to authenticate to the configured IDP is allowed access to PactFlow.
+
+The SAML IDP is configured via [environment variables](environment-variables#saml-authentication).
+
+## API
+
+The API is accessed using a bearer token that is set in the HTTP header of the request (eg. `Authorization: Bearer <your token here>`). The tokens are administered on a per user basis in the [settings page](/docs/user-interface/settings/api-tokens) of the PactFlow application.
+

website/docs/docs/on-premises-2x/authentication/demo.md

@@ -0,0 +1,29 @@
+---
+title: Demo Auth
+---
+
+To allow experimentation with PactFlow without the need to configure an external identity provider, the "demo" authentication provider can be enabled. With demo auth enabled, any user can log in to PactFlow by providing a name and email address. No password is used to authenticate the user.
+
+The first user to log in will be assigned the [Administrator](/docs/permissions/predefined-roles#administrator) role, and every user thereafter will receive the default ([User](/docs/permissions/predefined-roles#user)) role.
+
+After a user has logged in, they may perform all the actions their role allows, as if they were a user created via a real identify provider.
+
+:::caution
+
+This method of authentication is NOT secure and should not be used in production.
+
+:::
+
+Demo auth replaces the basic auth capability that was previously used for this purpose.
+
+## Configuration
+
+See the [Demo](/docs/on-premises-2x/environment-variables#demo_auth_enabled) section of the environment variables page. Demo auth cannot be enabled at the same time as any other method of authentication (ie. SAML).
+
+## Converting to a production IDP
+
+Demo authentication cannot be enabled at the same time as a real authentication provider (eg. SAML). We recommend starting with a clean database when installing PactFlow for production use. This will ensure no demo users remain in the system.
+
+## Docker Compose example
+
+This [Docker Compose example](/docs/on-premises-2x/docker-compose-example) is configured using Demo Auth.

website/docs/docs/on-premises-2x/authentication/oauth2.md

@@ -0,0 +1,48 @@
+---
+title: OAuth2
+---
+
+## Configuration
+
+An OAuth2 identify provider is configured by a set of environment variables prefixed with `PACTFLOW_TEST_OAUTH2_`, or using the `test_oauth2` key in a YAML configuration file. See the [Test OAuth2](/docs/on-premises-2x/environment-variables/1.14-beta) section of the environment variables page for the full list.
+
+## Callback URL
+
+The callback URL is `https://<your PactFlow host>/auth/oauth2/callback`. This must be configured in the settings for the PactFlow client in your Identify Provider.
+
+## Authorize params
+
+The following parameters are sent to the Identity Provider's configured [`authorize_url`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__authorize_url) during the request phase.
+
+| Parameter | Description |
+|-----------|-------------|
+| scope | `openid profile email` |
+| response_type | `code` |
+| response_mode | `form_post` |
+| state | A randomly generated hex string |
+| client_id  | The configured [client_id](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_id) |
+| redirect_uri |  The [callback URL](#callback-url) as documented above |
+
+The parameters configured in the [`custom_authorize_params`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__custom_authorize_params__key) are also merged into these default parameters.
+
+## Token params
+
+The following parameters are sent to the Identity Provider's configured [`token_url`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__token_url).
+
+| Parameter | Description |
+|-----------|-------------|
+| code | The `code` returned by the IDP during the callback phase. |
+| grant_type | `authorization_code` |
+| client_id  | The configured [client_id](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_id) |
+| client_secret | The configured [client_secret](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_secret) |
+| redirect_uri |  The [callback URL](#callback-url) as documented above |
+
+The parameters configured in the [`custom_token_params`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__custom_token_params__key) are also merged into these default parameters.
+
+## Custom Auth handler
+
+At the end of the OAuth2 login flow, a JWT is retrieved by PactFlow from the customer's Identify Provider. A custom Ruby auth handler configuration file will be supplied by PactFlow to map claims from the JWT to PactFlow roles and teams. The auth handler configuration file must be mounted as a volume on the PactFlow container, in the directory `/home/pactflow/extensions/` eg. `/home/pactflow/extensions/auth_ext_script.rb`.
+
+## Debugging
+
+The URLs and headers of the HTTP interactions with the Identity Provider will be logged at `info` level in the PactFlow logs. To see the request and response bodies, set the `PACTFLOW_LOG_LEVEL` to `debug`. Note that this will log sensitive information, so do not leave the logging at this level permanently.

website/docs/docs/on-premises-2x/authentication/saml.md

@@ -0,0 +1,128 @@
+---
+title: SAML
+---
+
+PactFlow supports single sign on using the SAML authentication protocol.
+
+Once SAML has been configured, if the database contains no users, the first user to log in will be assigned the [Administrator](/docs/permissions/predefined-roles#administrator) role, and every user thereafter will receive the default ([User](/docs/permissions/predefined-roles#user)) role.
+
+## Configuration
+
+A SAML provider is configured by a set of environment variables prefixed with `PACTFLOW_SAML_`. See the [SAML](/docs/on-premises-2x/environment-variables#saml-authentication) section of the environment variables page for the full list.
+
+## Assertion Consumer URL
+
+This is the endpoint to which the IDP will post the SAML assertion after the user is authenticated. It is also called the "sign on URL", "reply URL", and "callback URL", depending on your IDP. You will need to configure this value in your IDP when you set up the PactFlow service provider.
+
+The URL is `https://<your PactFlow host>/auth/saml/callback`.
+
+## Metadata URL
+
+The PactFlow SAML service provider metadata URL is available at `https://<your PactFlow host>/auth/saml/metadata`.
+
+## Configuring multiple SAML providers
+
+In PactFlow 1.7.0 and later, multiple SAML providers may be configured. To configure a second SAML provider, create another set of the [SAML environment variables](/docs/on-premises-2x/environment-variables#saml-authentication) with the prefix `PACTFLOW_SAML_2_` (and `PACTFLOW_SAML_3_` for the third, etc). The `PACTFLOW_SAML_ISSUER` does not need to be specified again, as it is shared between all SAML providers.
+
+The callback path for the second provider is `/auth/saml/2/callback`, and for the third `/auth/saml/3/callback` etc. The path for the metadata for subsequent SAML providers will be `/auth/saml/2/metadata`, `/auth/saml/3/metadata` etc.
+
+## Configuring Azure Active Directory
+
+### Create a non gallery application
+
+* Follow the [Microsoft documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-non-gallery-app) for creating a non gallery application.
+  * Choose `Non-gallery application` at the `Add your own app` screen.
+  * Set the name to `PactFlow On-Premesis` when prompted.
+
+* When the application has been created, assign the users that should be allowed to login to PactFlow.
+
+* Once the users have been assigned, select the `Single sign-on` tab. Select `SAML`.
+
+* Set the Identifier (Entity ID) to `https://pactflow.<your company domain>` eg. `https://pactflow.mycompany.com`. This field must match the [PACTFLOW_SAML_ISSUER]../(environment-variables#pactflow_saml_issuer) environment variable.
+
+* Set the Reply URL to `https://<your PactFlow host>/auth/saml/callback`
+
+* Leave the Sign On URL, Relay State and Logout Url fields blank.
+
+### Configure the PactFlow environment variables
+
+You can find a template for the required environment variables [here](/docs/on-premises-2x/environment-variables/templates#azure-active-directory).
+
+* Set the [PACTFLOW_SAML_ISSUER](/docs/on-premises-2x/environment-variables#pactflow_saml_issuer) to the `Identifier (Entity ID)`.
+* Set the [PACTFLOW_SAML_IDP_SSO_TARGET_URL](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_sso_target_url) to the `Login URL`.
+* Set the [PACTFLOW_SAML_IDP_ENTITY_ID](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_entity_id) to the `Azure AD Identifier`
+* Set the [PACTFLOW_SAML_IDP_CERT_FINGERPRINT](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_cert_fingerprint) to the `Thumbprint`
+* Set the [PACTFLOW_SAML_IDP_NAME](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_name) to your choice - this is a display name for the login button.
+* Set the identifier, email and name attributes as per the [template](/docs/on-premises-2x/environment-variables#/templates#azure-active-directory).
+
+
+## Docker Compose Example
+
+Follow [steps 1 and 2](/docs/on-premises-2x/docker-compose-example) from the Docker Compose example that uses Demo Auth, then use the following `docker-compose.yml` file to run your services.
+
+```
+version: "3"
+
+services:
+  simplesaml:
+    image: kristophjunge/test-saml-idp
+    logging:
+      driver: none # comment out the logging config to see the SAML server logs
+    ports:
+      - "8080:8080"
+      - "8443:8443"
+    environment:
+     - SIMPLESAMLPHP_SP_ENTITY_ID=https://pactflow.io
+     - SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE=http://localhost/auth/saml/callback
+
+  pactflow:
+    image: quay.io/pactflow/enterprise
+    depends_on:
+      - postgres
+    environment:
+      - PACTFLOW_HTTP_PORT=9292
+      - PACTFLOW_BASE_URL=http://localhost
+      - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres
+      # insecure settings only for the purposes of this demo! Not to be used in production.
+      - PACTFLOW_DATABASE_SSLMODE=disable
+      - PACTFLOW_REQUIRE_HTTPS=false
+      - PACTFLOW_LOG_FORMAT=short # normally this would be set to json, use short for demo only
+      - PACTFLOW_ADMIN_API_KEY=admin
+      - PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY=thisissomerandombytes
+      - PACTFLOW_SAML_AUTH_ENABLED=true
+      - PACTFLOW_SAML_IDP_NAME=Simple SAML
+      - PACTFLOW_SAML_IDP_SSO_TARGET_URL=http://localhost:8080/simplesaml/saml2/idp/SSOService.php
+      - PACTFLOW_SAML_IDP_CERT_FINGERPRINT=11:9B:9E:02:79:59:CD:B7:C6:62:CF:D0:75:D9:E2:EF:38:4E:44:5F
+      - PACTFLOW_SAML_IDP_ID_ATTRIBUTE=uid
+      - PACTFLOW_SAML_EMAIL_ATTRIBUTE=email
+      - PACTFLOW_COOKIE_SECRET=at-least-64-char-secret---------at-least-64-char-secret---------
+      - PACT_BROKER_ADMIN_API_KEY=admin
+      - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/
+    ports:
+      - "80:9292"
+    healthcheck:
+      test: ["CMD", "wget", "-nv", "-t1", "--spider", "http://localhost:9292/diagnostic/status/heartbeat"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    entrypoint: dockerize
+    command: -wait tcp://postgres:5432 docker-entrypoint
+    volumes:
+      - ./pactflow-onprem.lic:/home/pactflow-onprem.lic
+
+  postgres:
+    image: postgres:13-alpine
+    healthcheck:
+      test: psql postgres --command "select 1" -U postgres
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres-volume:/var/lib/postgresql/data
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: postgres
+
+volumes:
+  postgres-volume:
+```