docs: comprehensive developer experience improvements (issue #68)

.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"
+}

.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

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

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."

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/)