linuxmalaysia · linuxmalaysia · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -38,4 +38,80 @@ It follows a strict **"Measure, Harden, Re-Measure"** workflow.
 
 ---
 
+## 🌌 Google Antigravity & Google Jules Agent Skills
+
+### Location & Structure
+
+Project operational and domain-specific knowledge is represented using Google Antigravity-compatible Agent Skills. These are placed inside the `.agents/skills/` directory.
+
+Each skill is self-contained in its own directory (e.g., `.agents/skills/<skill-folder>/`) and contains a `SKILL.md` file. Each `SKILL.md` includes OKF v0.1 YAML frontmatter and a standard Deep State of Mind (DSOM) AI Protocol footer, bridging Google Jules and Antigravity capabilities.
+
+### Available Agent Skills
+
+The following table lists the available agent skills present in this repository:
+
+| Skill Directory | Skill Name | Description |
+| :--- | :--- | :--- |
+| `ai-agent-instructions` | `ai-agent-instructions` | Direct instruction file matching for copilot/cursor/cline/windsurf configurations. |
+| `ansible-boolean-conditionals` | `ansible-boolean-conditionals` | Guides on writing boolean conditionals in Ansible. |
+| `ansible-fqcn-idempotency` | `ansible-fqcn-idempotency` | Standards for Fully Qualified Collection Names (FQCN) and task idempotency. |
+| `ansible-galaxy-roles` | `ansible-galaxy-roles` | Instructions for managing and installing Ansible Galaxy external role dependencies. |
+| `ansible-testing-linting` | `ansible-testing-linting` | Guidelines on running ansible-playbook syntax checks and ansible-lint. |
+| `asimp-core-workflow` | `asimp-core-workflow` | Highlights Phase 1, Phase 2, and Phase 3 of the core ASIMP workflow. |
+| `jekyll-docs-deployment` | `jekyll-docs-deployment` | Procedures for pre-processing docs and managing GitHub Pages deployments. |
+| `jinja2-template-overrides` | `jinja2-template-overrides` | Rules for setting Jinja2 block trim headers with capitalized booleans. |
+| `jules-sandbox-mode` | `jules-sandbox-mode` | Handling of sandboxed, unprivileged execution environments. |
+| `ubuntu-scap-auditing` | `ubuntu-scap-auditing` | Guides on running SCAP scanner, fetching latest datastreams, and checking USN OVAL. |
+
+### Deep State of Mind (DSOM) Protocol
+
+The DSOM AI Protocol aligns agent-specific operational rules, linking local skill folders with central platform standards. Every `.agents/skills/<skill-folder>/SKILL.md` ends with a DSOM JSON block stating its synchronization status and signature, ensuring complete spatial alignment between Jules and human operators.
+
+---
+
+## 🔒 Google Jules Sandbox Limitations & Compatibility Standards
+
+### ⚠️ Google Jules Sandbox Constraints & Sudo Correction
+
+Although the `jules` user is configured with passwordless `sudo` privileges via `(ALL : ALL) NOPASSWD: ALL` inside the sandbox, virtualization limits prevent modifying host kernel settings or controlling restricted system services.
+- **Kernel & Configuration Restrictions**: Modifying `/etc/sysctl.conf` or loading custom kernel modules is blocked.
+- **Service Controls**: Managing container-restricted services such as `auditd`, `chrony`, `firewalld`, `autofs`, or `clamav` will fail or hang.
+- **Upgrade Operations**: Deep system package upgrades like `apt upgrade` or `dnf upgrade` can stall or consume excessive resources.
+- **Integrity Verifiers**: Running file verifications like `debsums` is restricted on sandbox file structures.
+
+### 📜 Mandatory Playbook Compliance Standard
+
+To run successfully under any context, all playbooks must dynamically detect the execution environment and adjust behavior:
+- **Environment Detection**: Detect the Google Jules sandbox by checking if `/home/jules` exists. Set the `is_sandbox_jules` fact accordingly.
+- **Conditional Enforcement & Privilege Scaling**: Set `asimp_privilege_level` to `'limited'` when running in sandboxes or without full root permissions, and to `'full'` on real unconstrained operating systems.
+  - **Limited/Sandbox Mode**: Run in non-destructive, audit/test/info mode only. Bypasses package upgrades, heavy downloads, and skips system-level remediation roles.
+  - **Real OS Mode**: run full-throttle remediations, package upgrades, and auditing with full privileges.
+- **Pre-Remediation Safety & Break-Prevention Verification**: When `asimp_privilege_level == 'full'`, the playbook must execute rigorous pre-remediation safety checks before hardening. These checks assert SSH syntax checks (`sshd -t`), root space availability, and `/etc/fstab` health to ensure that remediation tasks will not break the host system or active project codes.
+
+---
+
+## 🛠️ Code Conventions & File Hierarchy
+
+To maintain the high-fidelity auditability of ASIMP, developers and agents must adhere to the following file conventions:
+- Use Fully Qualified Collection Names (FQCN) for all tasks.
+- Avoid deprecated features and ensure strict idempotency of every command/shell execution.
+- Maintain standardized layouts for documentation and playbook structures.
+
+---
+
+## 📖 Google Open Knowledge Format (OKF) v0.1 Specification
+
+All documentation within this repository conforms to the Google Open Knowledge Format (OKF) v0.1.
+
+### 📐 Required Frontmatter Fields
+
+Every Markdown file must begin with a YAML frontmatter block containing:
+1. `okf_version`: Declaring `"0.1"`.
+2. `type`: File category (e.g., `instructions`, `documentation`).
+3. `title`: Page header string.
+4. `timestamp`: ISO-8601 creation/modification time.
+5. `topics`: A list of relevant tags or keywords.
+
+---
+
 ASIMP (Ansible System Integrity Management Platform) | Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-07-12 Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0 | [Legal Notice & Disclaimer](https://linuxmalaysia.github.io/ASIMP/legal-notice.html)
diff --git a/ansible.cfg b/ansible.cfg
@@ -20,7 +20,7 @@ transport = ssh
 # Don't gather host facts at the start of each play if they've already been gathered
 gathering = smart
 
-# Standardize output callback format for high-fidelity human audit of deployment/auditing steps (ansible-core 2.13+)
+# Standardize output callback for high-fidelity human audit of deployment/auditing steps
 callback_result_format = yaml
 bin_ansible_callbacks = True
 

diff --git a/docs/ansible_fqcn.md b/docs/ansible_fqcn.md
@@ -0,0 +1,103 @@
+---
+okf_version: "0.1"
+layout: default
+type: documentation
+title: "Ansible Best Practices & FQCN Standards"
+timestamp: "2026-08-05T12:00:00Z"
+topics: [asimp, ansible, fqcn, idempotency, best-practices]
+---
+
+
+# Ansible Best Practices & FQCN Standards
+
+Modern Ansible requires highly scalable, predictable, and idempotent playbooks. To prevent collisions, version drift, and deprecation warnings, ASIMP enforces strict development standards, mandating **Fully Qualified Collection Names (FQCN)** and **Explicit Task Idempotency**.
+
+---
+
+## 🧭 Fully Qualified Collection Names (FQCN)
+
+All playbooks, roles, and tasks in ASIMP must utilize fully qualified collection paths when invoking Ansible modules. Short, unqualified names (e.g., `apt`, `copy`, `shell`) are strictly prohibited.
+
+| Legacy Module Name | Mandatory FQCN Replacement |
+| :--- | :--- |
+| `apt` | `ansible.builtin.apt` |
+| `copy` | `ansible.builtin.copy` |
+| `shell` | `ansible.builtin.shell` |
+| `command` | `ansible.builtin.command` |
+| `replace` | `ansible.builtin.replace` |
+
+Using FQCN ensures playbooks remain robust across varying Ansible versions and executing environments.
+
+---
+
+## 🛡️ Symmetric Privilege Strategy
+
+ASIMP implements a hybrid, symmetric privilege model that separates global system tuning from unprivileged deployment or auditing steps:
+
+1. **Rootful OS Hardening**: Applied only when `asimp_privilege_level == 'full'`. This installs system utilities, modifies kernel sysctls, and enforces security configurations.
+2. **Rootless Auditing**: Executed dynamically under `become_user` or within simulated fallback loops inside Google Jules sandboxes (`is_sandbox_jules: true`).
+
+---
+
+## 📄 FQCN Ansible Task Blueprint
+
+Below is an example of production-grade task construction demonstrating proper FQCN syntax and explicit environment variables for rootless systemd execution:
+
+```yaml
+- name: Create Quadlet configuration directory
+  ansible.builtin.file:
+    path: "/home/songket/.config/containers/systemd"
+    state: directory
+    owner: songket
+    group: songket
+    mode: '0755'
+  become: yes
+  become_user: songket
+
+- name: Deploy Quadlet templates
+  ansible.builtin.template:
+    src: "templates/{{ item }}.j2"
+    dest: "/home/songket/.config/containers/systemd/{{ item }}"
+    owner: songket
+    group: songket
+    mode: '0644'
+  loop:
+    - skm_network.network
+    - skm_pod.pod
+  become: yes
+  become_user: songket
+  register: quadlets_deployed
+
+- name: Reload user-level systemd daemon and restart services
+  ansible.builtin.systemd_service:
+    daemon_reload: yes
+    scope: user
+    name: skm_pod-pod.service
+    state: restarted
+    enabled: yes
+  become: yes
+  become_user: songket
+  environment:
+    XDG_RUNTIME_DIR: "/run/user/{{ songket_uid | default(2001) }}"
+    DBUS_SESSION_BUS_ADDRESS: "unix:path=/run/user/{{ songket_uid | default(2001) }}/bus"
+  when: quadlets_deployed.changed
+```
+
+---
+
+## 🔍 Task Idempotency and Change Verification
+
+By default, executing shell or command modules always registers a "changed" state. Every shell or command task inside ASIMP must explicitly define `changed_when` or `failed_when` conditions to maintain high-fidelity change tracking.
+
+```yaml
+# INCORRECT (Will always report changed)
+- name: Check file existence
+  ansible.builtin.command: ls /var/log/asimp-baseline-scores.json
+
+# CORRECT (Strictly idempotent check)
+- name: Check file existence
+  ansible.builtin.command: ls /var/log/asimp-baseline-scores.json
+  register: file_check
+  changed_when: false
+  failed_when: false
+```
diff --git a/docs/ansible_playbook_map.md b/docs/ansible_playbook_map.md
@@ -0,0 +1,53 @@
+---
+okf_version: "0.1"
+layout: default
+type: documentation
+title: "Ansible Playbook and Document Architecture Map"
+timestamp: "2026-08-05T12:00:00Z"
+topics: [asimp, playbook, roles, architecture, mapping]
+---
+
+
+# Ansible Playbook and Document Architecture Map
+
+A cohesive architectural dictionary linking automated playbook files with their core roles, unprivileged services, and deployment/operational documentation.
+
+---
+
+## 🧭 Master Playbook and Document Matrix
+
+The following index maps playbooks, roles, and support files in ASIMP to their corresponding documentation sections:
+
+| Playbook / Script | Primary Purpose | Services & Tasks Managed | Related Documentation |
+| :--- | :--- | :--- | :--- |
+| `play.yml` | Multi-host remote execution | Dual-engine baseline checks, upgrades, system hardening, and verification | `docs/openscap.md`, `docs/lynis.md`, `docs/configuration.md` |
+| `play-localhost.yml` | Localhost execution | Hardening and audit on localhost with dynamic privilege level checking | `docs/index.md`, `docs/troubleshooting.md`, `docs/dsom_ansible_review.md` |
+| `playbooks/matrix_test.yml` | Local multi-OS testing matrix | Parallel Podman 5+ container orchestration for Ubuntu, Debian, and AlmaLinux | `docs/local_testing_matrix_spec.md` |
+| `tests/test_*.yml` | Playbook-level regression tests | Validates layout metadata, navbar entries, footers, and execution logic | `docs/local_testing_matrix_spec.md`, `docs/dsom_ansible_review.md` |
+| `scripts/verify_sitemap_links.py` | Pre-merge links validation | Crawls local documents and verifies GitBook links and sitemap integrity | `docs/_layouts/default.html` |
+
+---
+
+## 🛡️ 1. Security Operations: Hardening & Auditing
+
+OS-level security hardening is managed via `play.yml` or `play-localhost.yml`, integrating baseline policy validations alongside preventative break-prevention checks:
+
+```yaml
+# Pre-Remediation Safety Gate Check Block
+- name: Verify no critical risk factors that would break the system
+  ansible.builtin.assert:
+    that:
+      - asimp_risk_level not in ['CRITICAL_RISK', 'HIGH_RISK']
+    fail_msg: "Pre-Remediation Safety Check failed: High risk of system breakage detected. Aborting!"
+```
+
+By validating SSH key status, listening ports, and filesystem availability, the playbook safely drops back to simulations (Audits) in unprivileged containers/Google Jules sandboxes.
+
+---
+
+## 📊 2. Continuous Integration & Local Verification
+
+To guarantee that updates do not introduce package or systemd configuration crashes, diagnostic pipelines are triggered automatically:
+
+- **Continuous Integration (CI/CD)**: `playbooks/matrix_test.yml` spins up sandboxed environments locally to execute syntax checks and structural evaluations.
+- **Developer Feedback Loop**: Test summaries and detailed telemetry are compiled atomically and exported back to developers securely to maintain maximum workspace transparency.
diff --git a/docs/dsom_ansible_review.md b/docs/dsom_ansible_review.md
@@ -7,6 +7,9 @@ timestamp: "2026-08-05T12:00:00Z"
 topics: ["ansible", "dsom", "asimp", "compatibility", "review"]
 ---
 
+
+# Review & Adoption of DSOM Ansible Configuration Guide (v3.6.2)
+
 This document provides a comprehensive structural review and alignment strategy for adopting the **DSOM (Deep State of Mind) Ansible Configuration Guide (v3.6.2)** into the **ASIMP (Ansible System Integrity Management Platform)** repository.
 
 ASIMP is designed as a security hardening and auditing framework. Integrating DSOM's infrastructure guidelines allows ASIMP to align seamlessly with DSOM Ingestion Backbone environments.
@@ -45,7 +48,7 @@ DSOM v3.6.2 enforces a hybrid privilege blueprint:
 
 ---
 
-## 🔐 Sovereign Secrets Injection & Encrypted Secret Handling
+## 🔐 Sovereign Secrets Injection
 
 DSOM utilizes a **Runtime Injection Pattern** to avoid committing credentials:
 

diff --git a/docs/index.md b/docs/index.md
@@ -43,6 +43,11 @@ Explore the different sections of our system design, setup guides, and troublesh
 - **[Lynis Auditing & Playbooks](lynis.html)**: Detailed analysis of how ASIMP conducts host audits, extracts the Hardening Index, and integrates with the `lynis-ansible` hardening role.
 - **[Configuration & Variables](configuration.html)**: Discover customizable variables for our roles (`reporting-ASIMP`, `update-ubuntu-ASIMP`, `lynis-ansible`) and sample inventories.
 - **[Troubleshooting & Fallbacks](troubleshooting.html)**: Read detailed instructions on addressing DataStream resolution errors, connection elevation failures, and timeout behaviors.
+- **[Review & Adoption of DSOM Guide](dsom_ansible_review.html)**: Structural alignment review of the DSOM Ansible Configuration Guide v3.6.2.
+- **[Rootless Podman 5+ & Quadlet Orchestration](podman_rootless.html)**: Overview of rootless orchestration, systemd Quadlets, namespace mappings, and unprivileged container matrix testing.
+- **[Ansible Best Practices & FQCN Standards](ansible_fqcn.html)**: Guidelines for Fully Qualified Collection Names (FQCN), task idempotency checks, and privilege strategies.
+- **[Ansible Playbook and Document Architecture Map](ansible_playbook_map.html)**: Architectural dictionary linking playbook files with their core roles and operational documents.
+- **[Local Knowledge-First & Metadata Discovery](sop_knowledge_first_discovery.html)**: SOP guidelines for unprivileged and agentic spatial discovery and context preservation.
 
 ---
 

diff --git a/docs/local_testing_matrix_spec.md b/docs/local_testing_matrix_spec.md
@@ -1,4 +1,5 @@
 ---
+
 okf_version: "0.1"
 layout: default
 type: documentation

diff --git a/docs/podman_rootless.md b/docs/podman_rootless.md
@@ -0,0 +1,56 @@
+---
+okf_version: "0.1"
+layout: default
+type: documentation
+title: "Rootless Podman 5+ & Quadlet Orchestration"
+timestamp: "2026-08-05T12:00:00Z"
+topics: [asimp, podman, rootless, quadlet, orchestration]
+---
+
+
+# Rootless Podman 5+ & Quadlet Orchestration
+
+In ASIMP, we embrace the security-first principle of unprivileged, rootless workload execution. While typical systems-level security testing frameworks require full superuser privileges, ASIMP separates host OS tuning from target testing environments using **Rootless Podman 5+ & Systemd Quadlets**.
+
+---
+
+## 🧭 Why Rootless Podman 5+ & Quadlets?
+
+Containerized workloads run in parallel to test and verify ASIMP's hardening policies. Legacy architectures rely on rootful Docker daemons, which introduce unnecessary host security exposure. Podman 5+ resolves this by converting unprivileged declarative container specifications directly into native, unprivileged systemd unit files using **Quadlets** (such as `.container`, `.volume`, `.pod`, and `.network` configurations).
+
+This enables containers to be treated natively as standard local system services without daemon overhead.
+
+---
+
+## ⚙️ Unprivileged Environment Mappings
+
+To safely interact with rootless systemd managers, Ansible playbooks must operate under correct environment contexts:
+
+- **`XDG_RUNTIME_DIR`**: Specifies the socket and runtime file storage location. For rootless execution sessions, this defaults to `/run/user/<UID>`.
+- **`DBUS_SESSION_BUS_ADDRESS`**: Directs client requests to the user-level D-Bus message bus socket, typically located at `unix:path=/run/user/<UID>/bus`.
+
+Without these environment variables, systemctl commands executed by Ansible inside unprivileged user blocks will fail with connection errors.
+
+---
+
+## 🔒 Namespace Mapping & the keep-id Strategy
+
+When running rootless containers, Podman maps internal root (UID 0) to the host user's UID (e.g., `2001`). Internal non-root container users (like UID `2001` inside the container) map to high-range subuids on the host. This complicates backup processes and permission management.
+
+ASIMP leverages Podman's **User Namespace Mapping** (`UserNS=keep-id:uid=2001,gid=2001`) at container and pod levels. By provisioning a dedicated unprivileged user on the host and aligning container and host permissions, we preserve storage sovereignty and absolute file permission transparency without root level interventions.
+
+---
+
+## 🔄 Enabling Systemd Lingering
+
+By default, user-level systemd managers terminate when the user logs out. To allow background containers and unprivileged scanning services to survive sessions and launch on system start, lingering must be enabled:
+
+```yaml
+- name: Enable systemd lingering for songket user
+  ansible.builtin.command:
+    cmd: "loginctl enable-linger songket"
+    creates: "/var/lib/systemd/linger/songket"
+  become: yes
+```
+
+This guarantees seamless, high-performance background execution for our unprivileged testing matrix under any context.