Rewrite in-app documentation

frontend/pages/docs/administration/federation/peer-integration.mdx

@@ -0,0 +1,70 @@
+import DocsWrapper from 'src/docs/DocsWrapper'
+
+# Federation and Peer Integration
+
+> **Common questions this page answers:**
+>
+> - How do I connect Bailo to other instances?
+> - What is federation in Bailo?
+> - What federation states are available?
+
+Federation connects your Bailo instance to other Bailo instances or external model repositories, allowing users to
+discover and mirror models from external sources.
+
+## Federation states
+
+Your Bailo instance can operate in one of three federation states, controlled by the administrator:
+
+- **Disabled** - Federation is turned off. No external sources are visible
+- **Read Only** - Your instance can browse and mirror models from connected peers, but does not share its own models
+- **Enabled** - Full federation: your instance both reads from and shares models with connected peers
+
+The federation state is configured by your administrator in the application configuration.
+
+## Peer types
+
+Bailo supports connecting to different types of external model sources.
+
+- **Bailo** - Another Bailo instance
+- **HuggingFace Hub** - The HuggingFace model repository
+
+Additional sources can be set up by your Bailo administrator.
+
+## Configuring peers
+
+Peers are configured in the application's backend configuration. Each peer requires:
+
+- **Base URL**: The URL of the external Bailo instance or repository
+- **Label**: A display name for the peer (shown in the Marketplace filter)
+- **Kind**: The type of peer (Bailo or HuggingFace Hub)
+- **State**: Whether federation with this peer is disabled, read-only, or enabled
+
+Peer configuration is done through the app configuration file - see
+[App Configuration](/docs/administration/getting-started/app-configuration).
+
+## How federation appears to users
+
+Users see external models alongside local models in the Marketplace, with filtering by external source.
+
+When federation is enabled and peers are configured:
+
+- Users see a **filter by external sources** option in the Marketplace
+- Models from external sources appear alongside local models
+- Each external model shows its source
+- External models can be clicked to view the source
+
+## Checking peer status
+
+Check the reachability of connected peers through the API.
+
+You can check the status of connected peers [via the API](/api/docs//#/system).
+
+Each peer has a reachability status indicating whether Bailo can communicate with it.
+
+## Related pages
+
+- [App Configuration](/docs/administration/getting-started/app-configuration) - Where peers are configured
+- [Creating a Mirrored Model](/docs/users/model-mirroring/creating-a-mirrored-model) - Mirroring external models
+- [Browsing the Marketplace](/docs/users/using-a-model/browsing-the-marketplace) - Filtering by external sources
+
+export default ({ children }) => <DocsWrapper>{children}</DocsWrapper>

frontend/pages/docs/administration/getting-started/app-configuration.mdx

@@ -1,12 +1,23 @@
 import DocsWrapper from 'src/docs/DocsWrapper'
+import Alert from '@mui/material/Alert'
 
 # App Configuration
 
-## Configuration Files
+> **Common questions this page answers:**
+>
+> - How do I configure Bailo?
+> - Where are the configuration files?
+> - How does configuration inheritance work?
 
-> ⚠️ Note: If you use Helm this information does not apply to you. We use Helm to automatically configure the
-> application for you. Within helm you can manually alter this configuration in
-> `infrastructure/helm/bailo/templates/bailo/bailo.configmap.yaml`
+## Configuration files
+
+<Alert sx={{ my: '20px', '& .MuiAlert-message p': { margin: 0 } }} severity='warning'>
+If you use Helm this information does not apply to you.
+
+We use Helm to automatically configure the application for you. Within helm you can manually alter this configuration in
+`infrastructure/helm/bailo/templates/bailo/bailo.configmap.yaml`
+
+</Alert>
 
 Bailo uses [`node-config`](https://github.com/node-config/node-config#readme) for application configuration.
 `node-config` organizes hierarchical configurations, allowing the user to set a series of overrides over a base

frontend/pages/docs/administration/getting-started/deployment-architecture.mdx

@@ -0,0 +1,133 @@
+import DocsWrapper from 'src/docs/DocsWrapper'
+import Alert from '@mui/material/Alert'
+
+# Deployment Architecture
+
+> **Common questions this page answers:**
+>
+> - What services make up Bailo?
+> - How does Bailo's architecture work?
+> - What are the deployment options?
+
+Bailo is composed of several services that work together. Understanding this architecture helps when configuring,
+deploying, and troubleshooting a Bailo instance.
+
+## Core services
+
+Bailo requires six core services to operate.
+
+- **Frontend** (Next.js / Node.js) - Serves the web application UI
+- **Backend** (Node.js) - API (Application Programming Interface) server handling all business logic and data access
+- **NGINX** - Reverse proxy routing requests to frontend, backend, and registry
+- **MongoDB** - Stores all metadata: models, releases, schemas, reviews, users, tokens
+- **Object Storage** (MinIO, S3-compatible) - Stores model files and registry blobs. S3 stands for Simple Storage
+  Service.
+- **Container Registry** (Docker Registry) - Hosts container (Docker) images pushed to models
+
+## Optional services
+
+These services add security scanning, email notifications, and webhook testing capabilities.
+
+- **ArtefactScan** (FastAPI / Python) - Security scanning microservice wrapping ModelScan and Trivy
+- **ClamD** (ClamAV) - Antivirus daemon used to scan uploaded files for malware
+- **Mail Service** (SMTP-compatible) - Sends email notifications for reviews and access requests. SMTP stands for Simple
+  Mail Transfer Protocol.
+- **Webhook** (Webhook Tester) - Development tool for receiving and inspecting webhook requests
+
+## How requests flow
+
+All requests enter through the NGINX reverse proxy and are routed to the appropriate service.
+
+1. Users access Bailo through the **NGINX** reverse proxy (default port 8080)
+2. NGINX routes requests:
+   - UI page requests go to the **Frontend**
+   - API requests (`/api/...`) go to the **Backend**
+   - Container registry requests (`/v2/...`) go to the **Container Registry**
+3. The **Backend** reads and writes metadata to **MongoDB**
+4. File uploads and downloads go through the **Backend** to **Object Storage** (MinIO)
+5. Container image push/pull operations go through the **Container Registry**, which also uses **Object Storage**
+6. When files or images are uploaded, the **Backend** triggers scans via the **ClamD** and **ArtefactScan** service (if
+   configured)
+
+## Deployment options
+
+Bailo can be deployed using Docker Compose for development or Helm for production Kubernetes environments.
+
+### Docker compose (Development & Small Deployments)
+
+The repository includes a `compose.yaml` that runs the core services locally. This is the simplest way to get started.
+There is also ``compose.prod.yaml` to run all services locally. This is also used in the repository's GitHub workflows
+for testing.
+
+### Helm (Production & Kubernetes)
+
+For production deployments, Bailo provides Helm charts for deploying to Kubernetes. See:
+
+- [Helm Basic Usage](/docs/administration/helm/basic-usage)
+- [Helm Configuration](/docs/administration/helm/configuration)
+- [Isolated Environments](/docs/administration/helm/isolated-environments)
+
+### Standalone dockerfile
+
+<Alert sx={{ my: '20px', '& .MuiAlert-message p': { margin: 0 } }} severity='warning'>
+  `Dockerfile.standalone` is intended for local testing and secondary-instance scenarios. It should **not** be used as
+  the recommended production deployment model. Use Helm for production Kubernetes deployments.
+</Alert>
+
+`Dockerfile.standalone` builds a single container that runs a self-contained Bailo instance. It packages the frontend,
+backend, NGINX, MongoDB, MinIO, the container registry, and Mailcrab into one image using `supervisord`.
+
+This is not the normal development path. For day-to-day local development, use `compose.yaml`, because it runs each
+service separately and supports rebuilding, inspecting, and restarting individual services more easily.
+
+Use the standalone Dockerfile when you need an additional Bailo instance alongside your main Docker Compose instance,
+for example:
+
+- Testing cross-instance functionality, such as searching for models in another Bailo instance
+- Running a second local instance without starting another full Compose project
+- Creating a compact demo or smoke-test instance
+- Checking behaviour where one Bailo deployment needs to communicate with another
+
+To use it, first start your main Bailo instance with Docker Compose:
+
+```bash
+docker compose build --parallel
+docker compose up -d
+```
+
+The main instance is then available at `http://localhost:8080`.
+
+Build and run the standalone image from the repository root:
+
+```bash
+docker build . -t second-bailo -f Dockerfile.standalone
+docker run --rm -p 4318:8080 --network dev_internal --name second-bailo second-bailo:latest
+```
+
+The standalone instance is then available at `http://localhost:4318`.
+
+If your Compose instance uses a different `INSTANCE_NAME`, replace `dev_internal` with the matching internal network
+name, for example `<INSTANCE_NAME>_internal`.
+
+## Data storage
+
+Bailo stores structured metadata in MongoDB and binary artefacts in S3-compatible object storage:
+
+- **MongoDB** holds all structured metadata (models, schemas, reviews, tokens, etc.)
+- **Object Storage (MinIO/S3)** holds binary artefacts (model files, container image layers)
+
+Both need to be backed up to prevent data loss.
+
+## Configuration
+
+Bailo uses [node-config](https://github.com/node-config/node-config) for backend configuration. Configuration files can
+be overridden via environment variables or Helm values. See
+[App Configuration](/docs/administration/getting-started/app-configuration) for details.
+
+## Related pages
+
+- [App Configuration](/docs/administration/getting-started/app-configuration) - Configuring the backend
+- [Helm Basic Usage](/docs/administration/helm/basic-usage) - Deploying with Helm
+- [Artefact Scanners](/docs/administration/microservices/artefact-scanners) - Configuring security scanning
+
+export default ({ children }) => <DocsWrapper>{children}</DocsWrapper>

frontend/pages/docs/administration/helm/basic-usage.mdx

@@ -8,6 +8,12 @@ same base templates for deploying Bailo, configuring overrides to values as need
 
 For more details, see the [Helm project page](https://helm.sh/).
 
+> **Common questions this page answers:**
+>
+> - How do I deploy Bailo with Helm?
+> - What are the requirements for a Helm deployment?
+> - How do I upgrade or remove a Helm deployment?
+
 ## Requirements
 
 - [HELM CLI](https://github.com/helm/helm/releases)
@@ -19,6 +25,8 @@ If you are deploying to OpenShift, you will also need OC:
 
 ## Deployment
 
+Deploy Bailo to Kubernetes or OpenShift using standard Helm commands.
+
 ### Setup
 
 All commands assume they are run in the `infrastructure/helm/bailo` directory. You should have already authenticated

frontend/pages/docs/administration/helm/configuration.mdx

@@ -2,6 +2,12 @@ import DocsWrapper from 'src/docs/DocsWrapper'
 
 # Helm Configuration
 
+> **Common questions this page answers:**
+>
+> - How do I configure Helm values for Bailo?
+> - How do I override the default Helm configuration?
+> - What minimum configuration is required?
+
 The default Helm configuration is stored within `values.yaml`. You should not alter this configuration directly, instead
 overriding individual values via the command line `--set` flag, or by providing a custom `--values` file.
 

frontend/pages/docs/administration/helm/isolated-environments.mdx

@@ -5,41 +5,49 @@ import DocsWrapper from 'src/docs/DocsWrapper'
 Bailo is built to be deployed on isolated environments, where access to the internet is strictly regulated. To install
 Bailo on a segregated environment you will need the following dependencies.
 
-## Helm Charts
+> **Common questions this page answers:**
+>
+> - How do I deploy Bailo in an air-gapped environment?
+> - What dependencies does Bailo need for offline deployment?
+> - How do I configure the Trivy database in an isolated environment?
 
-We rely on the following [Bitnami charts](https://charts.bitnami.com/):
+## Helm charts
+
+Bailo's Helm chart depends on [Bitnami charts](https://charts.bitnami.com/):
 
 - MinIO https://charts.bitnami.com/bitnami
 - MongoDB https://charts.bitnami.com/bitnami
 
-## Docker Images
+## Docker images
 
-We rely on the following images:
+These container images must be available in your connected registry:
 
-- mongodb/mongodb-community-server:8.2.2-ubi9
-- bitnami/minio:2025.7.23
-- marlonb/mailcrab:v1.6.2
-- nginxinc/nginx-unprivileged:1.28.0-alpine3.21-slim
-- registry:3.0.0
-- node:24.11.1-alpine
+- mongodb/mongodb-community-server:8.x-ubi9
+- bitnamilegacy/minio:2025.x
+- marlonb/mailcrab:v1.x
+- nginxinc/nginx-unprivileged:1.x-alpine3.x-slim
+- registry:3.x
+- node:24.x-alpine
 
 These are regularly updated. To retrieve the latest versions used, check `./compose.yaml` and `./backend/Dockerfile`.
 These versions can be configured using the `tag` attribute for each image in `values.yaml` to override the defaults. In
 general, keeping to the same major version will maintain compatibility with Bailo.
 
 ## NPM
 
-We rely on many NPM packages. The full list is available in `package-lock.json`, `frontend/package-lock.json` and
-`backend/package-lock.json`. Most are standard packages with the exception of:
+Bailo relies on many NPM (Node Package Manager) packages. The full list is available in `package-lock.json`,
+`frontend/package-lock.json` and `backend/package-lock.json`. Most are standard packages with the exception of:
 
-- `sharp`, which is an optimised image transformer and requires some compilation tools.
-- `cypress`, which is a user interface testing tool and requires a Chromium download.
+- `sharp`, which is an optimised image transformer and requires some compilation tools
+- `cypress`, which is a user interface testing tool and requires a Chromium download
 
 `sharp` includes instructions on installing / building without internet [here](https://sharp.pixelplumbing.com/install).
 Instructions on installing `cypress` without internet are available
 [here](https://docs.cypress.io/guides/references/advanced-installation).
 
-## Trivy Database
+## Trivy database
+
+In isolated environments, Trivy may need custom configuration to access its vulnerability database.
 
 To give greater visibility of Bailo's registry and it's containing images, some environments may use Trivy to scan for
 threats, packages and more.
@@ -53,7 +61,8 @@ There are a number of environment variables that can be configured to customise
 - `TRIVY_DB_HOSTNAME=ghcr.io` - Host to retrieve the database from
 - `TRIVY_DB_IMAGE=ghcr.io/aquasecurity/trivy-db:2` - Image to retrieve the database from
 
-- `TRIVY_DB_TLS_VERIFY=True` - Enable or disable TLS verification or use a path to point to a custom certificate
+- `TRIVY_DB_TLS_VERIFY=True` - Enable or disable TLS (Transport Layer Security) verification or use a path to point to a
+  custom certificate
 - `TRIVY_DB_INSECURE=False` - Enable if database host is not using TLS or has a custom certificate implementation
 
 - `TRIVY_DB_USERNAME` - Registry login username

frontend/pages/docs/administration/microservices/artefact-scanners.mdx

@@ -2,6 +2,12 @@ import DocsWrapper from 'src/docs/DocsWrapper'
 
 # Artefact Scanners
 
+> **Common questions this page answers:**
+>
+> - What scanners does Bailo use?
+> - How do I configure artefact scanning?
+> - What is the ArtefactScan service?
+
 Within Bailo, it is possible to optionally deploy artefact scanners which are designed to help manage any potential risk
 of artefacts being uploaded with potentially malicious contents.
 
@@ -11,12 +17,12 @@ The scanners currently supported by Bailo are:
 - [ArtefactScan](https://github.com/gchq/Bailo/tree/main/lib/artefactscan_api) - Bailo scanning service that
   orchestrates multiple scanners
   - [ModelScan](https://github.com/protectai/modelscan) - malicious or unsafe content detection in model artefacts
-  - [Trivy](https://github.com/aquasecurity/trivy) - vulnerability scanning and SBOM generation for container image
-    layers
+  - [Trivy](https://github.com/aquasecurity/trivy) - vulnerability scanning and SBOM (Software Bill of Materials)
+    generation for container image layers
 
 ## ClamAV
 
-ClamAV is used for traditional malware detection on uploaded files.
+ClamAV provides traditional antivirus malware detection for uploaded files.
 
 - Uses the official [ClamAV Docker image](https://hub.docker.com/r/clamav/clamav)
 - Integrated via a
@@ -62,16 +68,18 @@ Trivy is used to analyse container image layers for known vulnerabilities and to
 - Scans uploaded image layer tarballs (overlay filesystems)
 - Uses a locally cached Trivy vulnerability database
 
-> Trivy is an open‑source vulnerability scanner from Aqua Security for containers and other artefacts.
+> Trivy is an open-source vulnerability scanner from Aqua Security for containers and other artefacts.
+
+## Minimal configuration
 
-## Minimal Configuration
+Configure scanner settings in the backend application configuration. These settings will apply to all scanners.
 
-| Name                                              | Description                                           | Value  |
-| ------------------------------------------------- | ----------------------------------------------------- | ------ |
-| `connectors.artefactScanners.kinds`               | List of enabled artefact scanner kinds                | `[]`   |
-| `connectors.artefactScanners.retryDelayInMinutes` | Minutes between repeated scans of the same artefact   | `60`   |
-| `connectors.artefactScanners.maxInitRetries`      | Number of startup connection attempts before failing  | `5`    |
-| `connectors.artefactScanners.initRetryDelay`      | Delay between successive startup pings (milliseconds) | `5000` |
+- **connectors.artefactScanners.kinds** - List of enabled artefact scanner kinds. Default: `[]`
+- **connectors.artefactScanners.retryDelayInMinutes** - Minutes between repeated scans of the same artefact. Default:
+  `60`.
+- **connectors.artefactScanners.maxInitRetries** - Number of startup connection attempts before failing. Default: `5`
+- **connectors.artefactScanners.initRetryDelay** - Delay between successive startup pings (milliseconds). Default:
+  `5000`.
 
 Enabling or disabling specific scanners is handled via connector configuration and deployed microservices.