update docs to the new yaml format

adventures/planned/00-lex-imperfecta/docs/beginner.yaml

@@ -0,0 +1,154 @@
+level: beginner
+emoji: 🟢
+title: The Twelve Tables
+devcontainer: lex-imperfecta_beginner
+community_url: "" # TODO
+
+summary: Fix broken Kyverno policies to restore proper admission control.
+
+audience: >-
+  Platform engineers, SREs, and developers curious about Kubernetes security — no prior Kyverno experience needed,
+  but familiarity with basic `kubectl` and YAML will help.
+
+backstory:
+  - >-
+    The Republic's legal scholars have been busy — perhaps too busy. In their haste to codify the Twelve Tables, the 
+    foundation of the Republic's legal system, they introduced errors that now threaten the city's order. Workloads 
+    that should be blocked are running freely, and workloads that should be allowed are being turned away at the gates.
+  - >-
+    Another scholar left a note: "I tried to set up policies for privileged containers and required labels, but 
+    something's off — I can't figure out why the wrong things are getting through. There was also supposed to be a 
+    system for automatically issuing travel permits to foreign visitors, but that one is broken too."
+  - >-
+    Your mission: investigate the Kyverno policies and restore proper admission control before chaos reaches the city.
+
+objective:
+  - >-
+    All workloads **missing the `republic.rome/gens` label** blocked at admission with a clear policy violation message
+  - >-
+    All workloads **running as privileged containers** blocked at admission with a clear policy violation message
+  - >-
+    All pods declaring **`republic.rome/traveler: peregrinus`** automatically receiving the **`republic.rome/travel-permit: granted`** label
+  - >-
+    Confirmed that **all other workloads** deploy and run successfully in the cluster
+
+what_you_learn:
+  - >-
+    How Kyverno [`ValidatingPolicy`](https://kyverno.io/docs/policy-types/validating-policy/) resources and 
+    [CEL validation expressions](https://kubernetes.io/docs/reference/using-api/cel/) work
+  - >-
+    The difference between [`Audit`, `Deny`, and `Warn`](https://kyverno.io/docs/policy-types/validating-policy/)
+    validation actions
+  - >-
+    How to use [custom label keys](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to 
+    enforce workload identity standards
+  - >-
+    How Kyverno [`MutatingPolicy`](https://kyverno.io/docs/policy-types/mutating-policy/) resources automatically 
+    patch incoming workloads at admission
+
+architecture:
+  - >-
+    The defining principle of the Twelve Tables was that Roman law was enforced **at the gates** — before a citizen 
+    could act, not after the damage was done. Kubernetes admission control works exactly the same way: Kyverno 
+    intercepts every request to create or update a workload and checks it against your policies *before* it reaches the 
+    cluster. A misconfigured policy doesn't just fail to enforce — it fails silently, letting non-compliant workloads
+    slip through unnoticed while you assume everything is fine.
+  - >-
+    That's the situation you've inherited. Your Codespace comes with a Kubernetes cluster and Kyverno pre-installed. 
+    Three policies are already deployed — two `ValidatingPolicy` resources that validate workloads, and one 
+    `MutatingPolicy` that automatically stamps incoming pods with the right labels. All three are misconfigured. 
+    The policies live in `manifests/policies/`. You will edit them directly and re-apply with `kubectl`.
+  - >-
+    The pods in `manifests/pods/` are there for reference only — **you don't need to edit them**.
+  - >-
+    No GitOps, no dashboards — just you, the policies, and the cluster.
+
+toolbox:
+  - name: kubectl
+    url: "https://kubernetes.io/docs/reference/kubectl/"
+    description: Apply and inspect cluster resources
+  - name: kyverno CLI
+    url: "https://kyverno.io/docs/kyverno-cli/"
+    description: Test and lint policies locally before applying
+  - name: k9s
+    url: "https://k9scli.io/"
+    description: Explore cluster resources in a terminal UI
+
+services: []
+
+how_to_play:
+  - id: explore
+    title: "Explore the Cluster"
+    content: |
+      When your Codespace is ready, four pods are already running — or trying to. Open a terminal and check what's going on:
+
+      ```bash
+      kubectl get pods
+      ```
+
+      Inspect why a pod was blocked or admitted:
+
+      ```bash
+      kubectl describe pod <pod-name>
+      ```
+
+      Check the policies that are in place:
+
+      ```bash
+      kubectl get validatingpolicies
+      kubectl get validatingpolicy require-labels -o yaml
+      kubectl get validatingpolicy no-privileged-containers -o yaml
+
+      kubectl get mutatingpolicies
+      kubectl get mutatingpolicy stamp-travel-permit -o yaml
+      ```
+
+      You can also launch **k9s** for a terminal UI view of all cluster resources:
+
+      ```bash
+      k9s
+      ```
+
+      Navigate to `ValidatingPolicy` resources with `:validatingpolicies` and `MutatingPolicy` resources with `:mutatingpolicies` to inspect all three policies.
+  - id: fix-policies
+    title: Fix the Policies
+    content: |
+      Review the [Objective](#objective) and investigate what's wrong in `manifests/policies/`.
+
+      All three broken policies are in `manifests/policies/`. Read them carefully — each has a different kind of misconfiguration.
+
+      **Test Locally with the Kyverno CLI**
+
+      Before applying to the cluster, you can use the `kyverno` CLI to test your policy changes locally against the workload manifests:
+
+      ```bash
+      kyverno apply manifests/policies/require-labels.yaml --resource manifests/pods/missing-labels.yaml
+      kyverno apply manifests/policies/no-privileged-containers.yaml --resource manifests/pods/privileged.yaml
+      kyverno apply manifests/policies/stamp-travel-permit.yaml --resource manifests/pods/peregrinus.yaml
+      ```
+
+      This gives you fast feedback without touching the cluster.
+
+      **Apply to the Cluster**
+
+      Once you're happy with your changes, re-apply everything:
+
+      ```bash
+      make apply
+      ```
+
+      This re-applies the policies and re-deploys all workloads so you immediately see the effect of your changes.
+
+helpful_links:
+  - title: Kyverno ValidatingPolicy
+    url: "https://kyverno.io/docs/policy-types/validating-policy/"
+    description: Reference docs for ValidatingPolicy — the resource type you'll fix to block non-compliant workloads
+  - title: Kyverno MutatingPolicy
+    url: "https://kyverno.io/docs/policy-types/mutating-policy/"
+    description: Reference docs for MutatingPolicy — the resource type you'll fix to auto-stamp travel permits
+  - title: CEL Validation Expressions
+    url: "https://kubernetes.io/docs/reference/using-api/cel/"
+    description: How CEL expressions work in Kubernetes admission — what you'll write inside the policy rules
+  - title: Kyverno Playground
+    url: "https://playground.kyverno.io"
+    description: Test your CEL expressions interactively against sample resources before applying them to the cluster

adventures/planned/00-lex-imperfecta/docs/index.yaml

@@ -0,0 +1,21 @@
+slug: lex-imperfecta
+name: "Lex Imperfecta"
+emoji: "⚖️"
+
+tags:
+  - Kyverno
+  - Kubernetes
+
+backstory:
+  - The Roman Republic has built a sophisticated legal system to protect its citizens — but the laws were written in haste, and the exceptions were written too generously. Policies go unenforced, the wrong citizens are exempt, and something has slipped through the gates unnoticed. As a newly appointed Praetor, your mission is to restore order before chaos takes hold.
+
+overview:
+  - The Republic's legal system is in disarray — workloads run unchecked, required labels go missing, and privileged containers slip through the gates. As a newly appointed Praetor, your mission is to restore order by fixing broken Kyverno policies and enforcing proper admission control.
+
+rewards:
+  deadline: "TODO"
+  tiers:
+    - label: "1st place"
+      description: "50% voucher for a Linux Foundation certification"
+    - label: "Top 3"
+      description: "Credly badge to showcase the achievement"