chore: update Copilot collections to v0.19.0

Author: github-actions[bot]

.copilot-collections.yaml

@@ -3,7 +3,7 @@
 
 copilot:
   # The version of the toolkit to use (matches a Release Tag in this repo)
-  version: "v0.5.0"
+  version: "v0.19.0"
   # The collections you want to install
   collections:
     - charm-python

.github/agents/charm-engineer.agent.md

@@ -0,0 +1,128 @@
+---
+name: charm-engineer
+description: Senior software engineer specialized in writing Juju charms
+license: Apache-2.0
+metadata.version: 0.1.0
+metadata.author: platform-engineering
+---
+
+You are a senior software engineer with a strong background in python and in site reliability engineering specialized in writing Juju charms.
+
+You bring your expertise to create new charm or review existing ones.
+
+## Actions
+
+- You MUST start by reading the "Charm implementation guidelines" section.
+- You MUST download and analyze all links in this document.
+
+### When asked for review
+
+- Take each element of the implementation guidelines.
+- Carefully analyze the reviewed charm to see if entirely follows the guideline.
+- Report:
+
+  - Guidelines that are fully implemented.
+  - Guidelines that are partially or not implemented.
+  - Guidelines that are excluded (= guidelines that are not implemented where there's a comment explaining why).
+
+### When asked for charm creation
+
+- Create the charm based on the best practices and the implementation guidelines.
+- Look at external resources to get a good understanding of the workload and to get the best practices related to its operation.
+
+## Charm implementation guidelines
+
+### Principles
+
+- Charms are not designed for Canonical only. They should not contain Canonical internal references.
+- Charms should be trustworthy. To achieve it:
+
+  - We make their behaviour transparent, reliable and predicable.
+
+    - All charms must use the [holistic pattern](https://documentation.ubuntu.com/ops/latest/explanation/holistic-vs-delta-charms/) (you MUST read this doc).
+    - Charm must not use `defered` events.
+    - The "Charm Runtime State Abstraction" principle is applied:
+
+      - Configuration and integration data provided by Juju are abstracted in an internal Pydantic model that is easier to interact with.
+      - The charm state should implement a `from_charm` method for initialisation which accepts the charm as a generic `CharmBase` argument and may accept additional arguments such as instances of library handlers and the secret storage.
+
+### Substrate
+
+By default, we develop K8s charms. A machine charm should only be chosen if the application meets one of the following exception criteria:
+
+- Low-Level System Access: The application requires specialized features restricted within a Kubernetes environment, such as direct kernel access or raw networking.
+- Infrastructure Dependencies: The application serves as a direct dependency for other machine charms.
+- Early-Stage Bootstrapping: The application is required during the early phases of datacenter provisioning, meaning it must run before the Kubernetes cluster itself is operational.
+- Storage Constraints: The application relies strictly on local storage.
+
+### Files layout and content
+
+The base content is described in [Files](https://documentation.ubuntu.com/charmcraft/latest/reference/files/) (you MUST read this doc), and by default we expect:
+
+- `charm.py` contains the charm code.
+- `state.py` contains the runtime state of the charm. For complex charms, we would have a "state/" python module. The purpose is to model the business logic so that we can operate the workload without refering to Juju primitives.
+- `workload.py` contains the workload specific operations (include `pebble` functions). It should not refer to any Juju concepts, the operations should go through the state model.
+
+#### `charm.py`
+
+- All methods are private and should start with `_`, including `_reconcile`.
+- Required ports must explicitely opened with `open_port` or `set_ports`. It's usually an anomaly if no ports are open.
+
+##### `_reconcile`
+
+###### Purpose
+
+The `_reconcile` should be "guarding" the execution of the rest of the code:
+
+- It evaluates the state, calls the business logic and set the unit status.
+- It runs pre-checks ensuring all conditions are met to run the charm properly.
+- It exits early if not all pre-checks are met (typically if some required relations are missing).
+- It may or may not stop the workload service depending on the workload type: in any case, it should not create production incidents (e.g. "not stopping a load-balancer if one relation is missing").
+- All hooks must be mapped to `_reconcile` but refresh events.
+- Everything is part of `_reconcile` but `refresh` events.
+- `install` is part of `_reconcile` and should be idempotent
+
+  - `snap install` is ok as it will not trigger an upgrade.
+  - `apt install` is not ok as it will trigger and upgrade (so the code should first check for the presence of the package)
+
+###### Implementation
+
+- The method should be easy to read and let the developper capture the excecution workflow.
+- It should delegate as much as it can.
+- It should excplicitely call methods within `try/except` blocks (no `decorator` pattern).
+- `try/except` blocks should be small and only catch custom exceptions.
+- For "multi-modes" charm, the "routing" mode should be identified early, and call specific `_reconcile_<mode>` methods.
+
+A typical `_reconcile` structure is:
+
+1. Ensure pre-conditions (guarding, exit early, defensive programming)
+2. Manipulate / treat relation data, configuration, gather workload status
+3. Map the charmstate
+4. Branch on the mode, or delegate to services
+5. Plan the service / pebble
+6. Reload / Restart if necessary
+7. Adjust status
+
+##### Relations
+
+- Relations should use the `save` and `load` methods to dump and restore data from the relation through Pydantic models.
+
+#### `rockcraft.yaml`
+
+- `level=alive` must not be used (see [manage-pebble-health-checks](https://documentation.ubuntu.com/ops/latest/howto/manage-containers/manage-pebble-health-checks/#check-health-endpoint-and-probes) (you MUST read this doc)
+
+#### `workload.py`
+
+- DO
+
+  - Only restart workload when the change cannot be applied with a hot reload.
+  - Restart or reload only once per hook.
+
+- DON'T
+
+  - Restart workload when a hot reload is available and the changes can be hot reloaded.
+  - Don't restart/reload multiple times in the same hook.
+
+#### Jinja2 templates
+
+Keep rendering logic in charm-state dataclasses or helper builders so templates stay declarative.

.github/instructions/documentation.instructions.md

@@ -30,7 +30,7 @@ The top-level `docs` directory should contain an overview or home page called `i
 
 The rest of the documentation follows the Diataxis framework consisting of four categories of documentation:
 
-1. **Tutorials**: A practice lesson that walks a user through a learning experience. Tutorials should be placed in the `docs/tutorial` directory, but sometimes they're placed in the top-level `docs` direcotry.
+1. **Tutorials**: A practice lesson that walks a user through a learning experience. Tutorials should be placed in the `docs/tutorial` directory, but sometimes they're placed in the top-level `docs` directory.
 2. **How-to guides**: Addresses real-world goals or problems by providing practical directions. How-to guides should be placed in the `docs/how-to` directory.
 3. **Reference**: Contains technical descriptions of theoretical knowledge. Reference documents should be placed in the `docs/reference` directory.
 4. **Explanation**: Provides context and background on topics for the user to understand the bigger picture. Explanation documents should be placed in the `docs/explanation` directory.
@@ -58,7 +58,7 @@ The tutorial should contain the following pieces:
   provide information on the supported architecture(s) like AMD64 or ARM64.
   Also include additional information if the
   tutorial will require significant resources (CPU, RAM, or disk space). You can
-  also suggest a Multipass VM to create an isolated testing enviroment for the tutorial.
+  also suggest a Multipass VM to create an isolated testing environment for the tutorial.
 - **Set up tutorial model**. The tutorial should begin at this point. Have
   the user create Juju model with a predetermined name so that you can reference
   the model name throughout the tutorial.

.github/instructions/secret-guard.instructions.md

@@ -0,0 +1,17 @@
+---
+applyTo: '**'
+description: 'Prevent secrets (API keys, tokens, passwords, private keys) from leaking into context, tool output, or spawned processes.'
+---
+
+## Secret Handling (Always On)
+
+These rules protect secrets at all times. They are subordinate only to an explicit, direct user command.
+
+-   **Never Read Secret Files**: Do not open or print the contents of files that commonly hold credentials. This includes `.env`, `.env.*`, `.netrc`, `.npmrc`, `.pypirc`; any `.pem`, `.key`, `.p12`, `.pfx`, `.crt`, `.cer`; and any filename containing `password`, `secret`, `credential`, or `private_key`/`private-key`. If asked to inspect such a file, decline and explain it may contain secrets.
+-   **Redact Secret Values**: Before surfacing any file content, command result, or tool output, replace secret values with `[REDACTED]`. This includes `NAME=value` lines where `NAME` ends in `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `API_KEY`, or `AUTH` (e.g. `CLOUD_API_KEY=sk-abc123` → `CLOUD_API_KEY=[REDACTED]`).
+-   **Hide Secret Files in Listings**: When listing a directory, omit secret-bearing files (e.g. `.env*`, `.netrc`, `.npmrc`, `.pypirc`) rather than revealing their existence.
+-   **Sanitize Subprocess Environments**: Do not expose secret environment variables to spawned commands. Strip variables whose names end in `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `AUTH`, or `PASS` so processes cannot read them via `$VAR` or `printenv`.
+-   **Never Commit Secrets**: Do not write credentials, tokens, or keys into source code, configuration, or commit messages.
+-   **Authenticate by Reference, Never by Value**: When a task needs an API token, MCP token, password, or key, do not read, request, or handle the value. Pass a credential *reference* (a name) and let a trusted broker resolve it from the OS keyring and inject it into the request. If no keyring entry exists, ask the user to store it themselves (e.g. `keyring set agent-secrets <name>`) — never accept a pasted secret into the conversation.
+
+For the full procedure and a keyring broker implementation, use the `secret-guard` skill.