ai: initial commit for agentic files for GH Copilot

.github/copilot-instructions.md

@@ -0,0 +1,237 @@
+# Kernel Team Internal Documentation - Copilot Instructions
+
+## Project Overview
+
+This is the **Kernel team's internal documentation** - a Sphinx-based documentation project using the [Canonical Sphinx Stack](https://github.com/canonical/sphinx-stack).
+Documentation targets the kernel team's documentation processes, standards, and best practices for maintaining the Ubuntu kernels.
+
+### Repository scope
+
+This is a docs-only repository.
+It contains documentation content and documentation tooling only.
+There is no product runtime or application source code in scope for behavior verification.
+
+When verifying documentation accuracy, treat repository artifacts as the source of truth:
+`docs/conf.py`, `docs/Makefile` targets, Sphinx configuration, examples, redirects,
+and consistency across documentation pages.
+
+## Architecture & Structure
+
+### Diátaxis Framework
+
+Content is organized using the [Diátaxis framework](https://diataxis.fr/):
+
+- `tutorial/` - Getting started guides (for example, `crank-your-first-kernel.md`).
+- `how-to/` - Task-oriented guides organized by topic or stages of kernel development (for example, stable updates, testing, and development).
+- `explanation/` - Conceptual overviews and background information.
+- `reference/` - Technical specifications, glossaries, and system requirements.
+
+### File Types
+
+- **Markdown (`.md`)** - Primary format for content pages with MyST syntax support.
+- **reStructuredText (`.rst`)** - Landing pages, index files, and content pages.
+- Mixed content: both formats coexist and are processed by Sphinx.
+
+### Repository layout
+
+- `docs/` - Documentation root.
+- `docs/tutorial/` - Tutorials and onboarding guides.
+- `docs/how-to/` - Task-oriented operational guides.
+- `docs/explanation/` - Conceptual and background documentation.
+- `docs/reference/` - Specifications, glossary entries, and reference material.
+- `docs/reuse/` - Shared links and reusable documentation snippets.
+- `docs/conf.py` - Sphinx project configuration, including redirects.
+- `docs/Makefile` - Documentation build, test, and local serve targets.
+
+### Key Configuration Files
+
+- `docs/conf.py` - Project-specific settings.
+- `docs/Makefile` - Build system.
+- `docs/.readthedocs.yaml` - Read the Docs build configuration.
+
+## Development Workflow
+
+### Local Setup
+
+```bash
+git clone https://github.com/canonical/kernel-docs.git
+cd kernel-docs/docs
+sudo apt update
+sudo apt install make python3 python3-venv python3-pip
+make install
+```
+
+### Build & Preview
+
+```bash
+make run          # Build, watch, and serve at http://127.0.0.1:8000
+make html         # Build only
+make serve        # Serve only
+make clean-doc    # Clean built files
+```
+
+For remote/VM development, set `export SPHINX_HOST=0.0.0.0` before running `make run`.
+
+### Testing & Quality Checks
+
+```bash
+make spelling     # Spell check (uses .custom_wordlist.txt for exceptions)
+make linkcheck    # Verify all links
+make lint-md      # Check Markdown formatting and MyST syntax
+make vale         # Check style guide compliance (Canonical Vale rules)
+make html         # Build docs and surface Sphinx warnings/errors
+make woke         # Check inclusive language
+make pa11y        # Accessibility testing
+```
+
+During development, run the checks that match the files you changed.
+Before submitting a PR, always run `make spelling`, `make linkcheck`, `make lint-md`, `make vale`, and `make html`.
+
+## Writing Conventions
+
+### Style & Language
+
+- Follow the [Canonical documentation style guide](https://docs.ubuntu.com/styleguide/en).
+- Use **US English** (`en-US`).
+- Acronyms: expand on first use, for example, "Yet Another Markup Language (YAML)."
+- Add technical terms to `docs/reference/glossary.md` and spell exceptions to `docs/.custom_wordlist.txt`.
+
+### Cross-References
+
+- Prefix all labels with the Diátaxis section to avoid clashes across pages.
+  - Recommended short prefixes: `tutorial-*`, `how-to-*`, `exp-*`, `ref-*`.
+- In `.rst` files, define labels with section-prefixed names:
+  - `.. _how-to-label:`
+- In `.rst` files, link with `:ref:\`label-name\`` and `:doc:\`/path/to/page\`` for internal pages.
+- In `.md` (MyST) files, define labels near the top of the page with section-prefixed names:
+  - `(how-to-label)=`
+- In `.md` (MyST) files, use `{ref}` for labels and `{doc}` for internal page links.
+- Prefer native internal cross-references (`:ref:`, `:doc:`, `{ref}`, `{doc}`) over plain relative links so broken links surface during `make run` and `make html`.
+- First mentions of packages and tools should link to official documentation or manpages.
+- Use semantic markup: `{kbd}\`Ctrl\``, `{manpage}\`dpkg(1)\``, `{term}\`DAC\``.
+- Manpage links auto-generate URLs (no hardcoding needed).
+
+### Formatting Rules
+
+- Blank line required after every heading before content.
+- Blank line required before every list (bullet or numbered).
+- Use sentence case for headings, not title case.
+- Active voice preferred: "This command does X" not "X is done by this command".
+- In `.md` files, use MyST admonition syntax: `` ```{note} ``, `` ```{warning} ``, `` ```{important} ``.
+- In `.rst` files, use RST admonition syntax: `.. note::`, `.. warning::`, `.. important::`.
+
+### Markdown Elements
+
+- **Headings**: Use proper hierarchy (`#`, `##`, `###`, `####`); don't skip levels.
+- **Lists**: Use `1.` for all numbered items (auto-renumbers).
+- **Code blocks**: Specify language for syntax highlighting.
+- **MyST extensions**: `attrs_block`, `attrs_inline`, `colon_fence`, `deflist`, `substitution`.
+
+### File Structure
+
+- Content pages are referenced once via their section landing page.
+- Landing pages in `docs/how-to/`, `docs/tutorial/`, and related sections organize navigation.
+- Images are stored in `docs/<section>/images/` directories.
+- Shared links are defined in `docs/reuse/links.txt` and auto-included via `rst_epilog`.
+
+## Critical Patterns
+
+### Redirects
+
+When renaming/moving/deleting files, **always add redirects**:
+
+**Add redirects in `docs/conf.py` under `redirects = {}`**:
+
+```python
+redirects = {
+  # Internal redirect (full docs path)
+  "how-to/old-page": "how-to/new-page",
+  # External redirect (full URL)
+  "how-to/obsolete-page": "https://example.com/new-location",
+}
+```
+
+### Custom Wordlist
+
+Add valid technical terms/acronyms to `docs/.custom_wordlist.txt` (alphabetically sorted) rather than wrapping in backticks, unless you want monospaced rendering.
+
+### PR Requirements
+
+- Link PRs to issues with `Fixes #<issue-number>` in the description.
+- Use [Conventional Comments](https://conventionalcomments.org/) for feedback.
+- Include manual testing for documentation workflows and commands.
+- Preview builds are available via the Read the Docs check on the PR.
+
+## Common Tasks
+
+### Meta Description Format
+
+All pages must have an HTML meta description. The format depends on file type:
+
+**MyST Markdown** (`.md`): Add to the front matter at the top of the file:
+
+```yaml
+---
+myst:
+  html_meta:
+    description: "Brief, user-facing description of the page content (50-160 characters)."
+---
+```
+
+**reStructuredText** (`.rst`): Add as a directive at the top of the file before the first heading:
+
+```rst
+.. meta::
+   :description: Brief, user-facing description of the page content (50-160 characters).
+```
+
+Metadata descriptions help with search results and accessibility. Keep them concise and action-oriented.
+
+### Adding New Content
+
+1. Determine Diátaxis category (tutorial/how-to/explanation/reference)
+2. Create `.md` / `.rst` file in appropriate subdirectory
+3. Add or review the page meta description (see [Meta Description Format](#meta-description-format) above):
+
+  - New files: must include a meta description
+  - Existing files: add one if missing, otherwise review and update it if it no longer matches the page intent
+
+4. Add to corresponding `index.rst` / `index.md` or section landing page
+5. Use section-prefixed labels / targets for cross-references in both MyST and RST
+   For example `(how-to-topic-name)=` in MyST or `.. _how-to-topic-name:` in RST
+6. Test: `make run` and verify navigation, formatting, and cross-references work as expected
+7. Run quality checks before committing:
+
+  ```bash
+  make spelling
+  make linkcheck
+  make lint-md
+  make vale
+  make html
+  ```
+
+  Fix any warnings or errors reported by these commands.
+8. Submit PR with clear description and link to any related issues
+
+Use short section prefixes for anchors when naming labels, for example `tutorial-*`, `how-to-*`, `exp-*`, and `ref-*`.
+
+### Updating Links
+
+- Prefer reputable sources (official upstream documentation, not blog posts).
+- Use "Related topics" sections for supplementary links at the end of the page.
+- The first package mention should link to documentation or manpages.
+
+### Handling Errors
+
+- **Spelling errors**: Add to `docs/.custom_wordlist.txt` or wrap in backticks.
+- **Link errors**: Check `linkcheck_ignore` in `docs/conf.py`.
+- **Build errors**: Check `docs/.sphinx/venv/pip_install.log` for dependency issues.
+- **Sphinx warnings**: Run `make html` and resolve missing references, syntax issues, and other warnings before merge.
+
+## Don't Do This
+
+- Don't use emojis in documentation.
+- Don't skip heading levels in document structure.
+- Don't assume reader knowledge without brief explanations or links.
+- Don't link to blog posts when official docs exist.
+- Don't treat this repository as a mixed code-and-docs project.

.github/skills/documentation-build/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: documentation-build
+description: "Validates documentation builds successfully. Use when checking Sphinx/RTD build integrity or diagnosing build failures. Reports errors, warnings, and build configuration issues."
+---
+
+# Documentation Build Validation
+
+## Scope
+
+Build validation only: detect documentation build configuration, run applicable build targets, collect all errors and warnings, and categorize by severity.
+
+## Inputs
+
+- Repository root.
+
+## Actions
+
+1. **Identify documentation root**: Detect docs roots in this order:
+
+   - `docs/`
+   - Repository root, when both `conf.py` and `Makefile` exist
+   - `doc/`
+   - `documentation/`
+   - `site/`
+   - `docs-src/`
+
+   If still not found, perform a bounded search for `conf.py` (max depth 4) and use its parent as the docs root.
+
+2. **Detect build configuration**: Check for the presence of:
+
+   - `conf.py` in the detected docs root
+   - `Makefile` in the detected docs root
+   - Optional: `.readthedocs.yaml` in the detected docs root or at repository root
+
+   If Sphinx build artifacts are absent in the target repository, report "not applicable" in findings and exit cleanly.
+
+3. **Run build targets** (when applicable):
+
+   ```bash
+   cd <docs_root>
+   # Use clean-doc when available, otherwise fall back to clean
+   if make -n clean-doc 2>/dev/null; then
+     make clean-doc
+   else
+     make clean
+   fi
+   make html
+   ```
+
+   Run additional checks for targets that exist.
+   Check each target before running to avoid false failures:
+
+   ```bash
+   # Check and run each target if available
+    for target in spelling linkcheck lint-md vale woke pa11y; do
+     if make -n $target 2>/dev/null; then
+       make $target
+     fi
+   done
+   ```
+
+4. **Capture output and handle failures**: If any command fails:
+
+   1. Capture the full error output from stderr and stdout
+   2. Run `make clean-doc` (or `make clean` if `clean-doc` is unavailable) to reset build state
+   3. Retry the failed build command once
+   4. If retry fails, STOP and report all captured errors
+   5. Do not proceed to content analysis until build succeeds
+
+   Warnings must be collected and reported, but are not blocking unless the repository explicitly treats warnings as errors.
+
+5. **Categorize findings by severity**:
+
+   - **Errors**: Build failures, broken links, missing files.
+   - **Warnings**: Deprecation notices, missing references, formatting issues.
+   - **Info**: Suggestions, minor notices.
+
+6. **Verify completion**: Confirm the validation completed:
+
+   - Build targets were executed (or determined not applicable)
+   - Output was captured (errors and warnings)
+   - Findings were categorized by severity
+
+   State the completion status:
+   - `✓ Build validation complete: [N] errors, [M] warnings found`
+   - OR `✓ Build validation complete: No issues found`
+   - OR `✓ Build validation: Not applicable - Sphinx artifacts not detected`
+
+## Constraints
+
+- Do not approve documentation that fails the Sphinx build.
+- Build docs locally to catch build warnings.
+- Do not invent Makefile targets; only use targets confirmed to exist in the target repository.
+
+## Output
+
+A build validation report listing all errors and warnings, categorized by severity.
+If Sphinx artifacts are not detected, report "Not applicable -- Sphinx artifacts not detected in target repo".