docs: rewrite README with structured overview and quick start guide

Replaces the minimal project description with a comprehensive README
including a component overview table, quick start instructions, common
Ansible operations, and links to detailed documentation. Aligns with
Red Panda Approval™ standards.

ansible/inventory/host_vars/puck.incus.yml

@@ -0,0 +1,46 @@
+---
+# Puck Configuration - Application Runtime
+# Services: alloy, docker, lxqt, jupyterlab
+
+services:
+  - alloy
+  - docker
+  - gitea_runner
+  - jupyterlab
+
+# Gitea Runner
+gitea_runner_name: "puck-runner"
+
+# Alloy
+alloy_log_level: "warn"
+angelia_syslog_port: 51421
+sagittarius_syslog_port: 51431
+athena_syslog_port: 51441
+kairos_syslog_port: 51451
+icarlos_syslog_port: 51461
+spelunker_syslog_port: 51481
+jupyterlab_syslog_port: 51491
+
+# =============================================================================
+# JupyterLab Configuration
+# =============================================================================
+jupyterlab_user: robert
+jupyterlab_group: robert
+jupyterlab_notebook_dir: /home/robert
+jupyterlab_venv_dir: /home/robert/env/jupyter
+
+# Ports
+jupyterlab_port: 22081           # JupyterLab (localhost only)
+jupyterlab_proxy_port: 22071     # OAuth2-Proxy (exposed to HAProxy)
+
+# OAuth2-Proxy Configuration
+jupyterlab_oauth2_proxy_dir: /etc/oauth2-proxy-jupyter
+jupyterlab_oauth2_proxy_version: "7.6.0"
+jupyterlab_domain: "ouranos.helu.ca"
+jupyterlab_oauth2_oidc_issuer_url: "https://id.ouranos.helu.ca"
+jupyterlab_oauth2_redirect_url: "https://jupyterlab.ouranos.helu.ca/oauth2/callback"
+
+# OAuth2 Credentials (from vault)
+jupyterlab_oauth_client_id: "{{ vault_jupyterlab_oauth_client_id }}"
+jupyterlab_oauth_client_secret: "{{ vault_jupyterlab_oauth_client_secret }}"
+jupyterlab_oauth2_cookie_secret: "{{ vault_jupyterlab_oauth2_cookie_secret }}"