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/roles/incus_storage_bucket/defaults/main.yml

@@ -0,0 +1,17 @@
+---
+# Default variables for incus_storage_bucket role
+
+# Incus configuration (should match terraform.tfvars)
+storage_pool: default
+project_name: agathos
+bucket_role: admin
+
+# Service-specific variables (must be provided)
+# bucket_name: casdoor
+# service_name: casdoor
+
+# Path to S3 credentials vault file (separate from main vault)
+s3_credentials_file: "{{ playbook_dir }}/inventory/group_vars/all/s3_vault.yml"
+
+# Task selection
+task_action: create  # create, regenerate, or remove

ansible/roles/incus_storage_bucket/meta/main.yml

@@ -0,0 +1,22 @@
+---
+# Role metadata and dependencies
+
+galaxy_info:
+  author: Agathos Project
+  description: Manages Incus S3-compatible storage buckets with Ansible Vault credential storage
+  license: MIT
+  min_ansible_version: "2.9"
+  platforms:
+    - name: Ubuntu
+      versions:
+        - noble
+        - plucky
+        - questing
+
+dependencies: []
+
+# Requirements:
+# - User running the playbook must be a member of the 'incus' group
+# - Incus CLI must be configured and accessible
+# - ANSIBLE_VAULT_PASSWORD_FILE environment variable must be set
+# - ansible-vault command must be available in PATH

ansible/roles/incus_storage_bucket/tasks/main.yml

@@ -0,0 +1,92 @@
+---
+# Main task file for incus_storage_bucket role
+# Creates Incus S3 buckets and outputs credentials to console
+
+- name: Validate required variables
+  ansible.builtin.assert:
+    that:
+      - bucket_name is defined
+    fail_msg: "Required variable not defined: bucket_name"
+
+- name: Check if bucket already exists
+  ansible.builtin.command:
+    cmd: incus storage bucket list {{ storage_pool }} --project={{ project_name }} --format=json
+  register: bucket_list
+  changed_when: false
+  failed_when: false
+
+- name: Parse bucket list
+  ansible.builtin.set_fact:
+    existing_buckets: "{{ bucket_list.stdout | from_json | map(attribute='name') | list }}"
+  when: bucket_list.rc == 0
+
+- name: Create storage bucket
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket create {{ storage_pool }} {{ bucket_name }}
+      --project={{ project_name }}
+  when: bucket_name not in (existing_buckets | default([]))
+  register: bucket_created
+
+- name: Set key name
+  ansible.builtin.set_fact:
+    key_name: "{{ bucket_name }}-access"
+
+- name: Check if bucket key already exists
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket key list {{ storage_pool }} {{ bucket_name }}
+      --project={{ project_name }} --format=json
+  register: key_list
+  changed_when: false
+  failed_when: false
+
+- name: Parse key list
+  ansible.builtin.set_fact:
+    existing_keys: "{{ key_list.stdout | from_json | map(attribute='name') | list }}"
+  when: key_list.rc == 0
+
+- name: Create bucket access key
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket key create {{ storage_pool }} {{ bucket_name }} {{ key_name }}
+      --role={{ bucket_role }} --project={{ project_name }}
+  register: key_created
+  when: key_name not in (existing_keys | default([]))
+
+- name: Show bucket key (for existing key)
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket key show {{ storage_pool }} {{ bucket_name }} {{ key_name }}
+      --project={{ project_name }}
+  register: key_show
+  changed_when: false
+  when: key_name in (existing_keys | default([]))
+
+- name: Parse credentials from YAML output
+  ansible.builtin.set_fact:
+    bucket_credentials: "{{ (key_created.stdout | default(key_show.stdout)) | from_yaml }}"
+
+- name: Get bucket info for endpoint
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket show {{ storage_pool }} {{ bucket_name }}
+      --project={{ project_name }}
+  register: bucket_info
+  changed_when: false
+
+- name: Parse bucket info from YAML
+  ansible.builtin.set_fact:
+    bucket_data: "{{ bucket_info.stdout | from_yaml }}"
+
+- name: Display S3 bucket credentials
+  ansible.builtin.debug:
+    msg:
+      - "============================================"
+      - "S3 BUCKET PROVISIONED: {{ bucket_name }}"
+      - "============================================"
+      - "Endpoint:   {{ bucket_data.s3_url }}"
+      - "Bucket:     {{ bucket_name }}"
+      - "Access Key: {{ bucket_credentials['access-key'] }}"
+      - "Secret Key: {{ bucket_credentials['secret-key'] }}"
+      - "============================================"

ansible/roles/incus_storage_bucket/tasks/regenerate.yml

@@ -0,0 +1,58 @@
+---
+# Regenerate bucket access key - outputs new credentials to console
+# Use with caution - invalidates existing credentials
+
+- name: Validate required variables
+  ansible.builtin.assert:
+    that:
+      - bucket_name is defined
+    fail_msg: "Required variable not defined: bucket_name"
+
+- name: Set key name
+  ansible.builtin.set_fact:
+    key_name: "{{ bucket_name }}-access"
+
+- name: Delete existing bucket key
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket key delete {{ storage_pool }} {{ bucket_name }} {{ key_name }}
+      --project={{ project_name }}
+  register: key_deleted
+  failed_when: false
+
+- name: Create new bucket access key
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket key create {{ storage_pool }} {{ bucket_name }} {{ key_name }}
+      --role={{ bucket_role }} --project={{ project_name }}
+  register: key_created
+
+- name: Parse new credentials from text output
+  ansible.builtin.set_fact:
+    bucket_credentials:
+      access-key: "{{ key_created.stdout | regex_search('Access key: (.+)', '\\1') | first }}"
+      secret-key: "{{ key_created.stdout | regex_search('Secret key: (.+)', '\\1') | first }}"
+
+- name: Get bucket info for endpoint
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket show {{ storage_pool }} {{ bucket_name }}
+      --project={{ project_name }}
+  register: bucket_info
+  changed_when: false
+
+- name: Parse bucket info from YAML
+  ansible.builtin.set_fact:
+    bucket_data: "{{ bucket_info.stdout | from_yaml }}"
+
+- name: Display new S3 bucket credentials
+  ansible.builtin.debug:
+    msg:
+      - "============================================"
+      - "S3 BUCKET KEY REGENERATED: {{ bucket_name }}"
+      - "============================================"
+      - "Endpoint:       {{ bucket_data.s3_url }}"
+      - "Bucket:         {{ bucket_name }}"
+      - "New Access Key: {{ bucket_credentials['access-key'] }}"
+      - "New Secret Key: {{ bucket_credentials['secret-key'] }}"
+      - "============================================"

ansible/roles/incus_storage_bucket/tasks/remove.yml

@@ -0,0 +1,48 @@
+---
+# Remove bucket - outputs confirmation to console
+# Use with extreme caution - data loss is permanent
+
+- name: Validate required variables
+  ansible.builtin.assert:
+    that:
+      - bucket_name is defined
+    fail_msg: "Required variable not defined: bucket_name"
+
+- name: Set key name
+  ansible.builtin.set_fact:
+    key_name: "{{ bucket_name }}-access"
+
+- name: Confirm deletion
+  ansible.builtin.pause:
+    prompt: "WARNING: This will permanently delete bucket '{{ bucket_name }}' and all its data. Type 'yes' to continue"
+  register: confirm_delete
+
+- name: Abort if not confirmed
+  ansible.builtin.fail:
+    msg: "Deletion aborted by user"
+  when: confirm_delete.user_input != 'yes'
+
+- name: Delete bucket key
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket key delete {{ storage_pool }} {{ bucket_name }} {{ key_name }}
+      --project={{ project_name }}
+  register: key_deleted
+  failed_when: false
+
+- name: Delete storage bucket
+  ansible.builtin.command:
+    cmd: >
+      incus storage bucket delete {{ storage_pool }} {{ bucket_name }}
+      --project={{ project_name }}
+  register: bucket_deleted
+
+- name: Display removal confirmation
+  ansible.builtin.debug:
+    msg:
+      - "============================================"
+      - "S3 BUCKET REMOVED: {{ bucket_name }}"
+      - "============================================"
+      - "Remember to remove credentials from vault.yml"
+      - "============================================"
+  when: bucket_deleted is succeeded