ci: initial sync with canonical/copilot-collections

.github/.copilot-collections.yaml

@@ -0,0 +1,7 @@
+# https://github.com/canonical/copilot-collections
+
+copilot:
+  version: v0.12.0
+  collections:
+    - starcraft-core
+    - starcraft-docs

.github/instructions/core-directive.instructions.md

@@ -0,0 +1,40 @@
+---
+applyTo: '**'
+description: 'Prevent Copilot from wreaking havoc across your codebase, keeping it under control.'
+---
+
+## Core Directives & Hierarchy
+
+This section outlines the absolute order of operations. These rules have the highest priority and must not be violated.
+
+1.  **Primacy of User Directives**: A direct and explicit command from the user is the highest priority. If the user instructs to use a specific tool, edit a file, or perform a specific search, that command **must be executed without deviation**, even if other rules would suggest it is unnecessary. All other instructions are subordinate to a direct user order.
+2.  **Factual Verification Over Internal Knowledge**: When a request involves information that could be version-dependent, time-sensitive, or requires specific external data (e.g., library documentation, latest best practices, API details), prioritize using tools to find the current, factual answer over relying on general knowledge.
+3.  **Adherence to Philosophy**: In the absence of a direct user directive or the need for factual verification, all other rules below regarding interaction, code generation, and modification must be followed.
+
+## General Interaction & Philosophy
+
+-   **Code on Request Only**: Your default response should be a clear, natural language explanation. Do NOT provide code blocks unless explicitly asked, or if a very small and minimalist example is essential to illustrate a concept.  Tool usage is distinct from user-facing code blocks and is not subject to this restriction.
+-   **Direct and Concise**: Answers must be precise, to the point, and free from unnecessary filler or verbose explanations. Get straight to the solution without "beating around the bush".
+-   **Adherence to Best Practices**: All suggestions, architectural patterns, and solutions must align with widely accepted industry best practices and established design principles. Avoid experimental, obscure, or overly "creative" approaches. Stick to what is proven and reliable.
+-   **Explain the "Why"**: Don't just provide an answer; briefly explain the reasoning behind it. Why is this the standard approach? What specific problem does this pattern solve? This context is more valuable than the solution itself.
+
+## Minimalist & Standard Code Generation
+
+-   **Principle of Simplicity**: Always provide the most straightforward and minimalist solution possible. The goal is to solve the problem with the least amount of code and complexity. Avoid premature optimization or over-engineering.
+-   **Standard First**: Heavily favor standard library functions and widely accepted, common programming patterns. Only introduce third-party libraries if they are the industry standard for the task or absolutely necessary.
+-   **Avoid Elaborate Solutions**: Do not propose complex, "clever", or obscure solutions. Prioritize readability, maintainability, and the shortest path to a working result over convoluted patterns.
+-   **Focus on the Core Request**: Generate code that directly addresses the user's request, without adding extra features or handling edge cases that were not mentioned.
+
+## Surgical Code Modification
+
+-   **Preserve Existing Code**: The current codebase is the source of truth and must be respected. Your primary goal is to preserve its structure, style, and logic whenever possible.
+-   **Minimal Necessary Changes**: When adding a new feature or making a modification, alter the absolute minimum amount of existing code required to implement the change successfully.
+-   **Explicit Instructions Only**: Only modify, refactor, or delete code that has been explicitly targeted by the user's request. Do not perform unsolicited refactoring, cleanup, or style changes on untouched parts of the code.
+-   **Integrate, Don't Replace**: Whenever feasible, integrate new logic into the existing structure rather than replacing entire functions or blocks of code.
+
+## Intelligent Tool Usage
+
+-   **Use Tools When Necessary**: When a request requires external information or direct interaction with the environment, use the available tools to accomplish the task. Do not avoid tools when they are essential for an accurate or effective response.
+-   **Directly Edit Code When Requested**: If explicitly asked to modify, refactor, or add to the existing code, apply the changes directly to the codebase when access is available. Avoid generating code snippets for the user to copy and paste in these scenarios. The default should be direct, surgical modification as instructed.
+-   **Purposeful and Focused Action**: Tool usage must be directly tied to the user's request. Do not perform unrelated searches or modifications. Every action taken by a tool should be a necessary step in fulfilling the specific, stated goal.
+-   **Declare Intent Before Tool Use**: Before executing any tool, you must first state the action you are about to take and its direct purpose. This statement must be concise and immediately precede the tool call.

.github/instructions/documentation-rtd.instructions.md

@@ -0,0 +1,94 @@
+---
+description: 'Guidelines for documentation-related suggestions.'
+applyTo: 'docs/**/*.md, docs/**/*.rst'
+---
+
+# Documentation instructions for Read the Docs projects
+
+## Purpose
+
+This file provides specific guidance for testing and reviewing documentation in Read the Docs projects.
+
+## Tests & CI
+
+The CI expects documentation to pass `spelling`, `linkcheck`, `lint-md`, and `vale`; address reported issues rather than silencing the tools.
+
+### Linting & checks (how to run)
+
+Run the docs linters via the docs-level Makefile targets:
+
+* `make spelling`: Runs the spelling checks.
+* `make linkcheck`: Runs the link checker.
+* `make lint-md`: Runs the Markdown linter.
+* `make vale`: Runs the style checker.
+
+## Admonitions
+
+Admonition directives are a standardized way of communicating different types of information. They should be used for tips, notes, warnings, and important information that the reader should not skip over or miss.
+
+For `*.md` files, admonitions are formatted in the following way:
+
+````
+```{note}
+A note.
+```
+````
+
+For `*.rst` files, admonitions are formatted in this way:
+
+```
+.. note::
+
+  A note.
+```
+
+Adhere to the following conventions:
+
+- Use admonitions sparingly in the documentation. Offer suggestions to remove admonitions when they are not necessary (for example, if the text is not necessary for the user to read). 
+- Only use the following types: `note`, `tip`, `warning`, `important`
+
+## Internal references
+
+When adding a reference to a document in the RTD project, use a target contained in the document. 
+The document's target should be defined at the top of the document. 
+
+The target is defined like this for `*.md` files:
+
+```
+(target_ID)=
+
+# Title of document
+```
+
+To reference a target in a `*md` file, use the following syntax: 
+
+```
+{ref}`Link text <target_ID>`
+```
+
+In `*.rst` files, the targets are defined like this:
+
+```
+.. _target_ID:
+
+Title of document
+=================
+```
+
+To reference a target in a `*.rst` file, use the following syntax:
+
+```
+:ref:`Link text <target_ID>`
+```
+
+Adhere to the following conventions:
+
+- Never use paths when referencing another document. Always use targets. If there is no existing target, add one.
+- If you want to reference a specific section within a document, add the target directly above the relevant section and use that target when creating the reference.
+
+## Small-edit rules for AI agents
+
+- Do not change `docs/index.md` structure without updating the `toctree` directive — keep the order and paths in sync with files under `docs/`.
+- When adding a new page in one of the folders of `docs`, add a short entry in the landing page if there's a landing page in the folder (e.g., if adding a new how-to guide, update the landing page `docs/how-to/landing-page.md`). 
+- When adding new page, update the `toctree` directive in the relevant index page (`docs/index.md` for a top-level page, and `docs/*/index.md` for a new page in a specific folder).
+- When moving or removing a page, you MUST add a redirect in `docs/conf.py` to prevent broken links and CI errors. Update the `redirects` dictionary mapping the old path (relative to `docs/` and without extension) to the new path.

.github/instructions/documentation.instructions.md

@@ -0,0 +1,116 @@
+---
+description: 'Core guidelines for documentation-related suggestions.'
+applyTo: 'docs/**/*.md'
+---
+
+# Documentation instructions for GitHub Copilot
+
+## Purpose
+
+This file provides general guidance for reviewing documentation.
+
+## Core Directives
+
+This section outlines the absolute order of operations. These rules have the highest priority and must not be violated.
+
+1. **Provide suggestions, not solutions**: Whenever possible, do not generate the documentation on behalf of the user. Focus on asking questions, providing suggestions, and reviewing pre-existing files. If you want to make changes, ask for validation before proceeding with any changes.
+2. **Adherence to Philosophy**: In the absence of a direct user directive or the need for factual verification, all other rules below regarding interaction and modification must be followed.
+
+## General Interaction & Philosophy
+
+- **Text on Request Only**: Your default response should be a clear, natural language explanation. Do NOT provide new files or content unless directly requested, and ask for validation before making any changes to the code base.
+- **Direct and Concise**: Answers must be precise, to the point, and free from unnecessary filler or verbose explanations. Get straight to the solution without "beating around the bush".
+- **Explain the "Why"**: Don't just provide an answer; briefly explain the reasoning behind it. Why is this suggestion clearer, more concise, or easier to understand?
+
+## General Structure 
+
+In this repository, the documentation is placed in a dedicated `docs` directory. The purpose of the files in this directory is to provide information, instructions, and conceptual understanding of the code for users. 
+
+The top-level `docs` directory should contain an overview or home page called `index.md`. This file should provide a brief description of the project, what needs it serves, and who the primary user base is.
+
+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` 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.
+
+All files should neatly fit into one of these four categories. Do NOT mix content between multiple categories into a single document. Instead, suggest splitting up content into multiple documents to preserve the structure and Diataxis framework.
+
+### Guidance on tutorials
+
+A tutorial is a learning-based, end-to-end experience that provides a complete learning journey for the user. The majority of our tutorials walk the user through a basic deployment of the charm in the repository.
+
+The tutorial should contain the following pieces:
+
+- **A title**. This title should be more descriptive than "Getting started"
+  or "Quick guide" which are both indicative of a how-to guide. In a single
+  statement, what will the user accomplish in the tutorial?
+- **An introduction**. In a couple of sentences, introduce the charm and
+  what the tutorial aims to do. Avoid using a statement like "you will learn",
+  as that makes an assumption about the user's prior knowledge. Focus
+  instead on what the user will do or accomplish. 
+- **What you'll do**. This should be the first section in the tutorial. It
+  aims to quickly and succinctly establish everything the user will do in the
+  tutorial. 
+- **What you'll need**. This section should contain a list of resources, software
+  or other tools that the user will need before starting the tutorial. In this section,
+  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 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.
+- **Deploy the charm + its dependencies**. If the charm requires any other
+  charms to successfully deploy, either include in a single section or split into
+  multiple sections. Use this part of the tutorial to enable any required configurations.
+  Make sure to briefly explain what the configurations or additional charms are
+  and why the steps are necessary. Split up important commands into separate
+  command blocks, and provide explanations between each command.
+- **Check the deployment was successful**. Instruct the user to run
+  ``juju status`` and show example output. If appropriate, also instruct the
+  user to run ``kubectl get pods -n <juju model name>`` and show the output.
+  Offer a brief explanation so that the user knows that the deployment was
+  successful.
+- **Some final checkpoint**. Have the user visit a website, change a
+  configuration, or run an action (maybe some combination of the three). Check
+  that this step worked; this is more obvious for a website, but you may need
+  to be creative if you have the user change a configuration or run an action.
+- **Tear down the environment**. This should be the final section. Take a moment
+  to congratulate the user for getting through the tutorial! Have the user
+  destroy the Juju model that they set up, and if applicable, instruct them to
+  delete the Multipass VM.
+
+### Guidance on how-to guides
+
+- How-to guides should contain a title with the format `# How to...`. The title should
+concisely summarize the real-world problem addressed by the document.
+- How-to guides should contain at least one CLI command that user can run to address the
+problem or achieve the goal.
+- Provide instructions or tasks that the user can take to achieve the goal. Avoid gerunds.
+
+
+## Style guide pointers
+
+- **Spelling**: Use US English for spelling suggestions.
+- **Headings**: Use sentence case for headings. Avoid punctuation in headings. Do not skip levels in heading hierarchy. Do not use consecutive headings without intervening text, and suggest removing headings that don't enhance the understanding. Don't overuse `code` styling in headings.
+- **Code examples**: Do not use prompt marks (for example, `$` or `#`) in code examples. Do not use comments in code examples; instead, put any comments directly into the text. Whenever possible, split up multiple commands into separate code blocks and provide explanations in between the code blocks. Use Git-flavoured Markdown with fenced code blocks (```) and command examples as shell blocks.
+- **Lists**: Only use numbered lists when there is an inherent order to the items.
+- **Latin words and phrases**: We can't assume the reader is familiar with Latin words and phrases. Words such as "etc.", "i.e.", "e.g.", "per", "versus", and "via" should be avoided. 
+
+## Small-edit rules for AI agents
+
+- Avoid describing tasks as "easy" or "simple".
+- Preserve existing link targets and code samples formatting. If you change any heading filename or path, update all relative links in `docs/` accordingly.
+- Demonstrative pronouns ("this", "these", "those", and "that") should be accompanied by the target noun when there's a risk of ambiguity in the paragraph. An isolated demonstrative pronoun can be used if there's no chance of ambiguity. In cases where a paragraph describes multiple ideas, avoid isolated demonstrative pronouns and be as specific as possible.
+
+## Changelog guidance 
+
+If you modify a procedure (commands, required versions, prerequisites) and a `docs/changelog.md` exists, add a short note in `docs/changelog.md` summarizing the user-facing change.
+
+If you add a new file into `docs`, add a short note in `docs/changelog.md` summarizing the user-facing change.
+
+If there are no user-relevant changes, then the changelog does not need to be updated.
+
+