docs: add Podman rootless mode instructions to CONTAINER.md

.github/workflows/container-test.yml

@@ -0,0 +1,53 @@
+name: Container Tests (Podman Rootless)
+
+on:
+  pull_request:
+    paths:
+      - 'CONTAINER.md'
+      - 'Containerfile.scratch'
+      - '.github/workflows/container-test.yml'
+  workflow_dispatch:
+
+jobs:
+  podman-rootless-test:
+    name: Podman Rootless Mode Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Create test directories
+        run: mkdir -p ${{ github.workspace }}/test-reports
+
+      - name: Pull AgentReady container
+        run: podman pull ghcr.io/ambient-code/agentready:latest
+
+      - name: Run assessment with Podman rootless command
+        run: |
+          podman run --rm \
+            --user $(id -u):$(id -g) \
+            --userns=keep-id \
+            -e GIT_CONFIG_COUNT=1 \
+            -e GIT_CONFIG_KEY_0=safe.directory \
+            -e GIT_CONFIG_VALUE_0=/repo \
+            -v ${{ github.workspace }}:/repo:ro,z \
+            -v ${{ github.workspace }}/test-reports:/reports:z \
+            ghcr.io/ambient-code/agentready:latest \
+            assess /repo --output-dir /reports
+
+      - name: Verify reports generated
+        run: |
+          echo "=== Generated Reports ==="
+          ls -la ${{ github.workspace }}/test-reports/
+          ls ${{ github.workspace }}/test-reports/*.json
+          ls ${{ github.workspace }}/test-reports/*.html
+          ls ${{ github.workspace }}/test-reports/*.md
+
+      - name: Upload test reports
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: podman-rootless-test-reports
+          path: ${{ github.workspace }}/test-reports/
+          retention-days: 30

CONTAINER.md

@@ -119,6 +119,48 @@ docker run --rm \
   assess /repo --output-dir /reports
 ```
 
+## Podman Rootless Mode
+
+On **rootless Podman** (common on Fedora, RHEL, CentOS), additional flags are required to handle SELinux labeling, UID mapping, and Git security checks.
+
+### Complete Command
+
+```bash
+podman run --rm -it \
+  --user $(id -u):$(id -g) \
+  --userns=keep-id \
+  -e GIT_CONFIG_COUNT=1 \
+  -e GIT_CONFIG_KEY_0=safe.directory \
+  -e GIT_CONFIG_VALUE_0=/repo \
+  -v /path/to/repo:/repo:ro,z \
+  -v /path/to/reports:/reports:z \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+```
+
+### Why These Flags?
+
+| Flag | Purpose |
+|------|---------|
+| `--userns=keep-id` | Maps container UID to match your host UID, fixing permission mismatches |
+| `--user $(id -u):$(id -g)` | Runs the container process as your host user |
+| `GIT_CONFIG_*` | Tells Git to trust the mounted `/repo` directory (required for Git 2.35.2+) |
+| `:z` (lowercase) | SELinux shared label - allows container access to mounted volumes |
+
+### When Do I Need This?
+
+Use the rootless Podman command if you encounter any of these errors:
+
+- `Path '/repo' is not readable` (SELinux blocking access)
+- `SHA is empty, possible dubious ownership` (Git security check)
+- `PermissionError: [Errno 13] Permission denied` (UID mismatch)
+
+### Note on SELinux Labels
+
+- Use `:z` (lowercase) for shared volumes that multiple containers may access
+- Use `:Z` (uppercase) for private volumes exclusive to one container
+- Both options relabel the volume for SELinux access
+
 ## CI/CD Integration
 
 ### GitHub Actions
@@ -195,16 +237,35 @@ Without the `-v ~/agentready-reports:/reports` mount, reports written to `/tmp`
 
 ### Permission denied on mounted volumes
 
-Add SELinux context (`:Z` flag) on SELinux systems:
+**On rootless Podman** (Fedora, RHEL, CentOS), see the [Podman Rootless Mode](#podman-rootless-mode) section for the complete solution.
+
+**Quick fix for SELinux only** - add the `:z` label to volumes:
 
 ```bash
 podman run --rm \
-  -v $(pwd):/repo:ro,Z \
-  -v $(pwd)/agentready-reports:/reports,Z \
+  -v $(pwd):/repo:ro,z \
+  -v $(pwd)/agentready-reports:/reports:z \
   ghcr.io/ambient-code/agentready:latest \
   assess /repo --output-dir /reports
 ```
 
+### Git "dubious ownership" error
+
+If you see `SHA is empty, possible dubious ownership`, the container's Git doesn't trust the mounted repository. Add Git safe.directory configuration:
+
+```bash
+podman run --rm \
+  -e GIT_CONFIG_COUNT=1 \
+  -e GIT_CONFIG_KEY_0=safe.directory \
+  -e GIT_CONFIG_VALUE_0=/repo \
+  -v $(pwd):/repo:ro \
+  -v $(pwd)/agentready-reports:/reports \
+  ghcr.io/ambient-code/agentready:latest \
+  assess /repo --output-dir /reports
+```
+
+For the complete solution addressing all rootless Podman issues, see [Podman Rootless Mode](#podman-rootless-mode).
+
 ## Links
 
 - **Container Registry**: https://github.com/ambient-code/agentready/pkgs/container/agentready