PortalDoctor v0.2.1

PortalDoctor v0.2.1 — Release Notes

Stabilization release for the passive Linux desktop portal diagnostic path.

PortalDoctor v0.2.1 keeps the v0.2 passive scope and makes its automation,
release and user-facing contracts explicit. It does not add active portal
probes, automatic fixes or new desktop support claims.

Highlights

• Finalized diagnostic exit codes for clean, severe-finding, incomplete-context,
  parser and internal-output outcomes.
• Added locked package and clean-root install smoke checks to CI.
• Extended the fault-injection acceptance harness to validate parser and
  runtime exit codes while preserving deterministic JSON findings.
• Refreshed the README demo with a slower, readable four-scene flow:
  health, routing, shareable report and controlled fault.
• Kept the validated support boundary at Ubuntu 26.04, GNOME, Wayland and a
  systemd user session.

Usage

Install the published crate:

cargo install portaldoctor --version 0.2.1 --locked

Run the default passive check:

portaldoctor

Create a privacy-aware issue attachment:

portaldoctor report --format markdown --suppress-hostname > portaldoctor-report.md
portaldoctor report --json > portaldoctor-report.json

Exit codes

Code	Meaning
0	Completed with no ERROR/CRITICAL finding; INFO/WARNING findings are allowed.
1	Completed with at least one ERROR/CRITICAL finding.
2	Invalid CLI usage or arguments.
3	Minimum graphical session/display or user D-Bus context is unavailable.
4	Output or internal process error prevented completion.

Compatibility boundary

The validated target is Ubuntu 26.04 with GNOME, Wayland and a systemd user
session. Active portal probes, KDE/wlroots validation, automatic fixes and a
GUI remain outside v0.2.1.

Validation

The release gate covers formatting, strict locked Clippy, the full test suite,
a locked release build, package verification, clean-root install, JSON and
Markdown smoke checks, parser/runtime exit-code checks and the deterministic
fault-injection harness.

PortalDoctor v0.2.0

PortalDoctor v0.2.0 — Release Notes

Passive ScreenCast readiness, bounded runtime evidence and privacy-aware
shareable reports.

PortalDoctor v0.2.0 completes the passive diagnostic path from session state
through portal routing and runtime evidence to an issue-friendly report. It
does not start portal dialogs, modify configuration or claim support for
desktop environments outside the validated target.

Highlights

• Added bounded PipeWire (pw-dump) and WirePlumber (wpctl status) health
  collection with normalized, portal-relevant video topology.
• Added deterministic PW001–PW003 and SC001–SC002 findings so a
  ScreenCast route is not mistaken for a working media path.
• Added optional, bounded current-boot/user-session journal evidence with
  stable classification and privacy sanitization.
• Added portaldoctor report with terminal, JSON and Markdown formats.
• Added report-level redaction for environment values, home paths, obvious
  secret labels and optionally the current hostname.
• Raw journal and PipeWire streams are excluded from shareable reports and
  explicitly marked as excluded in their metadata.
• Reworked the README and added a slower, readable Terminalizer demo.

Usage

Install the published crate:

cargo install portaldoctor --version 0.2.0 --locked

Run the default passive check:

portaldoctor

Create an issue-friendly attachment:

portaldoctor report --format markdown --suppress-hostname > portaldoctor-report.md
portaldoctor report --json > portaldoctor-report.json

Opt into bounded journal evidence when investigating a runtime failure:

portaldoctor --journal --verbose

Compatibility boundary

The validated target is Ubuntu 26.04 with GNOME, Wayland and a systemd user
session. Active portal probes, KDE/wlroots validation, automatic fixes and a
GUI remain outside v0.2.0.

Validation

The release gate passed formatting, strict Clippy, the full test suite, a
release build, the v0.1-compatible fault-injection harness, package
verification, live report checks and the final CI workflow.

Privacy note

Review generated attachments before publishing them. The report command is
the shareable boundary; the legacy portaldoctor --json and
portaldoctor check --json outputs retain the compatibility snapshot shape
and require manual review.

PortalDoctor v0.1.0

PortalDoctor v0.1.0 — Release Notes

First public release of the read-only PortalDoctor diagnostic CLI.

What it solves

Linux portal failures are distributed across session environment, XDG search
paths, portals.conf, .portal backend descriptors, D-Bus and systemd user
services. PortalDoctor collects those layers in one read-only snapshot,
reconstructs backend routing and reports deterministic, evidence-backed
findings.

It helps explain wrong or missing backend routing, malformed portal
configuration, a selected backend that lacks an interface, missing Wayland
session values, activation-environment mismatches, an unreachable portal
frontend and unavailable selected backend names.

Highlights

• OS, desktop, session and allowlisted environment discovery.
• Process versus systemd user activation-environment comparison.
• Upstream-style config/data root precedence and lowercase desktop-specific
  portals.conf lookup.
• [preferred] routing including default=, interface-specific overrides,
  * and none.
• .portal backend inventory, UseIn filtering and duplicate provenance.
• Explainable route tables with requested, available and selected candidates.
• D-Bus frontend/selected-backend name-owner checks with classified failures.
• Bounded systemd user service-state checks.
• 15 deterministic findings across ENV, XDP, CFG and DBUS families.
• Actionable terminal output and versioned JSON schema v1.
• 109 fixture/unit tests and CI quality gates.

Supported environment

The v0.1 validation target is:

• Ubuntu 26.04
• GNOME
• Wayland
• systemd user session
• XDG Desktop Portal frontend
• GNOME/GTK portal backends

Other environments are not claimed as supported by this release.

Installation

From the repository:

cargo install --git https://github.com/SetraTheXX/Portal-Doctor --tag v0.1.0 --locked

Or build from source:

git clone https://github.com/SetraTheXX/Portal-Doctor.git
cd Portal-Doctor
cargo build --release

Usage

portaldoctor
portaldoctor check environment
portaldoctor check portal
portaldoctor check --json
portaldoctor portal list
portaldoctor portal routes
portaldoctor portal explain ScreenCast

Safety and privacy

• Read-only by default; normal use does not require root or sudo.
• No network access, telemetry or AI service.
• Only 11 diagnostic environment variables are allowlisted.
• HOME is read only to derive XDG default roots when the corresponding XDG
  variables are unset; it is not collected or reported as a diagnostic
  variable.
• JSON output should be reviewed before sharing. v0.1 does not claim a
  general-purpose shareable redaction layer.
• D-Bus and subprocess interactions are bounded; timed-out child process groups
  are killed and reaped.

Limitations

• No PipeWire or WirePlumber graph/state collection.
• ScreenCast readiness stops at portal routing and D-Bus/systemd reachability.
• No journal correlation and no active portal probes/dialogs.
• NameHasOwner proves bus ownership, not method-level backend health.
• Backend-to-systemd-unit mapping follows conventional unit names.
• No automatic fixes and no GUI.
• KDE, wlroots/Sway, Hyprland and Niri are not supported claims.

Explicitly not included

Phase 5 PipeWire/WirePlumber integration is not part of v0.1. It remains a
planned next roadmap phase and is intentionally absent from this release.

Validation

The release-preparation baseline was validated with:

• cargo fmt --check
• strict Clippy (cargo clippy --all-targets --all-features -- -D warnings)
• cargo test --all-features
• cargo build --release
• real Ubuntu 26.04 / GNOME / Wayland bare invocation and JSON output checks