agentleFS
moeru-aimoeru-ai/auv/.agents/skills/auv-wayland-rendering/SKILL.md

auv-wayland-rendering

Skill207 starsChanged 37 days agoApache-2.0View on GitHub

Prepare, diagnose, and validate Linux GPU and Wayland environments for AUV rendering and capture through XDG Desktop Portal and PipeWire. Use when installing AUV desktop runtime dependencies, connecting from another machine over SSH, using an existing compositor or a headless wlroots/Sway session, checking hardware versus software rendering, running display.capture or Linux driver probes, exposing optional WayVNC safely, or troubleshooting blank frames and Wayland, portal, D-Bus, PipeWire, or session-environment failures.

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. About 0 are common, 16 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈16

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep ownership explicit: the compositor renders application clients.

    line 12
  2. Distinctive:

    Read setup.md before installing packages, creating a compositor session, or configuring remote viewing.

    line 18
  3. Distinctive:

    Read troubleshooting.md when a probe or capture fails, the image is blank, or hardware rendering is uncertain.

    line 20
  4. Very specific:

    Check AUV's current support matrix before describing a result as supported.

    line 22
  5. Distinctive:

    Run the read-only probe in the target shell:

    line 30
  6. Very specific:

    Add --require-gpu to make missing GPU prerequisites fatal when hardware rendering is required.

    line 36
  7. Very specific:

    Do not infer GPU rendering from the presence of a GPU or render node.

    line 47
  8. Distinctive:

    Prefer the existing logged-in Wayland compositor when one is available.

    line 53
  9. Very specific:

    Use headless Sway when the host has no desktop session or the test must be isolated.

    line 56
  10. Distinctive:

    Use a nested compositor when isolation is needed inside an existing Wayland desktop and an extra window is acceptable.

    line 61
  11. Distinctive:

    Use a source build or patch only after reproducing a version-specific defect and recording the exact upstream revision and reason.

    line 77
  12. Very specific:

    Run the compositor, portal backend, PipeWire, and AUV as the same unprivileged user.

    line 82
  13. Distinctive:

    Use the helper to run a command with either the current environment or the variables published by the user manager:

    line 87
  14. Distinctive:

    Do not run the compositor or AUV as root to work around device permissions.

    line 95
  15. Distinctive:

    Run the AUV Linux driver probe:

    line 105
  16. Distinctive:

    Run repeated product-surface captures:

    line 111
  17. Distinctive:

    Do not turn compilation, a portal introspection result, or a single screenshot into a blanket Linux support claim.

    line 142
  18. Distinctive:

    Keep GPU compositor rendering, GPU-buffer transport, and correct AUV artifact output as three separate claims.

    line 145
  19. Very specific:

    Do not expose an unauthenticated VNC port on 0.0.0.0.

    line 152
  20. Distinctive:

    Do not overwrite an existing desktop's portal selection without checking its current backend and other consumers.

    line 153
  21. Distinctive:

    Do not persist services or enable login linger unless the user requested a durable session.

    line 155
  22. Distinctive:

    Keep capture and input evidence separate.

    line 157

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

AUV Wayland Rendering

Build a reproducible Linux desktop session in which AUV can observe a Wayland display and persist capture artifacts. Treat environment validation as evidence, not as a change to AUV's public support claim.

Keep ownership explicit: the compositor renders application clients; AUV requests frames through the portal and records them. Do not imply that AUV ships the compositor or a Linux overlay renderer.

Read the relevant references

  • Read setup.md before installing packages, creating a compositor session, or configuring remote viewing.
  • Read troubleshooting.md when a probe or capture fails, the image is blank, or hardware rendering is uncertain.
  • Check AUV's current support matrix before describing a result as supported. A successful live probe is live-validated evidence for the named environment only.

Follow the workflow

1. Inspect before changing the host

Run the read-only probe in the target shell:

.agents/skills/auv-wayland-rendering/scripts/probe-wayland.sh

Add --require-gpu to make missing GPU prerequisites fatal when hardware rendering is required. The flag does not replace compositor-log evidence. Record:

  • distribution and package manager;
  • existing compositor and whether the session is local, nested, or headless;
  • WAYLAND_DISPLAY, XDG_RUNTIME_DIR, and the session D-Bus;
  • accessible /dev/dri/renderD* nodes and the renderer reported by compositor logs or eglinfo/vulkaninfo;
  • ScreenCast portal and PipeWire readiness.

Do not infer GPU rendering from the presence of a GPU or render node. Require a renderer log or renderer-tool result. Label pixman, llvmpipe, and similar paths as software rendering.

2. Choose the session shape

Prefer the existing logged-in Wayland compositor when one is available. It already owns the seat, GPU, D-Bus activation environment, and user consent UI.

Use headless Sway when the host has no desktop session or the test must be isolated. Start with wlroots renderer auto-selection. Force pixman only as an explicit software fallback; doing so gives deterministic rendering but does not validate the GPU path.

Use a nested compositor when isolation is needed inside an existing Wayland desktop and an extra window is acceptable. Do not point AUV at one compositor while its portal backend is attached to another.

3. Install the smallest capability set

Install or verify:

  • a Wayland compositor such as Sway;
  • xdg-desktop-portal and the backend for that compositor;
  • PipeWire and WirePlumber;
  • wayland-info and grim for independent diagnostics;
  • WayVNC only when a human needs to view the wlroots session remotely.

Request authorization before changing system packages, user services, group membership, login linger, or firewall state. Prefer distribution packages. Use a source build or patch only after reproducing a version-specific defect and recording the exact upstream revision and reason.

4. Keep one coherent user session

Run the compositor, portal backend, PipeWire, and AUV as the same unprivileged user. They must agree on XDG_RUNTIME_DIR, WAYLAND_DISPLAY, and the session bus. For a compositor started by a user service, import its generated variables into the systemd user manager and retrieve them in SSH shells.

Use the helper to run a command with either the current environment or the variables published by the user manager:

.agents/skills/auv-wayland-rendering/scripts/with-wayland-session.sh \
  auv invoke display.list --json

Do not run the compositor or AUV as root to work around device permissions. Fix seat, logind, container-device, or render-node access instead.

5. Validate from dependencies to AUV artifacts

Validate in this order so each failure has one clear owner:

  1. Confirm the Wayland socket and compositor output with wayland-info or the compositor IPC.
  2. Confirm PipeWire and the org.freedesktop.portal.ScreenCast interface.
  3. Run the AUV Linux driver probe:

    cargo run -p auv-driver-linux --example validate -- permissions displays
  4. Run repeated product-surface captures:

    .agents/skills/auv-wayland-rendering/scripts/verify-auv-capture.sh \
      --auv target/debug/auv --repeat 3
  5. Open at least one emitted PNG. Verify that it contains the expected client, has the expected dimensions, and is not a blank or stale frame.

Repeated captures establish startup and first-frame reliability. To test freshness, visibly change a client between two capture passes and compare their artifacts; identical static frames do not prove that updates propagate.

The verification script checks AUV's JSON result, artifact purpose, PNG signature, and file existence. It does not prove semantic correctness of the rendered application; visual inspection or an app-specific assertion remains separate.

6. Report the boundary precisely

Report all of the following:

  • OS, compositor, portal backend, output name and dimensions;
  • renderer and whether it is hardware or software;
  • portal frame transport when known (dma-buf, shared memory, or fallback);
  • AUV revision and exact validation commands;
  • successful run IDs and artifact paths;
  • whether remote viewing was enabled and how it was secured;
  • known warnings, fallbacks, and missing capabilities.

Do not turn compilation, a portal introspection result, or a single screenshot into a blanket Linux support claim.

Keep GPU compositor rendering, GPU-buffer transport, and correct AUV artifact output as three separate claims. None implies the other two.

Apply safety rules

  • Bind WayVNC to loopback and use an SSH tunnel unless authenticated transport was explicitly configured.
  • Do not expose an unauthenticated VNC port on 0.0.0.0.
  • Do not overwrite an existing desktop's portal selection without checking its current backend and other consumers.
  • Do not persist services or enable login linger unless the user requested a durable session.
  • Keep capture and input evidence separate. A rendered frame does not prove that input was delivered or that an application completed an operation.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.