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