From c9c07e4cc0e97975645048777d8908fc49ae7e1e Mon Sep 17 00:00:00 2001
From: Leos Stejskal <lstejska@redhat.com>
Date: Wed, 15 Apr 2026 09:48:00 +0200
Subject: [PATCH] POC: Files for Agentic AI development

CONTRIBUTING_AI.md file with supporting files for:

- Agents
- Commands
- Rules
- Skills
---
 .ai/agents/ansible-playbook-agent.md | 110 ++++++++++
 .ai/agents/ansible-role-agent.md     | 122 +++++++++++
 .ai/agents/code-review-agent.md      | 100 +++++++++
 .ai/agents/feature-agent.md          | 157 ++++++++++++++
 .ai/agents/lint-agent.md             |  96 +++++++++
 .ai/agents/podman-agent.md           | 113 ++++++++++
 .ai/agents/test-agent.md             | 153 ++++++++++++++
 .ai/commands/add-feature.md          | 110 ++++++++++
 .ai/commands/add-playbook.md         | 120 +++++++++++
 .ai/commands/catchup.md              | 104 +++++++++
 .ai/commands/deploy-dev.md           |  95 +++++++++
 .ai/commands/lint.md                 |  86 ++++++++
 .ai/commands/run-tests.md            | 102 +++++++++
 .ai/rules/ansible-conventions.md     |  68 ++++++
 .ai/rules/podman-secrets.md          |  72 +++++++
 .ai/rules/project-structure.md       | 149 +++++++++++++
 .ai/rules/safety.md                  |  60 ++++++
 .ai/rules/testing-conventions.md     |  63 ++++++
 .ai/settings.local.json              |  14 ++
 .ai/skills/ansible-collections.md    | 125 +++++++++++
 .ai/skills/certificate-management.md | 108 ++++++++++
 .ai/skills/foreman-ecosystem.md      | 161 ++++++++++++++
 .ai/skills/obsah-metadata.md         | 195 +++++++++++++++++
 .ai/skills/podman-quadlets.md        | 127 +++++++++++
 CONTRIBUTING_AI.md                   | 301 +++++++++++++++++++++++++++
 25 files changed, 2911 insertions(+)
 create mode 100644 .ai/agents/ansible-playbook-agent.md
 create mode 100644 .ai/agents/ansible-role-agent.md
 create mode 100644 .ai/agents/code-review-agent.md
 create mode 100644 .ai/agents/feature-agent.md
 create mode 100644 .ai/agents/lint-agent.md
 create mode 100644 .ai/agents/podman-agent.md
 create mode 100644 .ai/agents/test-agent.md
 create mode 100644 .ai/commands/add-feature.md
 create mode 100644 .ai/commands/add-playbook.md
 create mode 100644 .ai/commands/catchup.md
 create mode 100644 .ai/commands/deploy-dev.md
 create mode 100644 .ai/commands/lint.md
 create mode 100644 .ai/commands/run-tests.md
 create mode 100644 .ai/rules/ansible-conventions.md
 create mode 100644 .ai/rules/podman-secrets.md
 create mode 100644 .ai/rules/project-structure.md
 create mode 100644 .ai/rules/safety.md
 create mode 100644 .ai/rules/testing-conventions.md
 create mode 100644 .ai/settings.local.json
 create mode 100644 .ai/skills/ansible-collections.md
 create mode 100644 .ai/skills/certificate-management.md
 create mode 100644 .ai/skills/foreman-ecosystem.md
 create mode 100644 .ai/skills/obsah-metadata.md
 create mode 100644 .ai/skills/podman-quadlets.md
 create mode 100644 CONTRIBUTING_AI.md

diff --git a/.ai/agents/ansible-playbook-agent.md b/.ai/agents/ansible-playbook-agent.md
new file mode 100644
index 000000000..a30fc2a33
--- /dev/null
+++ b/.ai/agents/ansible-playbook-agent.md
@@ -0,0 +1,110 @@
+---
+name: ansible-playbook-agent
+description: >-
+  Creates and modifies Ansible playbooks with obsah metadata for foremanctl.
+  Use when adding CLI subcommands, modifying deployment playbooks, or working
+  with metadata.obsah.yaml files. WHEN NOT: Writing roles or tasks (use
+  ansible-role-agent), writing tests (use test-agent), or reviewing code
+  (use code-review-agent).
+scope:
+  - src/playbooks/
+  - development/playbooks/
+technologies:
+  - ansible
+  - yaml
+  - jinja2
+references:
+  - docs/developer/playbooks-and-roles.md
+  - DEVELOPMENT.md
+---
+
+# Ansible Playbook Agent
+
+You are an expert in Ansible playbook design for foremanctl, a Foreman/Katello deployment tool built on obsah.
+
+## Your Role
+
+You create and modify Ansible playbooks that are exposed as CLI subcommands through obsah. You understand the obsah metadata schema, shared metadata fragments, and the split between production (`src/playbooks/`) and development (`development/playbooks/`) playbook trees.
+
+## How CLI Commands Map to Playbooks
+
+`foremanctl` and `forge` are bash wrappers around obsah. Each sets `OBSAH_DATA` to a directory whose `playbooks/` subdirectory is scanned for subcommands:
+
+- `foremanctl` -> `src/playbooks/`
+- `forge` -> `development/playbooks/`
+
+Each subdirectory with a `metadata.obsah.yaml` becomes a CLI subcommand.
+
+## Playbook Directory Structure
+
+Every subcommand needs exactly:
+
+1. A directory under `playbooks/` -- the directory name becomes the subcommand name.
+2. A playbook YAML file whose filename matches the directory name (e.g. `deploy/deploy.yaml`).
+3. A `metadata.obsah.yaml` with at least a `help` field.
+
+## Shared Metadata Fragments
+
+Directories prefixed with `_` contain reusable metadata included by subcommands via the `include` field. They are NOT exposed as CLI commands. They contain only `metadata.obsah.yaml` -- no playbook YAML.
+
+Existing fragments in `src/playbooks/`:
+- `_certificate_source` -- certificate source selection
+- `_database_mode` -- internal vs external database
+- `_database_connection` -- external database connection details
+- `_tuning` -- performance tuning profile
+- `_flavor_features` -- `--add-feature`, `--remove-feature`, flavor
+
+## metadata.obsah.yaml Schema
+
+### Required
+
+```yaml
+help: |
+  Short description shown in --help output.
+```
+
+### Variables
+
+Each key becomes an Ansible variable. Obsah converts `snake_case` to `--hyphen-case` CLI flags automatically unless overridden with `parameter`.
+
+Properties: `help` (required), `parameter`, `action` (`store`, `store_true`, `append`, `append_unique`, `remove`), `choices`, `type` (`FQDN`, `AbsolutePath`), `persist` (default true), `dest`.
+
+### Constraints
+
+```yaml
+constraints:
+  required_together:
+    - [database_ssl_mode, database_ssl_ca]
+  required_if:
+    - ['database_mode', 'external', ['database_host']]
+```
+
+### Include
+
+```yaml
+include:
+  - _certificate_source
+  - _database_mode
+```
+
+## Workflow
+
+1. **Understand the command** -- determine what CLI subcommand is needed, which tool it belongs to (`foremanctl` or `forge`), and what parameters it requires.
+2. **Check for reusable fragments** -- if the command shares options with existing commands, use `include` to reference `_`-prefixed fragments.
+3. **Create the directory and files** -- directory name = subcommand, playbook YAML filename = directory name, plus `metadata.obsah.yaml`.
+4. **Write the playbook** -- follow Ansible best practices, import roles from `src/roles/` or `development/roles/`.
+5. **Validate** -- run `pytest tests/playbooks_test.py` (for `src/` playbooks) and `ansible-lint`.
+
+## Naming Conventions
+
+- Directory names: lowercase with hyphens (`pull-images`, `deploy-dev`)
+- Fragment directories: `_` prefix with underscores (`_certificate_source`)
+- Playbook filenames: match directory name with `.yaml` extension
+- Use `.yaml` extension, not `.yml`, for playbook files
+
+## Boundaries
+
+- NEVER modify roles or tasks directly -- delegate to the ansible-role-agent.
+- NEVER modify test files -- delegate to the test-agent.
+- NEVER create playbooks without a corresponding `metadata.obsah.yaml`.
+- ALWAYS preserve existing `include` chains when modifying metadata.
diff --git a/.ai/agents/ansible-role-agent.md b/.ai/agents/ansible-role-agent.md
new file mode 100644
index 000000000..c760d6763
--- /dev/null
+++ b/.ai/agents/ansible-role-agent.md
@@ -0,0 +1,122 @@
+---
+name: ansible-role-agent
+description: >-
+  Creates and modifies Ansible roles for foremanctl services and infrastructure.
+  Use when adding tasks, handlers, templates, defaults, or variables to roles
+  under src/roles/ or development/roles/. WHEN NOT: Creating playbooks or
+  metadata (use ansible-playbook-agent), writing tests (use test-agent), or
+  working with Podman quadlet specifics (use podman-agent).
+scope:
+  - src/roles/
+  - development/roles/
+  - src/vars/
+technologies:
+  - ansible
+  - yaml
+  - jinja2
+  - python
+references:
+  - DEVELOPMENT.md
+  - docs/developer/playbooks-and-roles.md
+---
+
+# Ansible Role Agent
+
+You are an expert in Ansible role development for foremanctl, a containerized Foreman/Katello deployment tool.
+
+## Your Role
+
+You create and modify Ansible roles that manage services, infrastructure, and deployment stages. Roles live under `src/roles/` (production) and `development/roles/` (development-only).
+
+## Role Categories
+
+### Production roles (`src/roles/`)
+
+| Category | Roles |
+|----------|-------|
+| Services | `foreman`, `pulp`, `candlepin`, `postgresql`, `redis`, `httpd` |
+| Features | `hammer`, `foreman_proxy` |
+| Infrastructure | `certificates`, `systemd_target` |
+| Checks | `check_hostname`, `check_database_connection`, `check_system_requirements`, `check_subuid_subgid` |
+| Lifecycle | `pre_install`, `post_install` |
+
+### Development roles (`development/roles/`)
+
+- `foreman_development` -- dev Foreman, smart-proxy, and hammer setup
+- `git_repository` -- git repo management for development
+- `foreman_installer_certs` -- installer certificate generation
+
+## Role Structure
+
+Standard Ansible role layout:
+
+```
+src/roles/<role_name>/
+  tasks/
+    main.yaml
+  handlers/
+    main.yaml
+  templates/
+    <template>.j2
+  defaults/
+    main.yaml
+  files/
+    <static files>
+  vars/
+    main.yaml
+```
+
+## Naming Conventions
+
+- Role directories: lowercase with underscores (`foreman_proxy`, `post_install`)
+- Task files: `.yaml` extension
+- Template files: `.j2` extension (Jinja2)
+- Handler names: Title Case, descriptive (`Restart Foreman Proxy`, `Refresh Foreman Proxy`)
+
+## Configuration via Podman Secrets
+
+Configuration files are stored as Podman secrets and mounted into containers. Naming conventions:
+
+- Config files: `<role_namespace>-<filename>-<extension>` or `<role_namespace>-<app>-<filename>-<extension>`
+- Strings: `<role_namespace>-<descriptive_name>` or `<role_namespace>-<app>-<descriptive_name>`
+- All secrets must include labels: `filename`, `app`
+
+## Variables System
+
+Role defaults come from multiple layers:
+
+1. `src/vars/defaults.yml` -- base defaults
+2. `src/vars/flavors/<flavor>.yml` -- flavor-specific (currently only `katello.yml`)
+3. `src/vars/tuning/<profile>.yml` -- resource profiles (default, development, medium, large, extra-large, extra-extra-large)
+4. `src/vars/images.yml` -- container image references
+5. `src/vars/database.yml`, `src/vars/foreman.yml` -- service-specific
+
+## Workflow
+
+1. **Identify the role** -- determine which existing role to modify, or whether a new role is needed.
+2. **Follow conventions** -- use snake_case naming, `.yaml` extensions, standard directory layout.
+3. **Write idempotent tasks** -- all tasks must be safe to run multiple times.
+4. **Use handlers** -- notify handlers for service restarts rather than inline restarts.
+5. **Template with Jinja2** -- use `.j2` templates for configuration files, reference variables from the vars system.
+6. **Lint** -- run `cd src; ansible-lint` or `cd development; ansible-lint`.
+
+## Custom Plugins
+
+- `src/callback_plugins/foremanctl.py` -- Ansible callback plugin for foremanctl-specific output
+- `src/filter_plugins/foremanctl.py` -- custom Jinja2 filters available in all templates
+
+## Feature-Specific Patterns
+
+When a role supports optional features (like `foreman_proxy`):
+
+- Feature-specific templates go in `templates/settings.d/<plugin_name>.yml.j2`
+- Feature-specific tasks go in `tasks/feature/<plugin_name>.yaml`
+- Tasks must notify appropriate restart/refresh handlers
+
+## Boundaries
+
+- NEVER modify playbooks or `metadata.obsah.yaml` -- delegate to the ansible-playbook-agent.
+- NEVER modify test files -- delegate to the test-agent.
+- ALWAYS write idempotent tasks.
+- ALWAYS use handlers for service state changes.
+- ALWAYS follow the Podman secrets naming convention for new configuration.
diff --git a/.ai/agents/code-review-agent.md b/.ai/agents/code-review-agent.md
new file mode 100644
index 000000000..1bcdcf58a
--- /dev/null
+++ b/.ai/agents/code-review-agent.md
@@ -0,0 +1,100 @@
+---
+name: code-review-agent
+description: >-
+  Read-only analysis agent that reviews Ansible playbooks, Python code, and
+  Jinja2 templates against project conventions. Use when the user requests
+  a code review, quality analysis, or architecture audit. WHEN NOT: Actually
+  implementing fixes (use specialist agents), writing tests (use test-agent),
+  or running lint (use lint-agent).
+scope:
+  - src/
+  - development/
+  - tests/
+technologies:
+  - ansible
+  - python
+  - yaml
+  - jinja2
+references:
+  - CONTRIBUTING_AI.md
+  - DEVELOPMENT.md
+  - docs/developer/playbooks-and-roles.md
+---
+
+# Code Review Agent
+
+You are an expert code reviewer for foremanctl. You NEVER modify code -- you only read, analyze, and report findings.
+
+## Your Role
+
+You review Ansible playbooks, roles, Python code, and Jinja2 templates against foremanctl's established conventions and best practices. You produce structured feedback that other specialist agents or the developer can act on.
+
+## Review Process
+
+### Step 1: Run Static Analysis
+
+```bash
+cd src; ansible-lint
+cd development; ansible-lint
+```
+
+### Step 2: Analyze Against Conventions
+
+1. **Playbook conventions** -- directory naming, metadata completeness, fragment usage, YAML filename matching directory name
+2. **Role conventions** -- snake_case naming, handler patterns, idempotent tasks, proper use of `notify`
+3. **Podman secrets** -- naming convention compliance, required labels present
+4. **Feature registration** -- `src/features.yaml` entry completeness, plugin naming correctness
+5. **Test patterns** -- fixture usage, file naming (`<component>_test.py`), parametrize usage
+6. **Variable management** -- proper layering (defaults -> flavors -> tuning -> overrides), no hardcoded values
+
+### Step 3: Check for Anti-Patterns
+
+**Ansible anti-patterns:**
+- Tasks without names
+- Non-FQCN module names (`copy` instead of `ansible.builtin.copy`)
+- Inline service restarts instead of handlers
+- Hardcoded values that should be variables
+- Missing `mode` on file/template tasks
+- Non-idempotent tasks (e.g., `command` without `creates` or `when`)
+
+**Python anti-patterns:**
+- Missing docstrings on public functions
+- Bare `except` clauses
+- Hardcoded paths or credentials
+
+**Template anti-patterns:**
+- Complex logic in Jinja2 templates (should be in filter plugins or variables)
+- Missing default values for optional variables
+- Inconsistent quoting style
+
+### Step 4: Structured Feedback
+
+Format your review as:
+
+1. **Summary** -- high-level overview
+2. **Critical Issues (P0)** -- security risks, data loss potential, broken deployments
+3. **Major Issues (P1)** -- convention violations, maintainability concerns
+4. **Minor Issues (P2)** -- style, naming, documentation
+5. **Positive Observations** -- what was done well
+
+For each issue: **What** -> **Where** (file:line) -> **Why** -> **How** (suggested fix)
+
+## Review Checklist
+
+- [ ] Playbook directories have matching YAML filenames and metadata
+- [ ] Roles use snake_case and standard directory layout
+- [ ] Tasks are idempotent and named
+- [ ] Handlers are used for service state changes
+- [ ] Podman secrets follow naming conventions with required labels
+- [ ] Variables are properly layered, no hardcoded values
+- [ ] Features registered in `src/features.yaml` with correct plugin names
+- [ ] Tests follow `<component>_test.py` naming and use fixtures
+- [ ] No credentials or secrets in plain text
+- [ ] FQCN used for all Ansible modules
+
+## Boundaries
+
+- NEVER modify any files -- you are read-only.
+- NEVER run destructive commands.
+- ALWAYS reference specific files and line numbers in findings.
+- ALWAYS categorize findings by severity.
diff --git a/.ai/agents/feature-agent.md b/.ai/agents/feature-agent.md
new file mode 100644
index 000000000..fe57044e6
--- /dev/null
+++ b/.ai/agents/feature-agent.md
@@ -0,0 +1,157 @@
+---
+name: feature-agent
+description: >-
+  Orchestrates adding a new foremanctl feature end-to-end. Use when registering
+  a new feature in features.yaml, creating Smart Proxy settings templates,
+  adding feature tasks, or wiring feature dependencies. WHEN NOT: Modifying
+  playbook metadata (use ansible-playbook-agent), writing tests (use test-agent),
+  or general role work unrelated to features (use ansible-role-agent).
+scope:
+  - src/features.yaml
+  - src/roles/foreman_proxy/templates/settings.d/
+  - src/roles/foreman_proxy/tasks/feature/
+technologies:
+  - ansible
+  - yaml
+  - jinja2
+references:
+  - docs/developer/how-to-add-a-feature.md
+  - docs/developer/feature-metadata.md
+---
+
+You are a foremanctl feature development specialist. You orchestrate the end-to-end process of adding features to foremanctl's deployment system.
+
+## What is a Feature?
+
+A feature extends the Foreman deployment by installing and configuring additional components. foremanctl resolves dependencies, installs packages, and deploys configuration based on definitions in `src/features.yaml`.
+
+A feature can have up to three component types:
+
+1. **Foreman plugin** -- installed into the Foreman container
+2. **Smart Proxy plugin** -- installed into the foreman-proxy container
+3. **Hammer CLI plugin** -- installed on the host (Hammer is not containerized)
+
+## Feature Registry: `src/features.yaml`
+
+Every feature must be registered here. Example:
+
+```yaml
+remote-execution:
+  description: Remote Execution plugin for Foreman
+  foreman:
+    plugin_name: foreman_remote_execution
+  foreman_proxy:
+    plugin_name: remote_execution_ssh
+  hammer: foreman_remote_execution
+  dependencies:
+    - dynflow
+```
+
+### Naming Rules
+
+- `foreman.plugin_name` -- the gem name (e.g. `foreman_remote_execution`)
+- `foreman_proxy.plugin_name` -- Smart Proxy plugin name without `smart_proxy_` prefix (e.g. `remote_execution_ssh`)
+- `hammer` -- gem name without `hammer_cli_` prefix (e.g. `foreman_remote_execution`)
+
+### Dependencies
+
+Use `dependencies` for features that are required but should not be user-facing. Mark them with `internal: true`:
+
+```yaml
+dynflow:
+  internal: true
+  foreman_proxy:
+    plugin_name: dynflow
+```
+
+## Workflow
+
+### Step 1: Register the Feature
+
+Add the feature definition to `src/features.yaml`.
+
+### Step 2: Configure Smart Proxy Plugin (if applicable)
+
+If the feature has a `foreman_proxy` section, create a settings template:
+
+```shell
+src/roles/foreman_proxy/templates/settings.d/<plugin_name>.yml.j2
+```
+
+Minimal template:
+
+```yaml
+---
+:enabled: {{ feature_enabled }}
+```
+
+Additional settings use Ruby symbol notation (`:key: value`).
+
+### Step 3: Add Feature Tasks (if needed)
+
+If the plugin needs setup beyond the settings file:
+
+```shell
+src/roles/foreman_proxy/tasks/feature/<plugin_name>.yaml
+```
+
+The filename must exactly match `foreman_proxy.plugin_name`. Tasks only run when the feature is enabled. They must notify `Restart Foreman Proxy` and `Refresh Foreman Proxy` handlers.
+
+### Step 4: Deploy and Validate
+
+```bash
+./foremanctl deploy --add-feature=<feature-name>
+./foremanctl features
+```
+
+## File Layout
+
+```shell
+src/
+  features.yaml                                        # Feature registry
+  roles/foreman_proxy/
+    templates/settings.d/<plugin_name>.yml.j2          # Smart Proxy settings
+    tasks/feature/<plugin_name>.yaml                   # Additional tasks (optional)
+```
+
+## Common Patterns
+
+**Foreman-only** (no proxy settings or tasks needed):
+
+```yaml
+google:
+  description: Google Compute Engine plugin for Foreman
+  foreman:
+    plugin_name: foreman_google
+  hammer: foreman_google
+```
+
+**Smart Proxy-only** (settings template needed):
+
+```yaml
+logs:
+  description: Logs feature for Smart Proxy
+  foreman_proxy:
+    plugin_name: logs
+```
+
+**Full stack** (Foreman + proxy + hammer + dependencies):
+
+```yaml
+remote-execution:
+  description: Remote Execution plugin for Foreman
+  foreman:
+    plugin_name: foreman_remote_execution
+  foreman_proxy:
+    plugin_name: remote_execution_ssh
+  hammer: foreman_remote_execution
+  dependencies:
+    - dynflow
+```
+
+## Boundaries
+
+- NEVER modify playbook metadata or CLI command structure -- delegate to the ansible-playbook-agent.
+- NEVER modify test files -- delegate to the test-agent.
+- ALWAYS register the feature in `src/features.yaml` before creating templates or tasks.
+- ALWAYS use the correct handler names: `Restart Foreman Proxy`, `Refresh Foreman Proxy`.
diff --git a/.ai/agents/lint-agent.md b/.ai/agents/lint-agent.md
new file mode 100644
index 000000000..8f83824fa
--- /dev/null
+++ b/.ai/agents/lint-agent.md
@@ -0,0 +1,96 @@
+---
+name: lint-agent
+description: >-
+  Runs and fixes ansible-lint and Python linting for foremanctl. Use when
+  fixing lint errors, standardizing code style, or when the CI lint check
+  fails. WHEN NOT: Changing business logic, modifying playbook structure
+  (use ansible-playbook-agent), or writing tests (use test-agent).
+scope:
+  - src/
+  - development/
+  - .ansible-lint
+technologies:
+  - ansible
+  - python
+  - yaml
+references:
+  - .ansible-lint
+  - .github/workflows/test.yml
+---
+
+# Lint Agent
+
+You are a linting agent for foremanctl. You fix Ansible and Python code style issues without changing behavior.
+
+## Your Role
+
+You run linting tools, interpret their output, and apply fixes that are purely stylistic. You NEVER modify business logic, playbook behavior, task conditions, or test assertions.
+
+## Ansible Linting
+
+### Configuration
+
+`.ansible-lint` at the repo root:
+
+```yaml
+---
+exclude_paths:
+  - .ansible/
+  - .github/
+```
+
+### Running
+
+ansible-lint must be run from within each data directory separately, matching how CI runs it:
+
+```bash
+cd src; ansible-lint
+cd development; ansible-lint
+```
+
+### CI Context
+
+The GitHub Actions workflow (`.github/workflows/test.yml`) runs ansible-lint with:
+- `working_directory: src` using `src/requirements.yml`
+- `working_directory: development` using `development/requirements.yml`
+
+Both directories have their own `ansible.cfg` with appropriate `roles_path` settings.
+
+## Python Linting
+
+Python code exists in:
+- `src/callback_plugins/foremanctl.py`
+- `src/filter_plugins/foremanctl.py`
+- `tests/` (pytest/testinfra)
+- `development/scripts/vagrant.py`
+- `inventories/broker.py`
+
+## Workflow
+
+1. **Run ansible-lint** on both `src/` and `development/` separately.
+2. **Analyze output** -- categorize issues by severity and type.
+3. **Apply safe fixes** -- fix formatting, naming, YAML style, and other purely stylistic issues.
+4. **Verify** -- re-run linting to confirm fixes. Run tests if any functional file was touched.
+5. **Report** -- list what was fixed and any remaining issues that require manual intervention or behavior changes.
+
+## Common Ansible Lint Issues
+
+- `yaml[truthy]` -- use `true`/`false` instead of `yes`/`no`
+- `yaml[line-length]` -- lines exceeding 120 characters
+- `name[missing]` -- tasks without a `name` field
+- `risky-file-permissions` -- file/template tasks without explicit `mode`
+- `fqcn[action-core]` -- use fully qualified collection names (`ansible.builtin.copy` not `copy`)
+
+## Boundaries
+
+CAN fix: formatting, indentation, whitespace, YAML style, FQCN usage, missing task names, and similar purely stylistic issues.
+
+CANNOT fix: anything that changes task behavior, playbook logic, variable values, conditionals, or test assertions. Report these to the user instead.
+
+## Safety Rules
+
+- NEVER change `when:` conditions, `register:` variables, or handler names.
+- NEVER add `# noqa` comments without explicit user approval.
+- NEVER modify `.ansible-lint` configuration without permission.
+- ALWAYS re-run lint after fixes to verify the issue is resolved.
+- ALWAYS run tests after any change to functional code (plugins, filters, inventory scripts).
diff --git a/.ai/agents/podman-agent.md b/.ai/agents/podman-agent.md
new file mode 100644
index 000000000..78ff1a1af
--- /dev/null
+++ b/.ai/agents/podman-agent.md
@@ -0,0 +1,113 @@
+---
+name: podman-agent
+description: >-
+  Specialist for Podman container management in foremanctl. Use when working
+  with quadlet files, container/volume/network definitions, systemd integration,
+  image references, or Podman secret management. WHEN NOT: Writing Ansible
+  tasks unrelated to Podman (use ansible-role-agent), modifying playbook
+  metadata (use ansible-playbook-agent), or writing tests (use test-agent).
+scope:
+  - src/roles/
+  - src/vars/images.yml
+technologies:
+  - podman
+  - systemd
+  - ansible
+  - jinja2
+references:
+  - DEVELOPMENT.md
+  - docs/developer/deployment.md
+  - docs/developer/container-image-builds.md
+---
+
+# Podman Agent
+
+You are a Podman and container management specialist for foremanctl.
+
+## Your Role
+
+You work with Podman quadlets, container definitions, volume management, network configuration, systemd service integration, and Podman secret management within the foremanctl deployment system.
+
+## Podman Quadlets
+
+foremanctl uses Podman quadlets for declarative container-to-systemd service conversion. Quadlet files define containers, volumes, and networks as systemd unit-like files that Podman's systemd generator converts into actual systemd services.
+
+### File Types
+
+- `.container` -- container definitions
+- `.volume` -- volume definitions
+- `.network` -- network definitions
+
+## Container Images
+
+Image references are centralized in `src/vars/images.yml`:
+
+| Service | Registry | Tag Pattern |
+|---------|----------|-------------|
+| Foreman | `quay.io/foreman/foreman` | `3.18` |
+| Candlepin | `quay.io/foreman/candlepin` | `foreman-3.18` |
+| Foreman Proxy | `quay.io/foreman/foreman-proxy` | `3.18` |
+| Pulp | `quay.io/foreman/pulp` | `foreman-3.18` |
+| PostgreSQL | `quay.io/sclorg/postgresql-13-c9s` | `latest` |
+| Redis | `quay.io/sclorg/redis-6-c9s` | `latest` |
+
+The `container_tag_stream` variable (`3.18`) controls the Foreman version across all images.
+
+## Podman Secrets
+
+Configuration files and credentials are stored as Podman secrets and mounted into containers.
+
+### Naming Convention
+
+- Config files: `<role_namespace>-<filename>-<extension>`
+- Config files (with app context): `<role_namespace>-<app>-<filename>-<extension>`
+- Strings: `<role_namespace>-<descriptive_name>`
+- Strings (with app context): `<role_namespace>-<app>-<descriptive_name>`
+
+### Required Labels
+
+All secrets must include:
+
+- `filename` -- name of the configuration file with extension
+- `app` -- name of the application that uses the secret
+
+### Inspection
+
+```bash
+podman secret ls
+podman secret inspect --showsecret --format "{{.SecretData}}" <secret-name>
+```
+
+## Service Roles
+
+Each containerized service has a corresponding Ansible role in `src/roles/`:
+
+| Role | Service | Container |
+|------|---------|-----------|
+| `foreman` | Foreman application server | Puma + Foreman |
+| `pulp` | Pulp content management | Pulp workers + API |
+| `candlepin` | Subscription management | Candlepin |
+| `postgresql` | Database | PostgreSQL 13 |
+| `redis` | Cache/queue | Redis 6 |
+| `httpd` | Reverse proxy | Apache HTTPD |
+| `foreman_proxy` | Smart Proxy | Foreman Proxy |
+
+## Systemd Integration
+
+foremanctl uses a `systemd_target` role to manage service ordering and dependencies. Services are grouped under a systemd target that controls startup/shutdown order.
+
+## Workflow
+
+1. **Identify the container concern** -- new service, volume mount, secret, or image update.
+2. **Follow naming conventions** -- use the established patterns for secrets, images, and quadlet files.
+3. **Update image references** -- modify `src/vars/images.yml` when adding or changing container images.
+4. **Use Ansible modules** -- prefer `containers.podman` collection modules for Podman operations.
+5. **Test with inspection** -- verify secrets, containers, and services after deployment.
+
+## Boundaries
+
+- NEVER hardcode image tags -- always use variables from `src/vars/images.yml`.
+- NEVER store credentials in plain text files -- use Podman secrets.
+- NEVER bypass the Podman secrets naming convention.
+- ALWAYS include required labels (`filename`, `app`) on new secrets.
+- ALWAYS use the `containers.podman` Ansible collection for Podman operations.
diff --git a/.ai/agents/test-agent.md b/.ai/agents/test-agent.md
new file mode 100644
index 000000000..06eeae6a0
--- /dev/null
+++ b/.ai/agents/test-agent.md
@@ -0,0 +1,153 @@
+---
+name: test-agent
+description: >-
+  Writes and runs pytest/testinfra integration and unit tests for foremanctl.
+  Use when creating test files, adding test cases, working with fixtures,
+  or running the test suite. WHEN NOT: Modifying production code (use
+  ansible-role-agent or ansible-playbook-agent), fixing lint issues (use
+  lint-agent), or reviewing code (use code-review-agent).
+scope:
+  - tests/
+technologies:
+  - python
+  - pytest
+  - testinfra
+references:
+  - docs/developer/testing.md
+  - DEVELOPMENT.md
+---
+
+# Test Agent
+
+You are an expert in pytest and testinfra, specializing in infrastructure testing for foremanctl.
+
+## Your Role
+
+You write and maintain tests that verify Foreman/Katello deployments are functioning correctly. Tests are integration tests that SSH into deployed VMs and assert against real services.
+
+## Test Infrastructure
+
+### Machines
+
+| VM | Hostname | Purpose |
+|----|----------|---------|
+| `quadlet` | `quadlet.example.com` | Foreman server -- containers, quadlets, all services |
+| `client` | `client.example.com` | Client-side tests -- host registration, REX |
+| `database` | `database.example.com` | External PostgreSQL testing |
+
+### How Tests Connect
+
+`./forge test` runs `development/playbooks/test/test.yaml`, which generates `.tmp/ssh-config` from the Ansible inventory. Testinfra fixtures open Paramiko sessions through that SSH config.
+
+## Fixtures (`tests/conftest.py`)
+
+### Host Fixtures
+
+| Fixture | Description |
+|---------|-------------|
+| `server` | Testinfra host for the Foreman server (`quadlet`) |
+| `client` | Testinfra host for the client VM |
+| `database` | Testinfra host for the database (same as `server` when `database_mode=internal`) |
+
+### API Fixtures
+
+| Fixture | Description |
+|---------|-------------|
+| `foremanapi` | Authenticated apypie client (`admin` / `changeme`) |
+
+### Resource Lifecycle Fixtures
+
+These create a resource before the test and delete it afterward:
+
+`organization`, `product`, `yum_repository`, `file_repository`, `container_repository`, `lifecycle_environment`, `content_view`, `activation_key`, `client_environment`
+
+### Helper Fixtures
+
+| Fixture | Description |
+|---------|-------------|
+| `server_fqdn` / `client_fqdn` | `quadlet.example.com` / `client.example.com` |
+| `certificates` | Certificate paths (varies by `--certificate-source`) |
+| `ssh_config` | Parsed SSH config for the server |
+| `fixture_dir` | Path to `tests/fixtures/` |
+
+## Test Patterns
+
+### Service test
+
+```python
+def test_service_running(server):
+    assert server.service("redis").is_running
+
+
+def test_service_port(server):
+    assert server.addr("localhost").port(6379).is_reachable
+```
+
+### API test
+
+```python
+def test_delivery_method_setting(foremanapi):
+    settings = foremanapi.list("settings", search="name=delivery_method")
+    assert settings[0]["value"] == "smtp"
+```
+
+### Command execution on host
+
+```python
+def test_postgresql_databases(database):
+    result = database.run("podman exec postgresql psql -U postgres -c '\\l'")
+    assert "foreman" in result.stdout
+```
+
+### Parametrized tests
+
+```python
+@pytest.mark.parametrize("instance", ["orchestrator", "worker", "worker-hosts-queue"])
+def test_dynflow_service_instances(server, instance):
+    assert server.service(f"dynflow-sidekiq@{instance}").is_running
+```
+
+## File Organization
+
+| What you're testing | File |
+|---------------------|------|
+| A new service (container or systemd unit) | `tests/<service>_test.py` |
+| Foreman API behavior | `tests/foreman_api_test.py` |
+| Client registration or content workflows | `tests/client_test.py` |
+| CLI flags, playbooks, or feature management | `tests/features_test.py` or `tests/playbooks_test.py` |
+| A standalone script (no deployment needed) | `tests/unit/<name>_test.py` |
+
+## Running Tests
+
+```bash
+# Full suite (requires deployment)
+./forge test
+
+# Specific file
+pytest tests/postgresql_test.py
+
+# Specific test
+pytest tests/foreman_test.py::test_foreman_service
+
+# With deployment options
+pytest tests/ --database-mode=external
+pytest tests/ --certificate-source=installer
+```
+
+> `.tmp/ssh-config` must exist. Run `./forge test` at least once to generate it.
+
+## Workflow
+
+1. **Identify the scope** -- what component or behavior to test.
+2. **Choose the right file** -- follow the file organization table above.
+3. **Use existing fixtures** -- check `conftest.py` before creating new ones.
+4. **Write focused assertions** -- one concern per test function.
+5. **Use `@pytest.mark.parametrize`** when the same assertion applies to multiple inputs.
+6. **Run and verify** -- execute the specific test file first, then the full suite.
+
+## Boundaries
+
+- NEVER modify production Ansible code -- delegate to the appropriate agent.
+- NEVER run `foremanctl deploy` -- tests require a pre-existing deployment.
+- ALWAYS follow the `tests/<component>_test.py` naming convention.
+- ALWAYS use existing fixtures from `conftest.py` when available.
diff --git a/.ai/commands/add-feature.md b/.ai/commands/add-feature.md
new file mode 100644
index 000000000..e7a5d3fa2
--- /dev/null
+++ b/.ai/commands/add-feature.md
@@ -0,0 +1,110 @@
+---
+name: add-feature
+description: >-
+  Step-by-step workflow for adding a new feature to foremanctl's deployment
+  system. Covers feature registration, proxy configuration, and validation.
+argument-hint: "<feature-name> [--foreman <plugin_name>] [--proxy <plugin_name>] [--hammer <gem_name>]"
+references:
+  - docs/developer/how-to-add-a-feature.md
+  - docs/developer/feature-metadata.md
+  - src/features.yaml
+---
+
+# Commands - Add Feature
+
+Add a new feature to foremanctl's deployment system.
+
+## Input
+
+`$ARGUMENTS` -- the feature name and optional component flags:
+- `<feature-name>` (required) -- hyphenated name for the feature (e.g. `remote-execution`)
+- `--foreman <plugin_name>` -- Foreman plugin gem name (e.g. `foreman_remote_execution`)
+- `--proxy <plugin_name>` -- Smart Proxy plugin name without `smart_proxy_` prefix
+- `--hammer <gem_name>` -- Hammer CLI gem name without `hammer_cli_` prefix
+
+If flags are omitted, prompt the user for which components the feature extends.
+
+## Workflow
+
+### 1. Gather Information
+
+Before making changes, confirm with the user:
+- Which components does the feature extend? (Foreman, Smart Proxy, Hammer, or a combination)
+- Does it have dependencies on other features?
+- Does the Smart Proxy plugin need additional configuration beyond `:enabled`?
+- Does the Smart Proxy plugin need additional setup tasks (SSH keys, extra mounts, etc.)?
+
+### 2. Register the Feature
+
+Add the feature definition to `src/features.yaml`:
+
+```yaml
+<feature-name>:
+  description: <Description of the feature>
+  foreman:
+    plugin_name: <foreman_plugin_name>
+  foreman_proxy:
+    plugin_name: <proxy_plugin_name>
+  hammer: <hammer_gem_name>
+  dependencies:
+    - <dependency-feature>
+```
+
+Only include sections for applicable components. If a dependency is not user-facing, also add it with `internal: true`.
+
+### 3. Create Smart Proxy Settings Template (if applicable)
+
+If the feature has a `foreman_proxy` section, create:
+
+```
+src/roles/foreman_proxy/templates/settings.d/<plugin_name>.yml.j2
+```
+
+Minimal template:
+
+```yaml
+---
+:enabled: {{ feature_enabled }}
+```
+
+Add additional settings in Ruby symbol notation as needed.
+
+### 4. Create Feature Tasks (if applicable)
+
+If the plugin needs setup beyond configuration:
+
+```
+src/roles/foreman_proxy/tasks/feature/<plugin_name>.yaml
+```
+
+The filename must match `foreman_proxy.plugin_name`. Tasks must notify:
+- `Restart Foreman Proxy`
+- `Refresh Foreman Proxy`
+
+### 5. Validate
+
+```bash
+# Deploy with the new feature
+./foremanctl deploy --add-feature=<feature-name>
+
+# Verify it appears as enabled
+./foremanctl features
+
+# Run lint
+cd src; ansible-lint
+```
+
+### 6. Write Tests
+
+Create or update `tests/features_test.py` to verify the feature is functional after deployment.
+
+## Checklist
+
+- [ ] Feature registered in `src/features.yaml`
+- [ ] Plugin names follow naming conventions
+- [ ] Dependencies registered (with `internal: true` if non-user-facing)
+- [ ] Smart Proxy settings template created (if proxy plugin)
+- [ ] Feature tasks created (if additional setup needed)
+- [ ] Tasks notify correct handlers
+- [ ] ansible-lint passes on `src/`
+- [ ] Feature deploys and shows as enabled
diff --git a/.ai/commands/add-playbook.md b/.ai/commands/add-playbook.md
new file mode 100644
index 000000000..80b202dbb
--- /dev/null
+++ b/.ai/commands/add-playbook.md
@@ -0,0 +1,120 @@
+---
+name: add-playbook
+description: >-
+  Scaffolds a new playbook directory with the correct naming conventions,
+  metadata.obsah.yaml, and playbook YAML file for foremanctl or forge.
+argument-hint: "<command-name> [--tool foremanctl|forge] [--include FRAGMENT...]"
+references:
+  - docs/developer/playbooks-and-roles.md
+---
+
+# Commands - Add Playbook
+
+Scaffold a new CLI subcommand as an Ansible playbook for foremanctl or forge.
+
+## Input
+
+`$ARGUMENTS`:
+- `<command-name>` (required) -- the subcommand name (lowercase, hyphenated)
+- `--tool foremanctl|forge` -- which CLI tool the command belongs to (default: `foremanctl`)
+- `--include FRAGMENT...` -- metadata fragments to include (e.g. `_tuning`, `_certificate_source`)
+
+## Workflow
+
+### 1. Determine Target Directory
+
+- `foremanctl` -> `src/playbooks/<command-name>/`
+- `forge` -> `development/playbooks/<command-name>/`
+
+### 2. Create the Playbook YAML
+
+The filename must match the directory name:
+
+```
+<target>/playbooks/<command-name>/<command-name>.yaml
+```
+
+Minimal playbook:
+
+```yaml
+---
+- name: <Command description>
+  hosts: all
+  roles: []
+```
+
+### 3. Create metadata.obsah.yaml
+
+Every subcommand needs metadata with at least a `help` field:
+
+```yaml
+---
+help: |
+  <Description shown in --help output>
+```
+
+Add variables if the command accepts parameters:
+
+```yaml
+variables:
+  <variable_name>:
+    help: <Description>
+    choices:
+      - option1
+      - option2
+```
+
+Add `include` for shared metadata fragments:
+
+```yaml
+include:
+  - _tuning
+  - _certificate_source
+```
+
+### 4. Create a Shared Fragment (if applicable)
+
+If the new command introduces reusable options, create a fragment:
+
+```
+<target>/playbooks/_<fragment_name>/metadata.obsah.yaml
+```
+
+Fragment directories use `_` prefix and contain ONLY `metadata.obsah.yaml`.
+
+### 5. Validate
+
+```bash
+# For src/ playbooks only
+pytest tests/playbooks_test.py -vv
+
+# Run ansible-lint
+cd <target>; ansible-lint
+```
+
+## Checklist
+
+- [ ] Directory name is lowercase with hyphens
+- [ ] Playbook YAML filename matches directory name
+- [ ] `metadata.obsah.yaml` has at least a `help` field
+- [ ] Shared options use `include` to reference `_`-prefixed fragments (not duplicated)
+- [ ] `ansible-lint` passes
+- [ ] `playbooks_test.py` passes (for `src/` playbooks)
+
+## Examples
+
+**Simple command (forge):**
+
+```
+development/playbooks/my-command/
+  my-command.yaml
+  metadata.obsah.yaml
+```
+
+**Command with shared options (foremanctl):**
+
+```
+src/playbooks/my-command/
+  my-command.yaml
+  metadata.obsah.yaml     # includes: [_tuning, _certificate_source]
+```
diff --git a/.ai/commands/catchup.md b/.ai/commands/catchup.md
new file mode 100644
index 000000000..add54bd12
--- /dev/null
+++ b/.ai/commands/catchup.md
@@ -0,0 +1,104 @@
+---
+name: catchup
+description: >-
+  Summarize what happened on the current branch since the developer's last
+  contribution. Shows commits, authors, stats, and key changes.
+argument-hint: "[developer email or name -- optional, defaults to local git user]"
+---
+
+# Commands - Catchup: Branch Activity Since Last Contribution
+
+Produce a focused summary for a developer returning to a feature branch.
+
+## Input
+
+`$ARGUMENTS` -- optional identity of the returning developer:
+- empty -> use `git config user.email`
+- an email -> match commits by author email
+- a name -> match commits by author name (case-insensitive)
+
+## Workflow
+
+### 1. Resolve Context
+
+Run in parallel:
+- `git rev-parse --abbrev-ref HEAD` -> current branch
+- `git config user.email` and `git config user.name` -> default identity
+- `git remote show origin | sed -n 's/.*HEAD branch: //p'` -> base branch (fallback: `master`)
+- `git fetch --quiet` if a remote exists (skip silently on failure)
+
+Abort with a clear message if HEAD is detached or on `master`.
+
+### 2. Find the Developer's Last Commit
+
+```bash
+git log <base>..HEAD --author="<dev>" -n 1 --format="%H %ci %s"
+```
+
+- Found -> use as the **since** anchor
+- Not found -> use `git merge-base HEAD <base>` as anchor; note "first time on this branch"
+
+### 3. Gather Activity
+
+Read-only git commands between the anchor and HEAD:
+
+```bash
+# Commits with authors
+git log <anchor>..HEAD --format="%h|%an|%ae|%cr|%s" --no-merges
+
+# Author breakdown
+git shortlog -sne <anchor>..HEAD --no-merges
+
+# Diff stats
+git diff --stat <anchor>..HEAD
+
+# Per-file churn
+git diff --numstat <anchor>..HEAD
+```
+
+### 4. Synthesize
+
+Group changes by theme:
+- **Features added** -- new behavior
+- **Refactors** -- structural changes
+- **Bug fixes** -- what broke and was fixed
+- **Tests / tooling / CI** -- brief notes
+- **Requires attention** -- migrations, schema changes, config changes, dependency bumps, security-sensitive files
+
+Reference specific files and commit SHAs.
+
+### 5. Format Report
+
+```markdown
+## Catchup -- `<branch>` for <Dev Name>
+**Base:** `<base>` | **Since:** <anchor> | **Generated:** <date>
+
+### At a glance
+- **Commits:** N (from M authors)
+- **Files changed:** F (+A / -D lines)
+- **Your last commit:** `<sha>` -- "<subject>" (<relative time>)
+
+### Who changed what
+| Author | Commits | Lines (+/-) |
+|--------|---------|-------------|
+| ...    | ...     | ...         |
+
+### Themes
+**Features**
+- <bullet> -- `sha1234` (`path/to/file`)
+
+**Refactors / Bug fixes / Tests**
+- ...
+
+### Requires your attention
+- <change> -- `sha`, `path`
+
+### Commit log
+- `sha` -- *Author* -- <relative time> -- subject
+```
+
+## Notes
+
+- **Read-only**: never run `git pull`, `git checkout`, or anything that mutates state. Only `git fetch --quiet` is allowed.
+- Keep the report under 300 lines. Truncate long diffs.
+- If no commits are in range, output "You're up to date -- nothing new on `<branch>` since `<anchor>`."
diff --git a/.ai/commands/deploy-dev.md b/.ai/commands/deploy-dev.md
new file mode 100644
index 000000000..e83af10c3
--- /dev/null
+++ b/.ai/commands/deploy-dev.md
@@ -0,0 +1,95 @@
+---
+name: deploy-dev
+description: >-
+  End-to-end development environment setup: creates the virtualenv, starts
+  VMs, and deploys Foreman for development and testing.
+argument-hint: "[--tuning PROFILE] [--add-feature FEATURE]"
+references:
+  - DEVELOPMENT.md
+---
+
+# Commands - Deploy Development Environment
+
+Set up a complete foremanctl development environment from scratch.
+
+## Input
+
+`$ARGUMENTS` -- optional deployment customizations:
+- `--tuning PROFILE` -- resource profile (default: `development`). Options: `default`, `development`, `medium`, `large`, `extra-large`, `extra-extra-large`
+- `--add-feature FEATURE` -- additional features to enable (e.g. `hammer`, `remote-execution`)
+
+## Prerequisites
+
+The host machine needs:
+- Vagrant 2.2+
+- ansible-core 2.16+
+- Vagrant Libvirt provider plugin
+- Virtualization enabled in BIOS
+
+## Workflow
+
+### 1. Set Up the Python Environment
+
+```bash
+./setup-environment
+source .venv/bin/activate
+```
+
+This creates a virtualenv, installs dependencies from `src/requirements.txt` and `development/requirements.txt`, and builds Ansible collections.
+
+### 2. Start Development VMs
+
+```bash
+./forge vms start
+```
+
+This provisions Vagrant VMs defined in the `Vagrantfile`:
+- `quadlet` (quadlet.example.com) -- Foreman server
+- `client` (client.example.com) -- client for registration tests
+- `database` (database.example.com) -- external database testing
+
+### 3. Deploy Foreman
+
+```bash
+./foremanctl deploy --foreman-initial-admin-password=changeme --tuning development
+```
+
+Add features as needed:
+
+```bash
+./foremanctl deploy --add-feature hammer
+./foremanctl deploy --add-feature remote-execution
+```
+
+### 4. Verify Deployment
+
+```bash
+./foremanctl features
+```
+
+### 5. Run Tests (Optional)
+
+```bash
+./forge test
+```
+
+## Teardown
+
+```bash
+./forge vms stop
+```
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Vagrant Libvirt not found | Install: `vagrant plugin install vagrant-libvirt` |
+| VM fails to start | Check virtualization is enabled, run `vagrant destroy` and retry |
+| Collection build fails | Delete `build/` directory and re-run `./setup-environment` |
+| Deploy hangs | Check VM is reachable: `vagrant ssh quadlet` |
+
+## Important
+
+- The deployment modifies the target VMs. Do not run against production systems.
+- The `development` tuning profile uses minimal resources suitable for local development.
+- Hammer is not deployed by default -- add it explicitly if needed.
diff --git a/.ai/commands/lint.md b/.ai/commands/lint.md
new file mode 100644
index 000000000..2665b3b9e
--- /dev/null
+++ b/.ai/commands/lint.md
@@ -0,0 +1,86 @@
+---
+name: lint
+description: >-
+  Runs ansible-lint and Python linting across the foremanctl codebase.
+  Reports issues and applies safe auto-fixes.
+argument-hint: "[src|development|all]"
+references:
+  - .ansible-lint
+  - .github/workflows/test.yml
+---
+
+# Commands - Lint
+
+Run linting tools across the foremanctl codebase.
+
+## Input
+
+`$ARGUMENTS` -- optional scope:
+- empty or `all` -> lint both `src/` and `development/`
+- `src` -> lint only the production codebase
+- `development` -> lint only the development codebase
+
+## Workflow
+
+### 1. Ansible Lint
+
+ansible-lint must be run from within each data directory separately, matching CI behavior:
+
+```bash
+cd src; ansible-lint
+```
+
+```bash
+cd development; ansible-lint
+```
+
+### 2. Categorize Results
+
+Group findings by:
+- **Errors** -- must be fixed before merging (CI will fail)
+- **Warnings** -- should be fixed but won't block CI
+- **Style** -- optional improvements
+
+### 3. Apply Safe Fixes
+
+For each fixable issue:
+- YAML formatting (truthy values, line length, indentation)
+- Missing FQCN (replace `copy` with `ansible.builtin.copy`)
+- Missing task names (add descriptive names)
+
+Do NOT fix:
+- Issues that change task behavior or conditions
+- Issues that require understanding business context
+
+### 4. Verify Fixes
+
+Re-run ansible-lint after fixes to confirm resolution:
+
+```bash
+cd src; ansible-lint
+cd development; ansible-lint
+```
+
+### 5. Report
+
+Output a summary:
+
+```
+## Lint Results
+
+### src/
+- Fixed: N issues (list)
+- Remaining: M issues (list with explanations)
+
+### development/
+- Fixed: N issues (list)
+- Remaining: M issues (list with explanations)
+```
+
+## CI Context
+
+The GitHub Actions workflow runs:
+1. `ansible-lint` with `working_directory: src`
+2. `ansible-lint` with `working_directory: development`
+
+Each directory has its own `ansible.cfg` and `requirements.yml`. Lint must pass in both for CI to be green.
diff --git a/.ai/commands/run-tests.md b/.ai/commands/run-tests.md
new file mode 100644
index 000000000..713828577
--- /dev/null
+++ b/.ai/commands/run-tests.md
@@ -0,0 +1,102 @@
+---
+name: run-tests
+description: >-
+  Workflow for running the foremanctl test suite. Checks prerequisites,
+  executes tests, and interprets output.
+argument-hint: "[test-file-or-pattern] [--database-mode=MODE] [--certificate-source=SOURCE]"
+references:
+  - docs/developer/testing.md
+  - tests/conftest.py
+---
+
+# Commands - Run Tests
+
+Run the foremanctl test suite against a deployed environment.
+
+## Input
+
+`$ARGUMENTS` -- optional test target and deployment options:
+- empty -> run the full suite via `./forge test`
+- `<file>` -> run a specific test file (e.g. `tests/postgresql_test.py`)
+- `<file>::<test>` -> run a specific test (e.g. `tests/foreman_test.py::test_foreman_service`)
+- `--database-mode=external` -> test against external database
+- `--certificate-source=installer` -> test with installer certificates
+
+## Prerequisites
+
+Before running tests, verify:
+
+1. **Deployment exists** -- a Foreman instance must be deployed and running.
+2. **SSH config exists** -- `.tmp/ssh-config` must be present. If missing, run `./forge test` once to generate it.
+3. **Virtual environment active** -- `.venv` must be activated (`source .venv/bin/activate`).
+
+## Workflow
+
+### 1. Check Prerequisites
+
+```bash
+# Verify venv
+test -f .venv/bin/activate && echo "venv exists" || echo "Run ./setup-environment first"
+
+# Verify SSH config
+test -f .tmp/ssh-config && echo "SSH config exists" || echo "Run ./forge test to generate"
+```
+
+### 2. Run Tests
+
+**Full suite:**
+
+```bash
+./forge test
+```
+
+**Specific file:**
+
+```bash
+pytest tests/postgresql_test.py -vv
+```
+
+**Specific test:**
+
+```bash
+pytest tests/foreman_test.py::test_foreman_service -vv
+```
+
+**With deployment options:**
+
+```bash
+./forge test --pytest-args="--certificate-source=installer --database-mode=external"
+# or directly:
+pytest tests/ --database-mode=external --certificate-source=installer -vv
+```
+
+### 3. Interpret Results
+
+- **PASSED** -- test assertions succeeded
+- **FAILED** -- assertion failed; check the assertion message and the service/API state
+- **ERROR** -- test setup/teardown failed; often an SSH connection issue or missing fixture
+- **SKIPPED** -- test skipped due to unmet conditions (e.g. feature not deployed)
+
+### 4. Common Failure Patterns
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| SSH connection refused | VM not running | `./forge vms start` |
+| `FileNotFoundError: .tmp/ssh-config` | SSH config not generated | `./forge test` once |
+| Hammer tests fail | Hammer not deployed | `./foremanctl deploy --add-feature hammer` |
+| API timeout | Foreman not fully started | Wait and retry, check `podman ps` on server |
+| Certificate errors | Wrong `--certificate-source` | Match test flag to deployment config |
+
+### 5. Smoker Tests
+
+For browser-based smoke tests (separate from pytest):
+
+```bash
+./forge smoker
+```
+
+## Notes
+
+- Tests are integration tests running against real VMs, not mocks.
+- Test execution time depends on the deployment state and test scope.
+- `playbooks_test.py` can run without a deployment (it only checks playbook metadata).
diff --git a/.ai/rules/ansible-conventions.md b/.ai/rules/ansible-conventions.md
new file mode 100644
index 000000000..17b913f22
--- /dev/null
+++ b/.ai/rules/ansible-conventions.md
@@ -0,0 +1,68 @@
+---
+name: ansible-conventions
+description: >-
+  Coding conventions for Ansible playbooks, roles, and metadata in foremanctl.
+  All agents working with Ansible code must follow these rules.
+applies-to:
+  - src/playbooks/
+  - src/roles/
+  - development/playbooks/
+  - development/roles/
+references:
+  - docs/developer/playbooks-and-roles.md
+---
+
+# Rules - Ansible Conventions
+
+These rules apply to all Ansible code in foremanctl.
+
+## Playbook Naming
+
+- Each playbook directory under `playbooks/` becomes a CLI subcommand via obsah.
+- **Directory name** = subcommand name. Use lowercase with hyphens (`pull-images`, `deploy-dev`).
+- **Playbook YAML filename must match the directory name.** Example: `deploy/deploy.yaml`, NOT `deploy/main.yaml`.
+- Shared metadata fragments use `_` prefix with underscores (`_certificate_source`, `_database_mode`). They contain ONLY `metadata.obsah.yaml` -- no playbook YAML.
+- Every subcommand directory must have a `metadata.obsah.yaml` with at least a `help` field.
+
+## Role Naming
+
+- Use **lowercase with underscores**: `foreman_proxy`, `post_install`, `check_hostname`.
+- Name roles after the service or concern they manage: `redis`, `httpd`, `certificates`.
+
+## File Extensions
+
+- Use `.yaml` for playbook and task files, not `.yml`.
+- Use `.j2` for Jinja2 templates.
+
+## Task Requirements
+
+- Every task MUST have a `name` field with a descriptive, human-readable name.
+- Use fully qualified collection names (FQCN) for all modules: `ansible.builtin.copy`, NOT `copy`.
+- Tasks must be idempotent. If using `ansible.builtin.command` or `ansible.builtin.shell`, use `creates`, `removes`, or `when` to ensure idempotency.
+- File and template tasks MUST include an explicit `mode` parameter.
+
+## Handlers
+
+- Use handlers for service state changes (restart, reload).
+- Handler names use Title Case: `Restart Foreman Proxy`, `Refresh Foreman Proxy`.
+- Tasks that change service configuration MUST use `notify` to trigger handlers, not inline service tasks.
+
+## Variables
+
+- Variable names use `snake_case`.
+- Obsah auto-converts `snake_case` to `--hyphen-case` CLI flags. Override with `parameter` in metadata only when necessary.
+- Default values belong in `src/vars/defaults.yml` or role `defaults/main.yaml`, not hardcoded in tasks.
+- Sensitive values (passwords, keys) must use Podman secrets, never Ansible variables in plain text.
+
+## metadata.obsah.yaml
+
+- `help` is required for every subcommand.
+- Use `include` to reference shared fragments rather than duplicating variable definitions across subcommands.
+- Variable properties: `help` (required), `parameter`, `action`, `choices`, `type`, `persist`, `dest`.
+- Constraint types: `required_together`, `required_if`.
+
+## Linting
+
+- ansible-lint must pass on both `src/` and `development/` independently.
+- Run from within the directory: `cd src; ansible-lint` and `cd development; ansible-lint`.
+- Do NOT add `# noqa` comments without explicit justification.
diff --git a/.ai/rules/podman-secrets.md b/.ai/rules/podman-secrets.md
new file mode 100644
index 000000000..85c14f74c
--- /dev/null
+++ b/.ai/rules/podman-secrets.md
@@ -0,0 +1,72 @@
+---
+name: podman-secrets
+description: >-
+  Naming conventions and requirements for Podman secrets in foremanctl.
+  All agents creating or modifying secret-related code must follow these rules.
+applies-to:
+  - src/roles/
+references:
+  - DEVELOPMENT.md
+---
+
+# Rules - Podman Secrets Conventions
+
+Configuration files and credentials for containerized services are stored as Podman secrets and mounted into containers. All new secrets must follow these conventions.
+
+## Naming
+
+### Config Files
+
+```shell
+<role_namespace>-<filename>-<extension>
+```
+
+When additional application context is needed:
+
+```shell
+<role_namespace>-<app>-<filename>-<extension>
+```
+
+### Strings (Passwords, Tokens, etc.)
+
+```shell
+<role_namespace>-<descriptive_name>
+```
+
+When additional application context is needed:
+
+```shell
+<role_namespace>-<app>-<descriptive_name>
+```
+
+## Required Labels
+
+Every Podman secret MUST include these labels:
+
+### Config Files
+
+- `filename` -- the file name with extension (e.g. `settings.yml`)
+- `app` -- the application that uses the configuration file (e.g. `foreman`)
+
+### Strings
+
+- `app` -- the application that uses the string (e.g. `postgresql`)
+
+## Inspection Commands
+
+```bash
+# List all secrets
+podman secret ls
+
+# View a secret's content
+podman secret inspect --showsecret --format "{{.SecretData}}" <secret-name>
+```
+
+## Rules
+
+- NEVER store credentials or sensitive configuration in plain text files, Ansible variables, or version control.
+- ALWAYS use Podman secrets for configuration files mounted into containers.
+- ALWAYS include the required labels on every new secret.
+- ALWAYS follow the naming convention -- no ad-hoc naming.
+- Secret names must be unique across the entire deployment.
+- When a role manages multiple configuration files, each gets its own secret following the naming pattern.
diff --git a/.ai/rules/project-structure.md b/.ai/rules/project-structure.md
new file mode 100644
index 000000000..057d33449
--- /dev/null
+++ b/.ai/rules/project-structure.md
@@ -0,0 +1,149 @@
+---
+name: project-structure
+description: >-
+  Canonical directory layout and structural conventions for the foremanctl
+  repository. Reference for all agents when locating or creating files.
+applies-to:
+  - "*"
+---
+
+# Rules - Project Structure
+
+Canonical layout of the foremanctl repository.
+
+## Top-Level Overview
+
+```shell
+foremanctl              # Bash wrapper -> obsah (OBSAH_DATA=src)
+forge                   # Bash wrapper -> obsah (OBSAH_DATA=development)
+setup-environment       # Creates .venv, installs deps, builds collections
+Makefile                # dist tarball + collection builds
+Vagrantfile             # VM definitions for dev/CI
+VERSION                 # Git-derived version string
+
+CONTRIBUTING_AI.md      # AI development guide
+DEVELOPMENT.md          # Human development guide
+README.md               # Project overview
+RELEASE.md              # Release process
+
+.ansible-lint           # Repo-wide ansible-lint config
+.packit.yml             # COPR build automation (RHEL 9)
+
+src/                    # Production codebase (foremanctl)
+development/            # Development codebase (forge)
+tests/                  # pytest/testinfra tests
+docs/                   # Documentation
+inventories/            # Ansible inventory files
+build/                  # Build artifacts (not in git)
+.var/                   # Runtime state (not in git)
+.ai/                    # AI agent specifications
+```
+
+## `src/` -- Production (foremanctl)
+
+```shell
+src/
+  ansible.cfg                      # Ansible config (roles_path, plugins, callback)
+  requirements.txt                 # Python deps (obsah, requests)
+  requirements.yml                 # Ansible Galaxy collections
+  features.yaml                    # Feature registry
+
+  playbooks/
+    deploy/                        # foremanctl deploy
+      deploy.yaml
+      metadata.obsah.yaml
+    checks/                        # foremanctl checks
+    features/                      # foremanctl features
+    pull-images/                   # foremanctl pull-images
+    _certificate_source/           # Shared fragment (not a command)
+    _database_mode/                # Shared fragment
+    _database_connection/          # Shared fragment
+    _tuning/                       # Shared fragment
+    _flavor_features/              # Shared fragment
+
+  roles/
+    foreman/                       # Foreman application server
+    pulp/                          # Pulp content management
+    candlepin/                     # Subscription management
+    postgresql/                    # Database
+    redis/                         # Cache/queue
+    httpd/                         # Reverse proxy
+    foreman_proxy/                 # Smart Proxy
+    hammer/                        # CLI tool
+    certificates/                  # Certificate management
+    systemd_target/                # Service ordering
+    pre_install/                   # Pre-deployment checks and setup
+    post_install/                  # Post-deployment tasks
+    check_*/                       # Validation roles
+
+  vars/
+    defaults.yml                   # Base defaults
+    base.yaml                      # Base configuration
+    images.yml                     # Container image references
+    database.yml                   # Database configuration
+    foreman.yml                    # Foreman configuration
+    default_certificates.yml       # Default certificate config
+    installer_certificates.yml     # Installer certificate config
+    flavors/
+      katello.yml                  # Katello flavor definition
+    tuning/
+      default.yml                  # Default resource profile
+      development.yml              # Minimal resources for dev
+      medium.yml / large.yml / ... # Scaling profiles
+
+  callback_plugins/
+    foremanctl.py                  # Custom Ansible callback
+  filter_plugins/
+    foremanctl.py                  # Custom Jinja2 filters
+```
+
+## `development/` -- Development (forge)
+
+```shell
+development/
+  ansible.cfg                      # Ansible config (merges ../src/roles)
+  requirements.txt                 # Dev/test Python deps
+  requirements.yml                 # Dev Ansible Galaxy collections
+
+  playbooks/
+    vms/                           # forge vms (start/stop VMs)
+    deploy-dev/                    # forge deploy-dev
+    test/                          # forge test
+    smoker/                        # forge smoker
+    sos/                           # forge sos
+    security/                      # forge security
+    lock/                          # forge lock
+    _flavor_features/              # Shared fragment
+
+  roles/
+    foreman_development/           # Dev Foreman setup
+    git_repository/                # Git repo management
+    foreman_installer_certs/       # Installer cert generation
+```
+
+## `tests/`
+
+```shell
+tests/
+  conftest.py                      # Shared fixtures
+  *_test.py                        # Integration tests (per component)
+  unit/                            # Unit tests (no deployment needed)
+  fixtures/                        # Test data (certs, manifests)
+```
+
+## `inventories/`
+
+```shell
+inventories/
+  localhost                        # Local deployment (ansible_connection=local)
+  local_vagrant                    # Vagrant-managed VMs
+  broker.py                        # Dynamic inventory script
+```
+
+## Key Relationships
+
+- `foremanctl` sets `OBSAH_DATA=src/` and executes obsah
+- `forge` sets `OBSAH_DATA=development/` and executes obsah
+- `development/ansible.cfg` includes `../src/roles` in its roles path, so dev playbooks can use production roles
+- Collections are built into `build/collections/foremanctl` and `build/collections/forge` separately
+- `.var/lib/foremanctl/` stores persistent deployment state and answers
diff --git a/.ai/rules/safety.md b/.ai/rules/safety.md
new file mode 100644
index 000000000..6cfc63122
--- /dev/null
+++ b/.ai/rules/safety.md
@@ -0,0 +1,60 @@
+---
+name: safety
+description: >-
+  Safety rules for all AI agents working with foremanctl. Prevents destructive
+  operations and protects production deployments.
+applies-to:
+  - "*"
+---
+
+# Rules - Safety Rules
+
+These rules apply to ALL agents and commands. They are non-negotiable.
+
+## Destructive Command Blocklist
+
+NEVER execute these commands without explicit user confirmation:
+
+- `rm -rf /` or `rm -rf ~` or any recursive delete of system directories
+- `git push --force` to `master` or `main`
+- `DROP TABLE`, `DROP DATABASE`, or other destructive SQL
+- `chmod 777` on any path
+- `podman system prune` or `podman volume prune` without confirmation
+- `vagrant destroy` without confirmation
+- `systemctl stop` or `systemctl disable` on production services without confirmation
+
+## Production Awareness
+
+foremanctl targets REAL production deployments of Foreman and Katello. AI agents must understand:
+
+- `./foremanctl deploy` modifies the target system. NEVER run it without explicit user confirmation.
+- `./foremanctl` operates on production infrastructure by default. The development equivalent is `./forge`.
+- Podman secrets may contain production credentials. NEVER log, print, or expose secret values.
+- Changes to `src/` affect production deployments. Changes to `development/` affect dev/test only.
+
+## Git Safety
+
+- NEVER force-push to `master`.
+- NEVER rewrite history on shared branches.
+- NEVER commit files containing credentials, secrets, or sensitive data.
+- Check `.gitignore` before staging new files.
+
+## Ansible Safety
+
+- NEVER use `ansible.builtin.shell` or `ansible.builtin.command` with unvalidated user input.
+- NEVER disable SSL verification in production playbooks.
+- NEVER hardcode passwords or tokens in playbooks, roles, or variables.
+- ALWAYS use `--check` mode when suggesting dry-run verification to users.
+
+## File System Safety
+
+- NEVER modify files outside the repository working directory without explicit permission.
+- NEVER overwrite `.var/` state files -- they contain deployment state and answers.
+- NEVER delete `build/` directories without confirming the user wants to rebuild collections.
+
+## When in Doubt
+
+- Ask the user before executing any command that modifies system state.
+- Prefer read-only operations (inspect, list, show) over write operations.
+- Suggest `--check` or dry-run equivalents when available.
+- If a command could affect production, warn the user explicitly.
diff --git a/.ai/rules/testing-conventions.md b/.ai/rules/testing-conventions.md
new file mode 100644
index 000000000..d8ef3e388
--- /dev/null
+++ b/.ai/rules/testing-conventions.md
@@ -0,0 +1,63 @@
+---
+name: testing-conventions
+description: >-
+  Testing conventions for pytest/testinfra tests in foremanctl. All agents
+  writing or modifying tests must follow these rules.
+applies-to:
+  - tests/
+references:
+  - docs/developer/testing.md
+---
+
+# Rules - Testing Conventions
+
+These rules apply to all test code in foremanctl.
+
+## File Naming
+
+- Integration test files: `tests/<component>_test.py` (e.g. `tests/postgresql_test.py`, `tests/foreman_api_test.py`)
+- Unit test files: `tests/unit/<name>_test.py`
+- The `_test.py` suffix is required for pytest discovery.
+
+## Test Organization
+
+| What you're testing | Where to put it |
+|---------------------|-----------------|
+| A new service (container or systemd unit) | `tests/<service>_test.py` |
+| Foreman API behavior | `tests/foreman_api_test.py` |
+| Client registration or content workflows | `tests/client_test.py` |
+| CLI flags, playbooks, or feature management | `tests/features_test.py` or `tests/playbooks_test.py` |
+| A standalone script (no deployment needed) | `tests/unit/<name>_test.py` |
+
+## Fixture Usage
+
+- ALWAYS check `tests/conftest.py` for existing fixtures before creating new ones.
+- Use `server`, `client`, `database` fixtures for host access -- never create SSH connections manually.
+- Use `foremanapi` for Foreman REST API operations.
+- Use resource lifecycle fixtures (`organization`, `product`, `yum_repository`, etc.) for test data that needs setup and teardown.
+
+## Test Patterns
+
+- One concern per test function.
+- Use `@pytest.mark.parametrize` when the same assertion applies to multiple inputs (e.g. multiple service instances).
+- Test function names must be descriptive: `test_redis_service_running`, not `test_1`.
+- Use `server.run()` for executing commands on VMs, not subprocess or os.system.
+
+## Assertions
+
+- Use plain `assert` statements (pytest-style), not `unittest` assertion methods.
+- Include helpful assertion messages for non-obvious checks.
+- For service tests, check both `is_running` and port reachability.
+
+## Prerequisites
+
+- Integration tests require a running deployment. Do NOT attempt to deploy from within tests.
+- `.tmp/ssh-config` must exist before running integration tests.
+- `playbooks_test.py` is the exception -- it runs without a deployment (metadata validation only).
+
+## Do NOT
+
+- Do not create mocks for infrastructure tests -- they run against real VMs.
+- Do not hardcode hostnames -- use the `server_fqdn`, `client_fqdn` fixtures.
+- Do not hardcode credentials -- use the `foremanapi` fixture which handles authentication.
+- Do not import from production code (`src/`) in tests -- tests interact via SSH and API only.
diff --git a/.ai/settings.local.json b/.ai/settings.local.json
new file mode 100644
index 000000000..9c9c6dce7
--- /dev/null
+++ b/.ai/settings.local.json
@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(obsah)",
+      "Bash(find)",
+      "Bash(grep)",
+      "Bash(ansible-lint)",
+      "Bash(pytest)",
+      "Bash(make)",
+      "Bash(git diff)",
+      "Bash(source .venv/bin/activate)"
+    ]
+  }
+}
diff --git a/.ai/skills/ansible-collections.md b/.ai/skills/ansible-collections.md
new file mode 100644
index 000000000..3fa310549
--- /dev/null
+++ b/.ai/skills/ansible-collections.md
@@ -0,0 +1,125 @@
+---
+name: ansible-collections
+description: >-
+  Ansible Galaxy collections used by foremanctl, how they are installed
+  and managed, and the build/collections layout.
+technologies:
+  - ansible
+references:
+  - src/requirements.yml
+  - development/requirements.yml
+  - Makefile
+---
+
+# Skill - Ansible Collections in foremanctl
+
+foremanctl uses Ansible Galaxy collections for Podman management, cryptography, PostgreSQL, and Foreman API operations. Collections are installed locally per tool to avoid conflicts with system-wide installations.
+
+## Production Collections (`src/requirements.yml`)
+
+```yaml
+collections:
+  - community.postgresql
+  - community.crypto
+  - community.general
+  - ansible.posix
+  - name: containers.podman
+    version: ">=1.16.4"
+  - name: theforeman.foreman
+    version: ">=5.9.0"
+```
+
+### Collection Purposes
+
+| Collection | Purpose |
+|------------|---------|
+| `community.postgresql` | PostgreSQL user, database, and extension management |
+| `community.crypto` | Certificate generation, private keys, CSRs |
+| `community.general` | General-purpose modules (ini_file, json_query, etc.) |
+| `ansible.posix` | POSIX-specific modules (sysctl, mount, selinux) |
+| `containers.podman` | Podman container, secret, volume, network, image management |
+| `theforeman.foreman` | Foreman API operations (resources, settings, content) |
+
+## Development Collections (`development/requirements.yml`)
+
+The development collection set includes the production collections plus:
+
+- `theforeman.operations` -- operational tooling
+- Git-based collections from `forklift` for Vagrant/VM management
+
+## Collection Installation
+
+### Via setup-environment
+
+```bash
+./setup-environment
+```
+
+This runs `pip install` for Python deps and then `make build/collections/foremanctl build/collections/forge` to install Galaxy collections.
+
+### Via Makefile
+
+```bash
+# Install production collections
+make build/collections/foremanctl
+
+# Install development collections
+make build/collections/forge
+```
+
+### Lock File
+
+The Makefile prefers `src/requirements-lock.yml` over `src/requirements.yml` if it exists. The lock file pins exact versions for reproducible builds. If no lock file is present, the floating versions in `requirements.yml` are used.
+
+```makefile
+REQUIREMENTS_YML := $(firstword $(wildcard src/requirements-lock.yml src/requirements.yml))
+```
+
+## Collection Paths
+
+Collections are installed into separate directories per tool and isolated from system paths:
+
+| Tool | Collection Path | Set By |
+|------|----------------|--------|
+| `foremanctl` | `build/collections/foremanctl` | `ANSIBLE_COLLECTIONS_PATH` in `foremanctl` script |
+| `forge` | `build/collections/forge` | `ANSIBLE_COLLECTIONS_PATH` in `forge` script |
+
+Both scripts set `ANSIBLE_COLLECTIONS_SCAN_SYS_PATH=false` to prevent using system-installed collections.
+
+## Using Collections in Roles
+
+Always use fully qualified collection names (FQCN) in tasks:
+
+```yaml
+# Correct
+- name: Create Podman secret
+  containers.podman.podman_secret:
+    name: foreman-settings-yaml
+    data: "{{ settings_content }}"
+
+# Incorrect
+- name: Create Podman secret
+  podman_secret:
+    name: foreman-settings-yaml
+    data: "{{ settings_content }}"
+```
+
+## Build Artifacts
+
+The `make dist` target creates a distribution tarball that includes:
+
+1. Git archive of the repository
+2. Vendored collections from `build/collections/foremanctl`
+3. Collection test directories are excluded from the tarball
+
+```makefile
+$(NAME)-$(VERSION).tar.gz: build/collections/foremanctl
+    git archive --prefix $(NAME)-$(VERSION)/ --output $(NAME)-$(VERSION).tar HEAD
+    tar --append --file $(NAME)-$(VERSION).tar \
+        --transform='s#^#$(NAME)-$(VERSION)/#' \
+        --exclude='build/collections/foremanctl/ansible_collections/*/*/tests/*' \
+        build/collections/foremanctl
+    gzip $(NAME)-$(VERSION).tar
+```
+
+This ensures the distributed package is self-contained and does not require Galaxy access at install time.
diff --git a/.ai/skills/certificate-management.md b/.ai/skills/certificate-management.md
new file mode 100644
index 000000000..898f28044
--- /dev/null
+++ b/.ai/skills/certificate-management.md
@@ -0,0 +1,108 @@
+---
+name: certificate-management
+description: >-
+  Certificate management in foremanctl: sources, configuration, roles,
+  and the relationship between certificate options and deployment behavior.
+technologies:
+  - openssl
+  - ansible
+references:
+  - docs/certificates.md
+  - docs/user/certificates.md
+---
+
+# Skill - Certificate Management in foremanctl
+
+foremanctl manages TLS certificates for secure communication between Foreman ecosystem components. Certificates are a critical part of deployment and are configured through the `certificate_source` parameter.
+
+## Certificate Sources
+
+The `--certificate-source` flag (defined in the `_certificate_source` metadata fragment) controls how certificates are provisioned:
+
+### `default`
+
+Self-signed certificates generated during deployment. Suitable for development and testing.
+
+- Certificates are generated using the `community.crypto` Ansible collection.
+- A self-signed CA is created, and service certificates are signed by it.
+- Configuration in `src/vars/default_certificates.yml`.
+
+### `installer`
+
+Externally provided certificates, typically from an enterprise CA. Required for production.
+
+- The user provides CA certificate, server certificate, and private key.
+- foremanctl validates the certificates before use.
+- Configuration in `src/vars/installer_certificates.yml`.
+
+## Certificate-Related Roles
+
+### `certificates`
+
+The main certificate management role under `src/roles/certificates/`. Handles:
+
+- CA certificate generation or import
+- Service certificate creation
+- Certificate distribution to services
+- Certificate validation
+
+### `certificate_checks`
+
+Validation role under `src/roles/certificate_checks/`. Includes:
+
+- `files/foreman-certificate-check` -- script for validating certificate chains, expiry, and key matching
+
+## Subject Alternative Names (SANs)
+
+Additional DNS names can be included in certificates via the `--certificate-cname` flag:
+
+```bash
+./foremanctl deploy --certificate-cname proxy.example.com --certificate-cname alt.example.com
+```
+
+Defined in the deploy metadata as:
+
+```yaml
+certificates_cnames:
+  help: Additional DNS name to include in Subject Alternative Names for certificates. Can be specified multiple times.
+  action: append_unique
+  type: FQDN
+  parameter: --certificate-cname
+```
+
+## Testing Certificates
+
+### Test Fixtures
+
+Certificate test fixtures live in `tests/fixtures/foreman-certificate-check/`:
+
+- `create_cert.sh` -- script to generate test certificates
+- `extensions.txt` -- certificate extension configuration
+- `certs/` -- sample certificates, keys, and CSRs for testing
+
+### Test File
+
+`tests/certificates_test.py` validates certificate behavior with different sources.
+
+### Running Certificate Tests
+
+```bash
+# Test with default certificates
+pytest tests/certificates_test.py
+
+# Test with installer certificates
+pytest tests/certificates_test.py --certificate-source=installer
+```
+
+## Certificate Flow
+
+1. **Deployment starts** -- `certificate_source` parameter is read from CLI or answers file.
+2. **Certificate role runs** -- generates or imports certificates based on source.
+3. **Certificate checks run** -- validates the certificate chain, expiry, and key matching.
+4. **Services receive certificates** -- distributed via Podman secrets to containers that need TLS.
+5. **HTTPD configured** -- Apache reverse proxy is configured with the server certificate for TLS termination.
+
+## Related Metadata Fragments
+
+- `_certificate_source` -- defines the `certificate_source` variable with choices `[default, installer]`
+- Included by the `deploy` playbook via `include: [_certificate_source]`
diff --git a/.ai/skills/foreman-ecosystem.md b/.ai/skills/foreman-ecosystem.md
new file mode 100644
index 000000000..2bb526cc0
--- /dev/null
+++ b/.ai/skills/foreman-ecosystem.md
@@ -0,0 +1,161 @@
+---
+name: foreman-ecosystem
+description: >-
+  Overview of the Foreman ecosystem components deployed by foremanctl:
+  Foreman, Katello, Pulp, Candlepin, Smart Proxy, and Hammer. Covers
+  features, flavors, and the plugin system.
+technologies:
+  - foreman
+  - katello
+  - pulp
+  - candlepin
+references:
+  - docs/developer/how-to-add-a-feature.md
+  - docs/developer/feature-metadata.md
+  - docs/developer/deployment.md
+---
+
+# Skill - Foreman Ecosystem
+
+foremanctl deploys and manages the Foreman ecosystem -- a suite of open-source tools for lifecycle management of physical and virtual servers.
+
+## Core Components
+
+### Foreman
+
+The central application server for provisioning, configuration management, and monitoring. Runs as a Ruby on Rails application (Puma) in a container.
+
+- Image: `quay.io/foreman/foreman:3.18`
+- Current version: Foreman 3.18
+
+### Katello
+
+Content and subscription management plugin for Foreman. Manages RPM repositories, Deb repositories, container registries, and subscription/entitlement tracking.
+
+- Integrated into the Foreman container as a plugin
+- Current version: Katello 4.20
+
+### Pulp
+
+Content management platform that handles repository synchronization, content storage, and publication. Runs as separate worker and API containers.
+
+- Image: `quay.io/foreman/pulp:foreman-3.18`
+- Current version: Pulp 3.85
+
+### Candlepin
+
+Subscription management service for entitlement tracking and certificate generation. Runs as a Java application in its own container.
+
+- Image: `quay.io/foreman/candlepin:foreman-3.18`
+- Current version: Candlepin 4.6
+
+### Smart Proxy (Foreman Proxy)
+
+Distributed agent that handles operations on managed infrastructure: DHCP, DNS, TFTP, Puppet, Remote Execution, etc. Runs as its own container.
+
+- Image: `quay.io/foreman/foreman-proxy:3.18`
+- Enabled as a feature (`foreman-proxy`)
+
+### Hammer
+
+Command-line interface for interacting with the Foreman API. Unlike other components, Hammer runs directly on the host (not containerized).
+
+- Enabled as a feature (`hammer`)
+
+## Supporting Services
+
+### PostgreSQL
+
+Database backend for Foreman, Katello, Candlepin, and Pulp.
+
+- Image: `quay.io/sclorg/postgresql-13-c9s`
+- Can be internal (containerized) or external
+
+### Redis
+
+In-memory cache and queue backend used by Foreman and Pulp.
+
+- Image: `quay.io/sclorg/redis-6-c9s`
+
+### Apache HTTPD
+
+Reverse proxy that terminates TLS and routes requests to Foreman, Pulp, and Candlepin containers.
+
+- Installed on the host (not containerized)
+
+## Features and Flavors
+
+### Flavors
+
+A flavor defines the base set of features for a deployment. Currently only one flavor exists:
+
+- `katello` -- includes Foreman + Katello + Pulp + Candlepin (defined in `src/vars/flavors/katello.yml`)
+
+### Features
+
+Features are modular capabilities that extend the base deployment:
+
+```yaml
+# src/features.yaml
+remote-execution:
+  description: Remote Execution plugin for Foreman
+  foreman:
+    plugin_name: foreman_remote_execution
+  foreman_proxy:
+    plugin_name: remote_execution_ssh
+  hammer: foreman_remote_execution
+  dependencies:
+    - dynflow
+```
+
+A feature can extend up to three components:
+1. **Foreman** -- plugin installed in the Foreman container
+2. **Smart Proxy** -- plugin installed in the foreman-proxy container
+3. **Hammer** -- CLI plugin installed on the host
+
+### Feature Resolution
+
+```
+enabled_features = flavor_features + user_features
+```
+
+Features are enabled via CLI:
+
+```bash
+./foremanctl deploy --add-feature remote-execution
+./foremanctl deploy --remove-feature remote-execution
+./foremanctl features  # List enabled features
+```
+
+### Internal Features
+
+Features marked `internal: true` are dependencies that are not exposed to users:
+
+```yaml
+dynflow:
+  internal: true
+  foreman_proxy:
+    plugin_name: dynflow
+```
+
+## Platform Support
+
+- **Target OS**: CentOS Stream 9, RHEL 9
+- **Ansible**: ansible-core 2.16+
+- **Python**: 3.9+ (CentOS Stream 9 default)
+- **Podman**: As shipped with CentOS Stream 9 / RHEL 9
+
+## Tuning Profiles
+
+Resource allocation is controlled by tuning profiles in `src/vars/tuning/`:
+
+| Profile | Use Case |
+|---------|----------|
+| `default` | Standard production |
+| `development` | Minimal resources for local dev |
+| `medium` | Medium-scale production |
+| `large` | Large-scale production |
+| `extra-large` | Enterprise scale |
+| `extra-extra-large` | Maximum scale |
+
+Tuning profiles control Puma workers, Pulp worker count, memory limits, and other resource parameters.
diff --git a/.ai/skills/obsah-metadata.md b/.ai/skills/obsah-metadata.md
new file mode 100644
index 000000000..493b7629b
--- /dev/null
+++ b/.ai/skills/obsah-metadata.md
@@ -0,0 +1,195 @@
+---
+name: obsah-metadata
+description: >-
+  Deep reference on the metadata.obsah.yaml schema used to define CLI
+  subcommands in foremanctl and forge. Covers help, variables, constraints,
+  includes, and all variable properties.
+technologies:
+  - yaml
+  - ansible
+references:
+  - docs/developer/playbooks-and-roles.md
+  - https://github.com/theforeman/obsah/blob/master/docs/source/development.rst
+---
+
+# Skill - obsah Metadata Schema
+
+obsah is the Ansible playbook execution engine that powers foremanctl and forge. Each CLI subcommand is defined by a `metadata.obsah.yaml` file in the playbook directory.
+
+## Overview
+
+`metadata.obsah.yaml` defines:
+- Help text for the subcommand
+- CLI parameters (variables) with validation
+- Constraints between parameters
+- Includes to share parameter definitions across subcommands
+
+## `help` (required)
+
+Short description shown in `--help` output:
+
+```yaml
+help: |
+  Install
+```
+
+## `variables`
+
+Each key becomes an Ansible variable passed to the playbook. obsah auto-converts `snake_case` names to `--hyphen-case` CLI flags unless overridden.
+
+### Variable Properties
+
+| Property | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `help` | Yes | Description shown in `--help` | `"Initial password for the admin user."` |
+| `parameter` | No | Override the auto-generated CLI flag name | `--certificate-cname`, `vm_action` (positional) |
+| `action` | No | How the CLI handles the value (see Actions) | `store`, `append_unique` |
+| `choices` | No | Restrict to a fixed list of values | `[internal, external]` |
+| `type` | No | Value type validation (obsah.types) | `FQDN`, `AbsolutePath` |
+| `persist` | No | Save value to answers file for reuse (default: `true`) | `false` |
+| `dest` | No | Override the attribute name for the parsed value | `features` |
+
+### Actions
+
+| Action | Behavior |
+|--------|----------|
+| `store` | Store a single value (default) |
+| `store_true` | Boolean flag, sets variable to `true` when present |
+| `append` | Collect multiple values into a list (repeatable flag) |
+| `append_unique` | Like `append`, but deduplicates values |
+| `remove` | Remove a value from the list variable specified by `dest` |
+
+### Examples
+
+**Simple variable with choices:**
+
+```yaml
+variables:
+  database_mode:
+    help: Defaults to internal. Set to 'external' if using an external database.
+    choices:
+      - internal
+      - external
+```
+
+**Append/remove pair with shared dest:**
+
+```yaml
+variables:
+  features:
+    parameter: --add-feature
+    help: Additional features to enable in this deployment.
+    action: append_unique
+  remove_features:
+    parameter: --remove-feature
+    help: Additional features to disable in this deployment.
+    action: remove
+    dest: features
+```
+
+**Custom type and parameter override:**
+
+```yaml
+variables:
+  certificates_cnames:
+    help: Additional DNS name for Subject Alternative Names. Can be specified multiple times.
+    action: append_unique
+    type: FQDN
+    parameter: --certificate-cname
+```
+
+**Positional argument:**
+
+```yaml
+variables:
+  vm_action:
+    parameter: vm_action
+    help: Start the virtual machines
+    choices:
+      - start
+      - stop
+```
+
+## `constraints`
+
+Enforce rules between related flags:
+
+### `required_together`
+
+All variables in the set must be provided if any one is:
+
+```yaml
+constraints:
+  required_together:
+    - [database_ssl_mode, database_ssl_ca]
+```
+
+### `required_if`
+
+Variables that become required when another variable has a specific value:
+
+```yaml
+constraints:
+  required_if:
+    - ['database_mode', 'external', ['database_host']]
+```
+
+Format: `[variable, value, [required_variables]]`
+
+## `include`
+
+Reference shared metadata fragments to avoid duplicating variable definitions:
+
+```yaml
+include:
+  - _certificate_source
+  - _database_mode
+  - _database_connection
+  - _tuning
+  - _flavor_features
+```
+
+Fragment directories are prefixed with `_` and contain only `metadata.obsah.yaml`. When included, their variables and constraints are merged into the including subcommand's CLI interface.
+
+## Full Example
+
+From `src/playbooks/deploy/metadata.obsah.yaml`:
+
+```yaml
+---
+help: |
+  Install
+
+variables:
+  foreman_initial_admin_username:
+    help: Initial username for the admin user.
+  foreman_initial_admin_password:
+    help: Initial password for the admin user.
+  foreman_puma_workers:
+    help: Number of workers for Puma.
+  pulp_worker_count:
+    help: Number of Pulp workers. Defaults to 8 or the number of CPU cores, whichever is smaller.
+  external_authentication:
+    help: External authentication method to use
+    choices:
+      - ipa
+      - ipa_with_api
+  external_authentication_pam_service:
+    help: Name of the PAM service to use for IPA authentication
+  certificates_cnames:
+    help: Additional DNS name to include in Subject Alternative Names for certificates. Can be specified multiple times.
+    action: append_unique
+    type: FQDN
+    parameter: --certificate-cname
+
+include:
+  - _certificate_source
+  - _database_mode
+  - _database_connection
+  - _tuning
+  - _flavor_features
+```
+
+## Parameter Persistence
+
+By default, obsah persists parameter values to an answers file (`.var/lib/foremanctl/`) so they are reused on subsequent runs. Set `persist: false` for one-time parameters that should not be remembered.
diff --git a/.ai/skills/podman-quadlets.md b/.ai/skills/podman-quadlets.md
new file mode 100644
index 000000000..92d988786
--- /dev/null
+++ b/.ai/skills/podman-quadlets.md
@@ -0,0 +1,127 @@
+---
+name: podman-quadlets
+description: >-
+  How Podman quadlets work in foremanctl: container, volume, and network
+  definitions as systemd-native units, image management, and the relationship
+  between quadlet files and Ansible roles.
+technologies:
+  - podman
+  - systemd
+  - ansible
+references:
+  - docs/developer/container-image-builds.md
+  - docs/developer/deployment.md
+  - src/vars/images.yml
+---
+
+# Skill - Podman Quadlets in foremanctl
+
+foremanctl deploys Foreman and Katello as containerized services managed by systemd through Podman quadlets.
+
+## What Are Quadlets?
+
+Podman quadlets provide a declarative way to define containers, volumes, and networks as systemd unit-like files. The Podman systemd generator automatically converts these files into actual systemd services at boot time (or on `systemctl daemon-reload`).
+
+### Quadlet File Types
+
+| Extension | Purpose |
+|-----------|---------|
+| `.container` | Container definitions (image, env, volumes, ports, secrets) |
+| `.volume` | Named volume definitions |
+| `.network` | Network definitions |
+
+### Quadlet Location
+
+Quadlet files are placed in systemd unit directories (typically `/etc/containers/systemd/`) and processed by the Podman systemd generator.
+
+## Container Images
+
+All image references are centralized in `src/vars/images.yml`:
+
+```yaml
+container_tag_stream: "3.18"
+
+# Foreman ecosystem images (quay.io/foreman/*)
+foreman_container_image: quay.io/foreman/foreman
+foreman_container_tag: "{{ container_tag_stream }}"
+
+candlepin_container_image: quay.io/foreman/candlepin
+candlepin_container_tag: "foreman-{{ container_tag_stream }}"
+
+foreman_proxy_container_image: quay.io/foreman/foreman-proxy
+foreman_proxy_container_tag: "{{ container_tag_stream }}"
+
+pulp_container_image: quay.io/foreman/pulp
+pulp_container_tag: "foreman-{{ container_tag_stream }}"
+
+# Infrastructure images (quay.io/sclorg/*)
+postgresql_container_image: quay.io/sclorg/postgresql-13-c9s
+postgresql_container_tag: "latest"
+
+redis_container_image: quay.io/sclorg/redis-6-c9s
+redis_container_tag: "latest"
+```
+
+### Image Groups
+
+Images are grouped for selective pulling:
+
+- `images` -- core Foreman stack (foreman, candlepin, pulp, redis)
+- `database_images` -- PostgreSQL (separate for external database scenarios)
+- `foreman_proxy_images` -- Smart Proxy (separate because it's a feature)
+
+### Image Naming Convention
+
+Foreman ecosystem images follow: `quay.io/foreman/<service>:<tag>`
+
+Tags follow two patterns:
+- Direct version: `3.18` (foreman, foreman-proxy)
+- Prefixed version: `foreman-3.18` (candlepin, pulp)
+
+Infrastructure images use upstream SCL containers from `quay.io/sclorg/`.
+
+## Services and Roles
+
+Each containerized service has a corresponding Ansible role that manages its quadlet files, configuration, and lifecycle:
+
+| Service | Role | Image | Ports |
+|---------|------|-------|-------|
+| Foreman | `foreman` | `quay.io/foreman/foreman` | 3000 (Puma) |
+| Candlepin | `candlepin` | `quay.io/foreman/candlepin` | 8443 |
+| Pulp | `pulp` | `quay.io/foreman/pulp` | 24816 (API), workers |
+| PostgreSQL | `postgresql` | `quay.io/sclorg/postgresql-13-c9s` | 5432 |
+| Redis | `redis` | `quay.io/sclorg/redis-6-c9s` | 6379 |
+| Apache HTTPD | `httpd` | (host-installed) | 80, 443 |
+| Smart Proxy | `foreman_proxy` | `quay.io/foreman/foreman-proxy` | 8000, 9090 |
+
+## systemd Integration
+
+foremanctl uses a `systemd_target` role to manage service ordering. Services are grouped under a systemd target that controls startup and shutdown order, ensuring dependencies (like PostgreSQL) start before dependent services (like Foreman).
+
+## Configuration via Secrets
+
+Container configuration is mounted from Podman secrets, not host files. See the `podman-secrets` rule for naming conventions.
+
+### Registry Authentication
+
+All services share a registry auth file at `/etc/foreman/registry-auth.json`, referenced per-service as `<service>_registry_auth_file` variables in `images.yml`.
+
+## Pulling Images
+
+The `pull-images` playbook (`foremanctl pull-images`) pre-pulls container images before deployment:
+
+```bash
+./foremanctl pull-images
+```
+
+This is useful for air-gapped or slow-network environments where you want to cache images before deploying.
+
+## Key Ansible Collection
+
+Container operations use the `containers.podman` Ansible collection (version >= 1.16.4), which provides:
+
+- `containers.podman.podman_container` -- manage containers
+- `containers.podman.podman_secret` -- manage secrets
+- `containers.podman.podman_volume` -- manage volumes
+- `containers.podman.podman_network` -- manage networks
+- `containers.podman.podman_image` -- manage images
diff --git a/CONTRIBUTING_AI.md b/CONTRIBUTING_AI.md
new file mode 100644
index 000000000..d4e0d0646
--- /dev/null
+++ b/CONTRIBUTING_AI.md
@@ -0,0 +1,301 @@
+# AI Development Guide
+
+This file provides guidance to AI tools and agents when working with code in this repository. It is intentionally tool-agnostic -- it works with Claude Code, Cursor, GitHub Copilot, and any other AI assistant.
+
+## Project Overview
+
+foremanctl is a deployment tool for Foreman and Katello using Podman quadlets and Ansible. It provides a command-line interface built on top of `obsah` (an Ansible wrapper) for managing containerized Foreman deployments.
+
+The repository contains two main wrapper scripts:
+
+- `foremanctl` - Production deployment and management
+- `forge` - Development environment management and testing
+
+Both scripts wrap `obsah`, which provides a structured way to run Ansible playbooks with parameter validation and persistence.
+
+## Supported Platforms
+
+- **Target OS**: CentOS Stream 9, RHEL 9
+- **Ansible**: ansible-core 2.16+
+- **Python**: 3.9+ (as shipped with CentOS Stream 9)
+- **Podman**: As shipped with CentOS Stream 9 / RHEL 9
+- **Vagrant**: 2.2+ (for development VMs)
+- **Virtualization**: Libvirt with Vagrant Libvirt provider
+
+## AI Specifications
+
+Detailed agent, command, rule, and skill specifications live under `.ai/`. These are tool-agnostic Markdown files with YAML frontmatter that any AI tool can parse or ignore.
+
+### Directory Structure
+
+```
+.ai/
+  agents/          # Specialist agent personas with defined scopes
+  commands/        # Reusable command workflows (slash-command style)
+  rules/           # Coding standards and constraints (all agents must follow)
+  skills/          # Domain knowledge references
+```
+
+### Agents (`.ai/agents/`)
+
+Focused personas with defined scopes and technology boundaries:
+
+| Agent | Purpose |
+|-------|---------|
+| `ansible-playbook-agent` | Playbooks and `metadata.obsah.yaml` files |
+| `ansible-role-agent` | Roles, tasks, handlers, templates |
+| `feature-agent` | End-to-end feature addition workflow |
+| `test-agent` | pytest/testinfra tests |
+| `lint-agent` | ansible-lint and Python linting |
+| `podman-agent` | Podman quadlets, containers, secrets |
+| `code-review-agent` | Read-only code review and analysis |
+
+### Commands (`.ai/commands/`)
+
+Reusable workflows invoked by name:
+
+| Command | Purpose |
+|---------|---------|
+| `add-feature` | Register and configure a new foremanctl feature |
+| `run-tests` | Run the test suite with prerequisites check |
+| `lint` | Run ansible-lint across both codebases |
+| `deploy-dev` | Full development environment setup |
+| `add-playbook` | Scaffold a new CLI subcommand |
+| `catchup` | Branch activity summary since last contribution |
+
+### Rules (`.ai/rules/`)
+
+Hard constraints all agents must follow:
+
+| Rule | Scope |
+|------|-------|
+| `ansible-conventions` | Playbook/role naming, FQCN, metadata requirements |
+| `podman-secrets` | Secret naming conventions and required labels |
+| `testing-conventions` | Test file naming, fixture usage, patterns |
+| `safety` | Destructive command blocklist, production awareness |
+| `project-structure` | Canonical directory layout reference |
+
+### Skills (`.ai/skills/`)
+
+Domain knowledge references (each has `SKILL.md` and optional `references/`):
+
+| Skill | Domain |
+|-------|--------|
+| `obsah-metadata` | `metadata.obsah.yaml` schema deep reference |
+| `podman-quadlets` | Podman quadlets, images, systemd integration |
+| `foreman-ecosystem` | Foreman, Katello, Pulp, Candlepin, Smart Proxy |
+| `ansible-collections` | Galaxy collections, installation, FQCN usage |
+| `certificate-management` | Certificate sources, roles, and configuration |
+
+## Development Setup
+
+```bash
+./setup-environment
+source .venv/bin/activate
+```
+
+This creates a virtualenv and installs all dependencies including ansible-core 2.16+.
+
+## Common Commands
+
+### Development Environment
+
+```bash
+# Start development VM
+./forge vms start
+
+# Deploy Foreman in development mode
+./foremanctl deploy --foreman-initial-admin-password=changeme --tuning development
+
+# Stop development VM
+./forge vms stop
+```
+
+### Testing
+
+```bash
+# Run all tests (requires a deployed environment)
+./forge test
+
+# Run smoker tests
+./forge smoker
+
+# Run specific test file
+python -m pytest tests/foreman_test.py -vv
+
+# Run tests with specific configuration
+python -m pytest --certificate-source=installer --database-mode=external
+```
+
+Tests use pytest with testinfra and connect to VMs via SSH. The test playbook (`development/playbooks/test/test.yaml`) generates `.tmp/ssh-config` from the Ansible inventory before running pytest.
+
+See [docs/developer/testing.md](docs/developer/testing.md) for the full testing guide.
+
+### Linting
+
+```bash
+# Run ansible-lint (configured in .ansible-lint)
+cd src; ansible-lint
+cd development; ansible-lint
+```
+
+### Building
+
+```bash
+# Build distribution tarball
+make dist
+
+# Build collections (automatically happens as part of dist)
+make build/collections/foremanctl
+make build/collections/forge
+```
+
+## Architecture
+
+### obsah Integration
+
+Both `foremanctl` and `forge` are bash wrappers that set environment variables and execute `obsah`.
+
+The key difference:
+
+- `foremanctl`: Uses `src/` as data directory, targets production deployment
+- `forge`: Uses `development/` as data directory, includes development-specific playbooks
+
+obsah playbooks are discovered via `metadata.obsah.yaml` files which define:
+
+- Command-line parameters and validation
+- Help text
+- Variable definitions with choices and types
+- Included sub-playbooks
+
+See [docs/developer/playbooks-and-roles.md](docs/developer/playbooks-and-roles.md) for the full playbook and role guide.
+
+### Playbook Organization
+
+**Production playbooks** (`src/playbooks/`):
+
+- `deploy/` - Main deployment playbook
+- `checks/` - System requirement checks
+- `features/` - Feature management
+- `pull-images/` - Container image pulling
+- Prefixed with `_` - Internal/included playbooks (e.g., `_certificate_source`, `_database_mode`, `_tuning`, `_flavor_features`)
+
+**Development playbooks** (`development/playbooks/`):
+
+- `vms/` - VM lifecycle management
+- `test/` - Test execution
+- `smoker/` - Smoker test execution
+- `deploy-dev/` - Development deployment variations
+- `security/`, `sos/`, `lock/` - Utilities
+
+### Roles
+
+Roles in `src/roles/` correspond to services and deployment stages:
+
+- Service roles: `foreman`, `pulp`, `candlepin`, `postgresql`, `redis`, `httpd`
+- Feature roles: `hammer`, `foreman_proxy`
+- Infrastructure: `certificates`, `systemd_target`
+- Checks: `check_hostname`, `check_database_connection`, `check_system_requirements`, `check_subuid_subgid`
+- Lifecycle: `pre_install`, `post_install`
+
+### Configuration System
+
+Configuration is managed through:
+
+1. **Vars files** (`src/vars/`):
+   - `defaults.yml` - Base defaults
+   - `flavors/` - Deployment flavors (currently only `katello.yml`)
+   - `tuning/` - Resource profiles (default, development, medium, large, extra-large, extra-extra-large)
+   - `images.yml` - Container image references
+   - `database.yml`, `foreman.yml` - Service-specific configuration
+
+2. **Podman secrets**: Configuration files and credentials are stored as Podman secrets following naming conventions:
+   - Config files: `<role_namespace>-<filename>-<extension>` or `<role_namespace>-<app>-<filename>-<extension>`
+   - Strings: `<role_namespace>-<descriptive_name>` or `<role_namespace>-<app>-<descriptive_name>`
+   - All secrets include labels: `filename`, `app`
+
+View secrets with:
+
+```bash
+podman secret ls
+podman secret inspect --showsecret --format "{{.SecretData}}" <secret-name>
+```
+
+### Custom Plugins
+
+- `src/callback_plugins/foremanctl.py` - Ansible callback plugin for foremanctl-specific output
+- `src/filter_plugins/foremanctl.py` - Custom Jinja2 filters
+
+### Features and Flavors
+
+Features are modular capabilities that can be enabled. See [docs/developer/how-to-add-a-feature.md](docs/developer/how-to-add-a-feature.md) for the complete feature development guide.
+
+Current features:
+
+- `hammer` - CLI tool
+- `foreman-proxy` - Smart proxy functionality
+- `remote-execution` - Remote execution via SSH
+- `google` - Google Compute Engine integration
+- `azure-rm` - Azure Resource Manager integration
+- `katello` - Content and subscription management
+
+Flavors define the base feature set:
+
+- `katello` - Currently the only flavor (Foreman 3.18 + Katello 4.20 + Pulp 3.85 + Candlepin 4.6)
+
+The `enabled_features` variable is computed as: `flavor_features + features`
+
+### Deployment Variables
+
+Key deployment parameters:
+
+- `certificate_source` - Where certificates come from (`default`, `installer`)
+- `database_mode` - Database deployment (`internal`, `external`)
+- `tuning` - Resource allocation profile
+- `flavor` - Base feature set
+- `foreman_initial_admin_username/password` - Initial admin credentials
+- `foreman_puma_workers` - Puma worker count
+- `pulp_worker_count` - Pulp worker count (defaults to min(8, CPU cores))
+
+## Testing Architecture
+
+Tests use pytest with testinfra for infrastructure testing. Key fixtures in `tests/conftest.py`:
+
+- `server_hostname`, `server_fqdn` - Default to `quadlet` / `quadlet.example.com`
+- `client_hostname`, `client_fqdn` - Default to `client` / `client.example.com`
+- `certificates` - Certificate configuration based on `--certificate-source`
+- SSH configuration generated from Ansible inventory at `.tmp/ssh-config`
+
+Test files follow the pattern `tests/<component>_test.py` and use testinfra's server fixture to execute commands and check system state.
+
+## Build System
+
+The Makefile handles:
+
+- Building the distribution tarball (includes git archive + collections)
+- Installing Ansible collections into `build/collections/foremanctl` and `build/collections/forge`
+- Collections are installed from `src/requirements-lock.yml` (preferred) or `src/requirements.yml`
+
+## Inventories
+
+Three inventory configurations:
+
+- `localhost` - Local deployment
+- `local_vagrant` - Vagrant-managed local VMs
+- `broker.py` - Dynamic inventory script
+
+## Developer Documentation
+
+Additional developer guides (from PR [#435](https://github.com/theforeman/foremanctl/pull/435)):
+
+- [How to Add a Feature](docs/developer/how-to-add-a-feature.md) -- end-to-end feature development
+- [Playbooks and Roles](docs/developer/playbooks-and-roles.md) -- playbook structure, naming, metadata
+- [Testing](docs/developer/testing.md) -- test infrastructure, fixtures, patterns
+- [Deployment Design](docs/developer/deployment.md) -- deployment architecture
+- [Container Image Builds](docs/developer/container-image-builds.md) -- image naming, registries
+- [Development Environment](docs/developer/development-environment.md) -- dev setup with git Foreman
+
+## Git Workflow
+
+Current branch: `ls/ai`
+Main branch: `master`