[BUG] Agent Ready Container mode execution instructions misses some key details

[kami619]

Bug Description

The recommended container execution command fails on systems running Podman in rootless mode, particularly on Enterprise Linux distributions (Fedora, RHEL, CentOS) or systems with non-standard User IDs (UIDs). The issues stem from SELinux labeling, volume permission mismatches between host and container users, and Git's "dubious ownership" security check.

To Reproduce

Steps to reproduce the behavior:

1. Use a system with Podman installed and SELinux enabled.
2. Ensure your host User ID is not 1001 (e.g., a corporate LDAP/SSSD account with a high UID).
3. Run the recommended command:
   podman run --rm -it -v $(pwd):/repo:ro -v $(pwd)/reports:/reports ghcr.io/ambient-code/agentready:latest assess /repo --output-dir /reports
4. See errors:

• First: Path '/repo' is not readable (SELinux)
• Second: SHA is empty, possible dubious ownership (Git security)
• Third: PermissionError: [Errno 13] Permission denied when writing to /reports (UID mismatch)

Expected Behavior

The container should be able to read the mounted repository, verify the Git state, and write the output JSON/HTML reports to the mounted volume without manual UID remapping or permission changes on the host.

Actual Behavior

The process fails at multiple stages due to host-container isolation boundaries. The container's internal user (agentready:1001) cannot interact with host files owned by the user (e.g., 123123123).

Environment

• OS: Fedora / RHEL (Podman environment)
• Version: latest
• Python Version: 3.12 (inside container)

Additional Context

In rootless Podman, the internal user 1001 does not automatically have permission to write to host volumes unless the UIDs are aligned or the volumes are relabeled. Furthermore, Git 2.35.2+ prevents operations on repositories where the current user doesn't match the owner of the .git folder.

Possible Solution

The documentation should be updated to include a "Podman/Rootless" version of the command. The following flags resolve the issues:

1. :z: Relabels the volume for SELinux.
2. **--userns=keep-id and --user $(id -u):$(id -g)**: Aligns the container user with the host user to fix PermissionError.
3. GIT_CONFIG env vars: Tells the internal Git binary to trust the /repo path.

Proposed updated command for Podman users:

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

[kami619]

This particular command worked without any issue.

$ 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 /home/kakella/code/opendatahub-tests:/repo:ro,z \
  -v /home/kakella/agentready-reports:/reports:z \
  ghcr.io/ambient-code/agentready:latest assess /repo --output-dir /reports

Assessment complete!
  Score: 56.3/100 (Bronze)
  Assessed: 24
  Skipped: 1
  Total: 25
  Duration: 1.1s

Assessment Results:
----------------------------------------------------------------------------------------------------
Test Name                           Test Result    Notes                         
----------------------------------------------------------------------------------------------------
architecture_decisions              ❌ FAIL         no ADR directory (need: ADR directory with deci...
branch_protection                   ⏭️ NOT_APPLICABLE Requires GitHub API integration for branch prot...
cicd_pipeline_visibility            ❌ FAIL         basic config (need: CI with best practices)
claude_md_file                      ❌ FAIL         missing (need: present)       
code_smells                         ✅ PASS         67/100                        
concise_documentation               ❌ FAIL         16 lines, 4 headings, 0 bullets (need: <500 lin...
container_setup                     ✅ PASS         60/100                        
conventional_commits                ❌ FAIL         not configured (need: configured)
cyclomatic_complexity               ✅ PASS         100/100                       
dependency_security                 ❌ FAIL         Security tools configured: detect-secrets, gitl...
file_size_limits                    ❌ FAIL         1 huge, 20 large out of 353 (need: <5% files >5...
gitignore_completeness              ✅ PASS         83/100                        
inline_documentation                ❌ FAIL         45.8% (need: ≥80%)            
issue_pr_templates                  ❌ FAIL         PR:False, Issues:0 (need: PR template + ≥2 issu...
lock_files                          ✅ PASS         100/100                       
one_command_setup                   ❌ FAIL         multi-step setup (need: single command)
openapi_specs                       ❌ FAIL         no OpenAPI spec (need: OpenAPI 3.x spec present)
precommit_hooks                     ✅ PASS         100/100                       
readme_structure                    ❌ FAIL         2/3 sections (need: 3/3 sections)
semantic_naming                     ✅ PASS         97/100                        
separation_of_concerns              ❌ FAIL         organization:100, cohesion:94, naming:0 (need: ...
standard_layout                     ❌ FAIL         1/2 directories (need: 2/2 directories)
structured_logging                  ❌ FAIL         not configured (need: structured logging library)
test_coverage                       ❌ FAIL         not configured (need: configured with >80% thre...
type_annotations                    ✅ PASS         100/100                       
----------------------------------------------------------------------------------------------------

Reports generated:
  JSON: /reports/assessment-20260121-193718.json
  HTML: /reports/report-20260121-193718.html
  Markdown: /reports/report-20260121-193718.md