diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..ab065aa
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,25 @@
+{
+  "name": "Veraison Docs Development",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers/features/go:1": {
+      "version": "1.21"
+    },
+    "ghcr.io/devcontainers/features/python:1": {
+      "version": "3.10"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "golang.go",
+        "timonwong.shellcheck",
+        "redhat.vscode-yaml"
+      ]
+    }
+  },
+  "postCreateCommand": "sudo apt-get update && sudo apt-get install -y protobuf-compiler shellcheck curl make && chmod +x scripts/*.sh",
+  "remoteUser": "vscode"
+}
diff --git a/.github/workflows/ci-validate.yml b/.github/workflows/ci-validate.yml
new file mode 100644
index 0000000..9ec6fd4
--- /dev/null
+++ b/.github/workflows/ci-validate.yml
@@ -0,0 +1,27 @@
+name: CI - Docs validation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python (for some tools if needed)
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck protobuf-compiler
+          # Note: docker and docker-compose are pre-installed on GitHub Actions runners
+          # Our validation scripts check for their presence but don't require them to run
+      - name: Run validation
+        run: |
+          make validate
+          make shellcheck
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..52bf18c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,152 @@
+# Contributing to Veraison Documentation
+
+Thank you for your interest in contributing to the Veraison docs. This file gives a
+lightweight, focused workflow that helps maintainers review contributions quickly and
+ensures a consistent developer experience.
+
+## Getting Started
+
+### Prerequisites
+
+1. Validate your environment:
+   ```bash
+   make validate
+   ```
+
+2. Install missing dependencies:
+   ```bash
+   ./scripts/setup.sh
+   ```
+
+3. (Optional) Use VS Code devcontainer for a pre-configured environment
+
+### Development Workflow
+
+1. **Fork and Branch**
+   - Fork the repository
+   - Create a branch named `docs/issue-<number>-<short-desc>`
+   - Example: `docs/issue-68-onboarding-scripts`
+
+2. **Make Changes**
+   - Make small, focused commits (one logical change per commit)
+   - Update or add documentation under appropriate folders:
+     - `api/` - API specifications
+     - `demo/` - Demo walkthroughs
+     - `architecture/` - Architecture documentation
+     - `scripts/` - Automation scripts
+
+3. **Validate Changes**
+   - Run validation: `make validate`
+   - Run linting: `make shellcheck` (if modifying scripts)
+   - Test demos: `make demo-psa` or `make demo-cca`
+   - Run health checks: `make health-check`
+
+4. **Test Documentation**
+   - Verify all commands work as documented
+   - Test on your platform (Ubuntu/macOS/Windows WSL)
+   - Check links and formatting
+
+5. **Submit PR**
+   - Push your branch
+   - Open a Pull Request against `main`
+   - Include issue number in title: `docs: improve setup automation (issue #68)`
+   - Fill out the PR checklist
+
+## Pull Request Checklist
+
+Before submitting your PR, ensure:
+
+- [ ] I followed the contributing guidelines in this file
+- [ ] I ran `make validate` and fixed any issues
+- [ ] I ran `make shellcheck` (if scripts were modified)
+- [ ] I tested the changes on my platform
+- [ ] The changes are described clearly in the PR description
+- [ ] I updated relevant documentation (README, TROUBLESHOOTING, etc.)
+- [ ] If adding examples, I verified they work correctly
+- [ ] I checked for broken links and formatting issues
+
+## Development Environment
+
+### Using Makefile
+
+```bash
+make help          # Show all available targets
+make validate      # Validate environment
+make shellcheck    # Lint shell scripts
+make demo-psa      # Start PSA demo
+make demo-cca      # Start CCA demo
+make health-check  # Check service health
+make clean         # Stop all services
+```
+
+### Using Devcontainer
+
+1. Install VS Code and the "Dev Containers" extension
+2. Open this repository in VS Code
+3. Press Ctrl+Shift+P and select "Dev Containers: Reopen in Container"
+4. The environment will be automatically configured
+
+### Manual Setup
+
+Follow the Quick Start section in [README.md](README.md).
+
+## Contribution Guidelines
+
+### Documentation Style
+
+- Use clear, concise language
+- Include code examples where helpful
+- Provide platform-specific instructions when needed
+- Link to related documentation
+- Keep formatting consistent
+
+### Script Guidelines
+
+- Use bash/POSIX shell
+- Include usage/help text
+- Handle errors gracefully
+- Be non-destructive (prompt before changes)
+- Test on multiple platforms if possible
+
+### Commit Messages
+
+Follow conventional commit format:
+
+```
+type: brief description (issue #N)
+
+Longer explanation if needed
+```
+
+Types: `docs`, `feat`, `fix`, `chore`, `test`, `refactor`
+
+Examples:
+- `docs: add troubleshooting guide (issue #68)`
+- `feat: add health check script (issue #68)`
+- `fix: correct docker-compose syntax in PSA demo`
+
+### Testing
+
+- Test all commands and examples
+- Verify cross-platform compatibility when possible
+- Check that demos start successfully
+- Run health checks on services
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common problems
+2. Review [docs/ERROR_HANDLING.md](docs/ERROR_HANDLING.md) for error scenarios
+3. Ask on [Veraison Zulip](https://veraison.zulipchat.com)
+4. Open an issue with detailed information
+
+## Code of Conduct
+
+Be respectful and constructive. We're all here to improve Veraison together.
+
+## Questions?
+
+- Zulip: https://veraison.zulipchat.com
+- Issues: https://github.com/veraison/docs/issues
+- Discussions: https://github.com/veraison/docs/discussions
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..fc62c7c
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,50 @@
+SHELL := /bin/bash
+.PHONY: help validate shellcheck quick-start demo-psa demo-cca health-check clean
+
+help:
+	@echo "Veraison Documentation - Available targets:"
+	@echo "  make validate      - Run environment validation checks"
+	@echo "  make shellcheck    - Run shellcheck on all scripts"
+	@echo "  make quick-start   - Run quick-start verification"
+	@echo "  make demo-psa      - Start PSA demo services"
+	@echo "  make demo-cca      - Start CCA demo services"
+	@echo "  make health-check  - Check health of running services"
+	@echo "  make clean         - Stop all demo services"
+	@echo ""
+	@echo "For troubleshooting, see TROUBLESHOOTING.md"
+
+validate:
+	@echo "Running project validation..."
+	@./scripts/validate-setup.sh
+
+shellcheck:
+	@echo "Running shellcheck on scripts..."
+	@command -v shellcheck >/dev/null 2>&1 || { echo "shellcheck not found, install it for better validation"; exit 0; }
+	@shellcheck scripts/*.sh || true
+
+quick-start:
+	@echo "Quick start (delegates to scripts/quick-start.sh)"
+	@./scripts/quick-start.sh
+
+demo-psa:
+	@echo "Starting PSA demo services..."
+	@cd demo/psa && docker compose up -d
+	@echo "Services started. Check status with: cd demo/psa && docker compose ps"
+
+demo-cca:
+	@echo "Starting CCA demo services..."
+	@cd demo/cca && docker compose up -d
+	@echo "Services started. Check status with: cd demo/cca && docker compose ps"
+
+health-check:
+	@echo "Checking service health..."
+	@./scripts/healthcheck.sh http://localhost:8080/ || echo "PSA verifier not responding"
+	@./scripts/healthcheck.sh http://localhost:8888/ || echo "PSA provisioning not responding"
+	@./scripts/healthcheck.sh http://localhost:8081/ || echo "CCA verifier not responding"
+	@./scripts/healthcheck.sh http://localhost:8889/ || echo "CCA provisioning not responding"
+
+clean:
+	@echo "Stopping all demo services..."
+	@cd demo/psa && docker compose down 2>/dev/null || true
+	@cd demo/cca && docker compose down 2>/dev/null || true
+	@echo "Services stopped."
diff --git a/README.md b/README.md
index 11eca4e..36e278e 100644
--- a/README.md
+++ b/README.md
@@ -25,3 +25,67 @@
 * [DICE notes](musings/dice.md)
 * [Device and Supply-Chain Modelling](musings/device-and-supply-chain-modelling.md)
 * [Assumptions about Attestation Evidence](musings/token-assumptions.md)
+```
+
+## Quick Start
+
+This repository includes comprehensive tooling to improve the developer onboarding experience.
+See `CONTRIBUTING.md` for the full workflow.
+
+### 1. Validate Your Environment
+
+```sh
+make validate
+# or
+scripts/validate-setup.sh
+```
+
+### 2. Install Missing Dependencies
+
+```sh
+scripts/setup.sh
+```
+
+### 3. Run Quick Start
+
+```sh
+make quick-start
+# or
+scripts/quick-start.sh
+```
+
+### 4. Start Demo Services
+
+```sh
+# PSA demo
+make demo-psa
+
+# CCA demo
+make demo-cca
+
+# Check health
+make health-check
+```
+
+### 5. Using VS Code?
+
+Open this repository in a devcontainer for a pre-configured development environment:
+- Install the "Dev Containers" extension
+- Open Command Palette (Ctrl+Shift+P)
+- Select "Dev Containers: Reopen in Container"
+
+### Available Make Targets
+
+Run `make help` to see all available commands.
+
+### Troubleshooting
+
+If you encounter issues, see:
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Platform-specific solutions
+- [docs/ERROR_HANDLING.md](docs/ERROR_HANDLING.md) - Common error scenarios
+
+### Demo-Specific Instructions
+
+For detailed demo walkthroughs:
+- PSA: [demo/psa/](demo/psa/)
+- CCA: [demo/cca/](demo/cca/)
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 0000000..04a99b4
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,244 @@
+# Troubleshooting Guide
+
+This guide covers common issues and platform-specific solutions for working with Veraison documentation.
+
+## Table of Contents
+
+- [Setup Issues](#setup-issues)
+- [Docker Issues](#docker-issues)
+- [Platform-Specific Issues](#platform-specific-issues)
+- [Demo Issues](#demo-issues)
+- [Build and Validation Issues](#build-and-validation-issues)
+
+## Setup Issues
+
+### Missing Dependencies
+
+**Problem**: `scripts/validate-setup.sh` reports missing tools.
+
+**Solution**:
+```bash
+# Run the guided setup
+./scripts/setup.sh
+
+# Or install manually:
+# Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install -y docker.io docker-compose-plugin protobuf-compiler shellcheck
+
+# macOS (using Homebrew)
+brew install docker docker-compose protobuf shellcheck
+
+# Verify installation
+./scripts/validate-setup.sh
+```
+
+### protoc Not Found
+
+**Problem**: `protoc: command not found`
+
+**Solution**:
+- **Ubuntu/Debian**: `sudo apt-get install -y protobuf-compiler`
+- **macOS**: `brew install protobuf`
+- **Manual**: Download from https://github.com/protocolbuffers/protobuf/releases
+
+### shellcheck Not Found
+
+**Problem**: `shellcheck: command not found`
+
+**Solution**:
+- **Ubuntu/Debian**: `sudo apt-get install -y shellcheck`
+- **macOS**: `brew install shellcheck`
+- **Windows (WSL)**: `sudo apt-get install -y shellcheck`
+
+## Docker Issues
+
+### Docker Permission Denied
+
+**Problem**: `Got permission denied while trying to connect to the Docker daemon socket`
+
+**Solution**:
+```bash
+# Add your user to the docker group
+sudo usermod -aG docker $USER
+
+# Log out and log back in, or run:
+newgrp docker
+
+# Verify
+docker ps
+```
+
+### Docker Compose Version Issues
+
+**Problem**: `docker-compose: command not found` or version conflicts
+
+**Solution**:
+```bash
+# Modern Docker includes compose as a plugin
+docker compose version
+
+# If using standalone docker-compose v1:
+python3 -m pip install --user docker-compose
+
+# Or install the plugin:
+sudo apt-get install -y docker-compose-plugin
+```
+
+### Port Already in Use
+
+**Problem**: `Bind for 0.0.0.0:8080 failed: port is already allocated`
+
+**Solution**:
+```bash
+# Find and stop the conflicting process
+sudo lsof -i :8080
+sudo kill <PID>
+
+# Or change the port in docker-compose.yml
+```
+
+## Platform-Specific Issues
+
+### Ubuntu/Debian
+
+**Issue**: Older package versions
+
+**Solution**:
+```bash
+# Add Docker's official repository for latest versions
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+sudo apt-get update
+sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+```
+
+### macOS
+
+**Issue**: Docker Desktop required
+
+**Solution**:
+- Install Docker Desktop from https://www.docker.com/products/docker-desktop
+- Or use alternatives like OrbStack or Colima
+
+**Issue**: Slow file I/O with Docker volumes
+
+**Solution**:
+- Use Docker Desktop's VirtioFS for better performance
+- Consider using named volumes instead of bind mounts
+
+### Windows (WSL2)
+
+**Issue**: WSL2 integration not working
+
+**Solution**:
+1. Ensure WSL2 is installed: `wsl --install`
+2. Enable WSL2 integration in Docker Desktop settings
+3. Restart Docker Desktop
+
+**Issue**: Line ending issues
+
+**Solution**:
+```bash
+# Configure git to handle line endings
+git config --global core.autocrlf input
+```
+
+## Demo Issues
+
+### PSA Demo Fails to Start
+
+**Problem**: Services fail to start or exit immediately
+
+**Solution**:
+```bash
+# Check logs
+cd demo/psa
+docker compose logs
+
+# Rebuild containers
+docker compose down
+docker compose build --no-cache
+docker compose up
+```
+
+### CCA Demo Missing Files
+
+**Problem**: Required data files or keys are missing
+
+**Solution**:
+```bash
+# Ensure you're in the correct directory
+cd demo/cca/prov-verif-e2e
+
+# Check that data/keys and data/templates exist
+ls -la data/keys/
+ls -la data/templates/
+```
+
+### Health Check Failures
+
+**Problem**: Services are running but health checks fail
+
+**Solution**:
+```bash
+# Manual health check
+curl http://localhost:8080/health
+
+# Check service logs for errors
+docker compose logs <service-name>
+
+# Wait longer for services to start
+sleep 10 && ./scripts/healthcheck.sh http://localhost:8080/health
+```
+
+## Build and Validation Issues
+
+### Make Validate Fails
+
+**Problem**: `make validate` exits with error
+
+**Solution**:
+```bash
+# This is expected if tools are missing
+# Install missing dependencies first
+./scripts/setup.sh
+
+# Then retry
+make validate
+```
+
+### Shellcheck Reports Issues
+
+**Problem**: `make shellcheck` reports warnings or errors
+
+**Solution**:
+- Review the reported issues in your shell scripts
+- Most are suggestions for better practices
+- Critical issues should be fixed before committing
+
+### OpenAPI Validation Fails
+
+**Problem**: API specs fail validation
+
+**Solution**:
+```bash
+# Check specific API directory
+cd api/challenge-response
+make
+
+# Review the error messages
+# Common issues: missing required fields, invalid references
+```
+
+## Getting Help
+
+If you encounter issues not covered here:
+
+1. Check the [Veraison Zulip channel](https://veraison.zulipchat.com)
+2. Review existing GitHub issues: https://github.com/veraison/docs/issues
+3. Open a new issue with:
+   - Your platform and versions
+   - Output from `./scripts/validate-setup.sh`
+   - Complete error messages
+   - Steps to reproduce
diff --git a/demo/cca/README.md b/demo/cca/README.md
new file mode 100644
index 0000000..b1ab929
--- /dev/null
+++ b/demo/cca/README.md
@@ -0,0 +1,36 @@
+# CCA Demo: Minimal Placeholder
+
+This folder contains a minimal placeholder `docker-compose.yml` that demonstrates how
+to provide a one-command demo orchestration for CCA attestation. It's intentionally
+a placeholder and should be replaced with real CCA verification services.
+
+## Quick Start
+
+```bash
+cd demo/cca
+docker compose up -d
+docker compose ps
+```
+
+## Health Checks
+
+```bash
+# Check CCA verifier
+../../scripts/healthcheck.sh http://localhost:8081/ || echo "Service starting..."
+
+# Check CCA provisioning
+../../scripts/healthcheck.sh http://localhost:8889/ || echo "Service starting..."
+```
+
+## Stop Services
+
+```bash
+docker compose down
+```
+
+## Next Steps
+
+For the full CCA demo with real attestation:
+- See [manual-end-to-end.md](manual-end-to-end.md) for detailed steps
+- Replace placeholder services with actual Veraison CCA components
+- Update docker-compose.yml with proper service images and configuration
diff --git a/demo/cca/docker-compose.yml b/demo/cca/docker-compose.yml
new file mode 100644
index 0000000..4cd3961
--- /dev/null
+++ b/demo/cca/docker-compose.yml
@@ -0,0 +1,36 @@
+version: '3.8'
+
+services:
+  # Veraison CCA verification service (placeholder)
+  cca-verifier:
+    image: nginx:alpine
+    ports:
+      - "8081:80"
+    volumes:
+      - ./data:/usr/share/nginx/html:ro
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - veraison-cca-net
+
+  # CCA provisioning service (placeholder)
+  cca-provisioning:
+    image: nginx:alpine
+    ports:
+      - "8889:80"
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - veraison-cca-net
+
+networks:
+  veraison-cca-net:
+    driver: bridge
diff --git a/demo/psa/README.md b/demo/psa/README.md
new file mode 100644
index 0000000..862324d
--- /dev/null
+++ b/demo/psa/README.md
@@ -0,0 +1,56 @@
+# PSA Demo: Quick Start
+
+This folder contains a placeholder `docker-compose.yml` that demonstrates one-command
+demo orchestration for PSA attestation. The services are placeholders and should be
+replaced with actual Veraison PSA components.
+
+## Quick Start
+
+### Using Make (Recommended)
+
+```sh
+# From repository root
+make demo-psa
+make health-check
+```
+
+### Using Docker Compose Directly
+
+```sh
+cd demo/psa
+docker compose up -d
+docker compose ps
+```
+
+## Services
+
+- **Verifier**: Listens on port 8080
+- **Provisioning**: Listens on port 8888
+
+## Health Checks
+
+```sh
+# Check verifier
+../../scripts/healthcheck.sh http://localhost:8080/
+
+# Check provisioning
+../../scripts/healthcheck.sh http://localhost:8888/
+```
+
+## Stop Services
+
+```sh
+docker compose down
+# or from repository root:
+make clean
+```
+
+## Next Steps
+
+For complete PSA demo walkthroughs:
+- [Manual End-to-End](manual-end-to-end.md) - Detailed manual workflow
+- [Automated End-to-End](automated-end-to-end.md) - Automated testing
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md) for common issues.
diff --git a/demo/psa/docker-compose.yml b/demo/psa/docker-compose.yml
new file mode 100644
index 0000000..7a73f00
--- /dev/null
+++ b/demo/psa/docker-compose.yml
@@ -0,0 +1,36 @@
+version: '3.8'
+
+services:
+  # Veraison verification service (placeholder)
+  verifier:
+    image: nginx:alpine
+    ports:
+      - "8080:80"
+    volumes:
+      - ./data:/usr/share/nginx/html:ro
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - veraison-net
+
+  # Provisioning service (placeholder)
+  provisioning:
+    image: nginx:alpine
+    ports:
+      - "8888:80"
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - veraison-net
+
+networks:
+  veraison-net:
+    driver: bridge
diff --git a/docs/ERROR_HANDLING.md b/docs/ERROR_HANDLING.md
new file mode 100644
index 0000000..666aaca
--- /dev/null
+++ b/docs/ERROR_HANDLING.md
@@ -0,0 +1,241 @@
+# Error Handling Guide
+
+This guide documents common error scenarios and their handling across Veraison documentation and demos.
+
+## Common Error Scenarios
+
+### 1. Invalid Token Format
+
+**Scenario**: Evidence token is malformed or uses incorrect encoding.
+
+**Detection**:
+```
+Error: failed to decode token: invalid format
+```
+
+**Resolution**:
+- Verify token is properly base64-encoded
+- Check token structure matches expected format (CoRIM, PSA, CCA)
+- Validate JSON structure for claims
+
+**Prevention**:
+- Use provided templates in `demo/*/data/templates/`
+- Validate tokens before submission
+
+### 2. Missing Endorsements
+
+**Scenario**: Reference values or endorsements not provisioned before verification.
+
+**Detection**:
+```
+Error: no matching reference values found
+Error: endorsement not found for platform
+```
+
+**Resolution**:
+1. Provision endorsements first using the provisioning API
+2. Verify endorsement was accepted: check API response
+3. Confirm evidence fields match provisioned reference values
+
+**Order of Operations**:
+```bash
+# 1. Provision endorsements
+curl -X POST http://localhost:8888/endorsement-provisioning/v1/submit \
+  -H "Content-Type: application/corim-unsigned+cbor; profile=http://arm.com/psa/iot/1" \
+  -d @corim.cbor
+
+# 2. Verify evidence
+curl -X POST http://localhost:8080/challenge-response/v1/newSession
+```
+
+### 3. Network Connectivity Issues
+
+**Scenario**: Services cannot communicate with each other.
+
+**Detection**:
+```
+Error: connection refused
+Error: dial tcp: lookup failed
+```
+
+**Resolution**:
+- Check all services are running: `docker compose ps`
+- Verify network configuration in docker-compose.yml
+- Check firewall rules
+- Use service names (not localhost) in Docker network
+
+### 4. Certificate/Key Errors
+
+**Scenario**: Invalid or missing cryptographic keys.
+
+**Detection**:
+```
+Error: failed to verify signature
+Error: certificate verification failed
+```
+
+**Resolution**:
+- Verify key files exist in `demo/*/data/keys/`
+- Check key format matches expected type (EC256, EC384, etc.)
+- Ensure public/private key pairs match
+- Validate key permissions (should be readable)
+
+### 5. Schema Validation Errors
+
+**Scenario**: API requests fail schema validation.
+
+**Detection**:
+```
+Error: invalid request: missing required field
+Error: schema validation failed
+```
+
+**Resolution**:
+- Review OpenAPI specifications in `api/*/schemas/`
+- Check request Content-Type headers
+- Validate JSON/CBOR structure
+- Use provided templates as reference
+
+## Error Handling Best Practices
+
+### For Demo Users
+
+1. **Check Prerequisites**:
+   ```bash
+   ./scripts/validate-setup.sh
+   ```
+
+2. **Start Services in Order**:
+   ```bash
+   # Start verification services first
+   docker compose up -d
+   
+   # Wait for health checks
+   ./scripts/healthcheck.sh http://localhost:8080/health
+   
+   # Then proceed with provisioning
+   ```
+
+3. **Enable Verbose Logging**:
+   ```bash
+   # Add to docker-compose.yml environment
+   VERAISON_LOG_LEVEL: debug
+   ```
+
+4. **Capture Logs**:
+   ```bash
+   docker compose logs > debug.log
+   ```
+
+### For Contributors
+
+1. **Validate Before Commit**:
+   ```bash
+   make validate
+   make shellcheck
+   ```
+
+2. **Test Error Paths**:
+   - Include negative test cases
+   - Document expected error messages
+   - Test with invalid inputs
+
+3. **Document Error Messages**:
+   - Clear, actionable error messages
+   - Include context and suggested fixes
+   - Reference relevant documentation
+
+## API Error Responses
+
+### Standard Error Format
+
+```json
+{
+  "error": "brief error description",
+  "detail": "detailed explanation of what went wrong",
+  "status": 400,
+  "suggestion": "what to do next"
+}
+```
+
+### Common HTTP Status Codes
+
+- `400 Bad Request`: Invalid input data, schema validation failure
+- `401 Unauthorized`: Missing or invalid authentication
+- `404 Not Found`: Resource (endorsement, session) not found
+- `409 Conflict`: Resource already exists
+- `500 Internal Server Error`: Service error, check logs
+- `503 Service Unavailable`: Service not ready, retry later
+
+## Debugging Tips
+
+### Enable Debug Mode
+
+For shell scripts:
+```bash
+bash -x ./scripts/setup.sh
+```
+
+For Docker services:
+```yaml
+environment:
+  DEBUG: "1"
+  LOG_LEVEL: "debug"
+```
+
+### Inspect Service State
+
+```bash
+# Check service health
+docker compose ps
+
+# View service logs
+docker compose logs -f <service>
+
+# Execute commands in container
+docker compose exec <service> sh
+
+# Inspect network
+docker network inspect <network-name>
+```
+
+### Validate Data Files
+
+```bash
+# Check JSON syntax
+jq . < data/templates/psa-claims.json
+
+# Validate CBOR (requires cbor-diag)
+cbor2diag < data.cbor
+
+# Check file permissions
+ls -la data/keys/
+```
+
+## Reporting Issues
+
+When reporting errors, include:
+
+1. **Environment Information**:
+   ```bash
+   ./scripts/validate-setup.sh
+   docker --version
+   docker compose version
+   ```
+
+2. **Complete Error Messages**:
+   - Full command that failed
+   - Complete error output
+   - Relevant log excerpts
+
+3. **Steps to Reproduce**:
+   - Starting state
+   - Exact commands run
+   - Expected vs actual behavior
+
+4. **Context**:
+   - Which demo (PSA, CCA)
+   - Platform (Ubuntu, macOS, Windows/WSL)
+   - Any modifications made
+
+Report issues at: https://github.com/veraison/docs/issues
diff --git a/scripts/healthcheck.sh b/scripts/healthcheck.sh
new file mode 100755
index 0000000..fe40f33
--- /dev/null
+++ b/scripts/healthcheck.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# scripts/healthcheck.sh - simple service health check examples
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: $0 <url>"
+  exit 2
+fi
+
+URL=$1
+
+if command -v curl >/dev/null 2>&1; then
+  status=$(curl -s -o /dev/null -w "%{http_code}" "$URL" || true)
+  if [[ "$status" =~ ^2 ]]; then
+    echo "HEALTHY: $URL returned $status"
+    exit 0
+  else
+    echo "UNHEALTHY: $URL returned $status"
+    exit 1
+  fi
+else
+  echo "curl not installed; install curl to run health checks"
+  exit 2
+fi
diff --git a/scripts/quick-start.sh b/scripts/quick-start.sh
new file mode 100755
index 0000000..8420074
--- /dev/null
+++ b/scripts/quick-start.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# scripts/quick-start.sh - minimal quick start for local evaluation (requires Docker)
+set -euo pipefail
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "Docker is required for quick-start. Please install Docker or run 'scripts/setup.sh'"
+  exit 2
+fi
+
+echo "Starting a minimal quick-start environment using Docker."
+
+echo "Pulling a small busybox image as a placeholder demo (no network services are required)."
+docker pull busybox:latest >/dev/null
+
+echo "Running a quick command inside a short-lived container to verify Docker works."
+docker run --rm busybox:latest echo "Quick-start: docker run succeeded"
+
+echo "Quick-start finished. This repository's demos require more specific images and compose files which
+should be added per-demo under 'demo/'. See demo/psa/ and demo/cca/ for example workflows."
diff --git a/scripts/setup.sh b/scripts/setup.sh
new file mode 100755
index 0000000..85327cc
--- /dev/null
+++ b/scripts/setup.sh
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# scripts/setup.sh - install minimal developer prerequisites (non-destructive)
+set -euo pipefail
+
+usage(){
+  cat <<EOF
+Usage: $(basename "$0") [--dry-run]
+
+Installs or suggests installation steps for common developer dependencies used by the
+Veraison documentation (docker, docker-compose, protoc, shellcheck).
+This script is conservative: it prints commands and prompts before making changes.
+EOF
+}
+
+DRY_RUN=0
+while [[ ${#} -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift;;
+    -h|--help) usage; exit 0;;
+    *) echo "Unknown arg: $1"; usage; exit 2;;
+  esac
+done
+
+echo "Checking common tools..."
+need_install=()
+check(){
+  if ! command -v "$1" >/dev/null 2>&1; then
+    need_install+=("$1")
+    echo " - $1: MISSING"
+  else
+    echo " - $1: found ($(command -v "$1"))"
+  fi
+}
+
+check docker
+check docker-compose || check docker-compose
+check protoc
+check shellcheck
+
+if [[ ${#need_install[@]} -eq 0 ]]; then
+  echo "All common tools detected."
+  exit 0
+fi
+
+echo "\nTools suggested for install: ${need_install[*]}"
+if [[ $DRY_RUN -eq 1 ]]; then
+  echo "Dry run: not installing anything."
+  exit 0
+fi
+
+read -r -p "Proceed with printed install suggestions? [y/N] " ans
+case "$ans" in
+  [Yy]*) ;;
+  *) echo "Aborting per user request."; exit 0;;
+esac
+
+for t in "${need_install[@]}"; do
+  echo "\nSuggested install for: $t"
+  case "$t" in
+    docker)
+      cat <<'CMD'
+On Debian/Ubuntu:
+  sudo apt-get update && sudo apt-get install -y ca-certificates curl gnupg lsb-release
+  curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+  echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+  sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io
+CMD
+      ;;
+    docker-compose)
+      cat <<'CMD'
+Install via pip (if using compose v1) or use Docker's compose plugin:
+  python3 -m pip install --user docker-compose
+Or on modern systems:
+  sudo apt-get install -y docker-compose-plugin
+CMD
+      ;;
+    protoc)
+      echo "Visit https://github.com/protocolbuffers/protobuf/releases and download a release for your OS. On debian/ubuntu: sudo apt-get install -y protobuf-compiler"
+      ;;
+    shellcheck)
+      echo "On Debian/Ubuntu: sudo apt-get install -y shellcheck"
+      ;;
+    *)
+      echo "No automated instruction for $t; please install it using your platform package manager."
+      ;;
+  esac
+done
+
+echo "\nSetup script finished. Re-run 'scripts/validate-setup.sh' to verify the environment."
diff --git a/scripts/validate-setup.sh b/scripts/validate-setup.sh
new file mode 100755
index 0000000..81b4a68
--- /dev/null
+++ b/scripts/validate-setup.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# scripts/validate-setup.sh - run pre-flight checks for documentation developer environment
+set -euo pipefail
+
+echo "Running pre-flight checks for Veraison docs development environment"
+missing=0
+check(){
+  if ! command -v "$1" >/dev/null 2>&1; then
+    echo "[FAIL] Missing: $1"
+    missing=1
+  else
+    echo "[ OK ] Found: $1 -> $(command -v "$1")"
+  fi
+}
+
+# Check for Docker (required)
+check docker
+
+# Check for docker-compose (v1) or docker compose plugin (v2)
+if command -v docker-compose >/dev/null 2>&1; then
+  echo "[ OK ] Found: docker-compose -> $(command -v docker-compose)"
+elif docker compose version >/dev/null 2>&1; then
+  echo "[ OK ] Found: docker compose (plugin)"
+else
+  echo "[WARN] docker-compose not found (optional, demos may not work)"
+fi
+
+# Check optional tools
+if command -v protoc >/dev/null 2>&1; then
+  echo "[ OK ] Found: protoc -> $(command -v protoc)"
+else
+  echo "[WARN] protoc not found (optional)"
+fi
+
+if command -v shellcheck >/dev/null 2>&1; then
+  echo "[ OK ] Found: shellcheck -> $(command -v shellcheck)"
+else
+  echo "[WARN] shellcheck not found (optional)"
+fi
+
+if [[ $missing -ne 0 ]]; then
+  echo "One or more required tools are missing. Run scripts/setup.sh for guidance."
+  exit 2
+fi
+
+echo "All required tools appear installed."