ubuntu-start 0.3.1__py3-none-any.whl

guide_search.py

@@ -0,0 +1,39 @@
+"""Search normalized guide entries without GTK dependencies."""
+from __future__ import annotations
+
+from collections.abc import Iterable
+import unicodedata
+
+GuideSearchEntry = tuple[str, int, str, str, str]
+
+
+def _normalize_token(token: str) -> str:
+    decomposed = unicodedata.normalize("NFKD", token.casefold())
+    return "".join(character for character in decomposed if character.isalnum())
+
+
+def find_guide_matches(
+    query: str,
+    entries: Iterable[GuideSearchEntry],
+) -> list[GuideSearchEntry]:
+    """Return entries containing every query term in their visible text.
+
+    Entries contain a guide kind, its index, the guide title, a step title,
+    and the step description. Matching is case-insensitive, ignores accents
+    and punctuation, and accepts terms in any order.
+    """
+    terms = [_normalize_token(term) for term in query.split()]
+    terms = [term for term in terms if term]
+    if not terms:
+        return []
+
+    matches = []
+    for entry in entries:
+        searchable = " ".join(
+            _normalize_token(word)
+            for value in entry[2:]
+            for word in value.casefold().split()
+        )
+        if all(term in searchable for term in terms):
+            matches.append(entry)
+    return matches

system_diagnostics.py

@@ -0,0 +1,365 @@
+"""Read-only system diagnostics used by Ubuntu Start."""
+from __future__ import annotations
+
+import os
+import ipaddress
+import platform
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import time
+import urllib.error
+import urllib.request
+
+
+def parse_nmcli_device_status(output: str) -> list[tuple[str, str, str]]:
+    """Parse `nmcli -t -f DEVICE,TYPE,STATE device status` output."""
+    devices = []
+    for line in output.splitlines():
+        fields = line.split(":", 2)
+        if len(fields) != 3:
+            continue
+        device, device_type, state = (field.strip() for field in fields)
+        if not device or not device_type or not state:
+            continue
+        if device.casefold() == "device":
+            continue
+        if device == "lo" or device_type.casefold() == "loopback":
+            continue
+        devices.append((device, device_type.casefold(), state.casefold()))
+    return devices
+
+
+def read_network_devices(timeout: float = 3.0) -> tuple[list[tuple[str, str, str]], str | None]:
+    """Read local NetworkManager device state without probing the network."""
+    if shutil.which("nmcli") is None:
+        return [], "not-installed"
+
+    env = os.environ.copy()
+    env.update({"LANG": "C", "LC_ALL": "C"})
+    env.pop("LANGUAGE", None)
+    try:
+        result = subprocess.run(
+            ["nmcli", "--terse", "--fields", "DEVICE,TYPE,STATE", "device", "status"],
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+    except subprocess.TimeoutExpired:
+        return [], "timeout"
+    except OSError:
+        return [], "unavailable"
+
+    if result.returncode != 0:
+        return [], "unavailable"
+    return parse_nmcli_device_status(result.stdout), None
+
+
+def parse_bluetooth_controller_status(output: str) -> str:
+    """Parse only controller presence and power state from bluetoothctl output."""
+    has_controller = False
+    powered = None
+    for line in output.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("Controller "):
+            has_controller = True
+        key, separator, value = stripped.partition(":")
+        if separator and key.casefold() == "powered":
+            state = value.strip().casefold()
+            if state in {"yes", "no"}:
+                powered = state == "yes"
+    if not has_controller:
+        return "no-controller"
+    if powered is None:
+        return "unknown"
+    return "powered" if powered else "off"
+
+
+def read_bluetooth_status(
+    timeout: float = 3.0,
+    controller_path: str | Path = "/sys/class/bluetooth",
+) -> str:
+    """Read local Bluetooth controller power state without scanning for devices."""
+    if shutil.which("bluetoothctl") is None:
+        return "not-installed"
+    if not any(Path(controller_path).glob("hci*")):
+        return "no-controller"
+    result = _run_local(["bluetoothctl", "show"], timeout)
+    if result is None:
+        return "timeout-or-unavailable"
+    if result.returncode != 0:
+        return "unavailable"
+    return parse_bluetooth_controller_status(result.stdout)
+
+
+def parse_wpctl_volume(output: str) -> tuple[int, bool] | None:
+    """Parse a volume percentage and mute flag from `wpctl get-volume`."""
+    match = re.search(r"\bVolume:\s*([0-9]+(?:\.[0-9]+)?)", output, re.IGNORECASE)
+    if not match:
+        return None
+    percent = round(float(match.group(1)) * 100)
+    muted = bool(re.search(r"\[MUTED\]", output, re.IGNORECASE))
+    return percent, muted
+
+
+def parse_pactl_volume(output: str) -> int | None:
+    """Parse the first channel percentage from `pactl get-*-volume`."""
+    match = re.search(r"\b([0-9]{1,3})%", output)
+    return int(match.group(1)) if match else None
+
+
+def parse_pactl_mute(output: str) -> bool | None:
+    match = re.search(r"\bMute:\s*(yes|no)\b", output, re.IGNORECASE)
+    return match.group(1).casefold() == "yes" if match else None
+
+
+def read_audio_status(timeout: float = 2.0) -> dict[str, tuple[int, bool] | None | str]:
+    """Read default speaker and microphone volume/mute state without changing it."""
+    wpctl = shutil.which("wpctl")
+    pactl = shutil.which("pactl")
+    result: dict[str, tuple[int, bool] | None | str] = {
+        "output": None, "input": None, "error": None,
+    }
+    if wpctl:
+        for key, endpoint in (("output", "@DEFAULT_AUDIO_SINK@"), ("input", "@DEFAULT_AUDIO_SOURCE@")):
+            response = _run_local([wpctl, "get-volume", endpoint], timeout)
+            if response and response.returncode == 0:
+                result[key] = parse_wpctl_volume(response.stdout)
+    if pactl:
+        for key, kind, endpoint in (
+            ("output", "sink", "@DEFAULT_SINK@"),
+            ("input", "source", "@DEFAULT_SOURCE@"),
+        ):
+            if result[key] is not None:
+                continue
+            volume = _run_local([pactl, f"get-{kind}-volume", endpoint], timeout)
+            mute = _run_local([pactl, f"get-{kind}-mute", endpoint], timeout)
+            percent = parse_pactl_volume(volume.stdout) if volume and volume.returncode == 0 else None
+            muted = parse_pactl_mute(mute.stdout) if mute and mute.returncode == 0 else None
+            if percent is not None and muted is not None:
+                result[key] = (percent, muted)
+    if not wpctl and not pactl:
+        result["error"] = "not-installed"
+
+    if result["output"] is None and result["input"] is None and result["error"] is None:
+        result["error"] = "unavailable"
+    return result
+
+
+def parse_cpu_model(cpuinfo: str) -> str | None:
+    """Return a useful CPU model from Linux procfs content."""
+    for line in cpuinfo.splitlines():
+        key, separator, value = line.partition(":")
+        if separator and key.strip().casefold() in {"model name", "hardware", "processor"}:
+            candidate = value.strip()
+            if candidate and candidate.casefold() not in {"unknown", "unknown processor"}:
+                if key.strip().casefold() == "processor" and candidate.isdigit():
+                    continue
+                return candidate
+    return None
+
+
+def parse_memory_kib(meminfo: str) -> int | None:
+    """Return MemTotal in KiB from Linux procfs content."""
+    for line in meminfo.splitlines():
+        key, separator, value = line.partition(":")
+        if separator and key.strip() == "MemTotal":
+            parts = value.split()
+            if parts and parts[0].isdigit():
+                return int(parts[0])
+    return None
+
+
+def _read(path: Path) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace").strip() or None
+    except OSError:
+        return None
+
+
+def _graphics_adapters(drm_path: Path) -> list[str]:
+    adapters = []
+    for device_path in sorted(drm_path.glob("card[0-9]*/device")):
+        vendor = _read(device_path / "vendor")
+        device = _read(device_path / "device")
+        if not vendor or not device:
+            continue
+        driver_link = device_path / "driver"
+        try:
+            driver = driver_link.resolve(strict=True).name
+        except OSError:
+            driver = None
+        pci_id = f"{vendor}:{device}"
+        adapters.append(f"{pci_id} ({driver})" if driver else pci_id)
+    return adapters
+
+
+def read_hardware_details(
+    cpuinfo_path: str | Path = "/proc/cpuinfo",
+    meminfo_path: str | Path = "/proc/meminfo",
+    sys_root: str | Path = "/sys",
+) -> dict[str, str | None | list[str]]:
+    """Read useful hardware facts while deliberately excluding serial numbers."""
+    cpuinfo = _read(Path(cpuinfo_path)) or ""
+    meminfo = _read(Path(meminfo_path)) or ""
+    sys_root = Path(sys_root)
+    product = _read(sys_root / "class/dmi/id/product_name")
+    if product and product.casefold() in {"default string", "to be filled by o.e.m.", "not specified"}:
+        product = None
+
+    memory_kib = parse_memory_kib(meminfo)
+    memory = f"{round(memory_kib / 1_048_576)} GiB" if memory_kib is not None else None
+    return {
+        "system_model": product,
+        "processor": parse_cpu_model(cpuinfo),
+        "memory": memory,
+        "graphics": _graphics_adapters(sys_root / "class/drm"),
+        "architecture": platform.machine(),
+    }
+
+
+def read_storage_status(path: str | Path = "/") -> dict[str, int]:
+    """Return local filesystem capacity in bytes."""
+    usage = shutil.disk_usage(path)
+    return {"total": usage.total, "used": usage.used, "free": usage.free}
+
+
+def read_battery_status(power_supply_path: str | Path = "/sys/class/power_supply") -> list[dict[str, str | int]]:
+    """Read charge and optional full-charge capacity estimate without device identifiers."""
+    batteries = []
+    for battery in sorted(Path(power_supply_path).glob("*") if Path(power_supply_path).exists() else []):
+        if _read(battery / "type") != "Battery":
+            continue
+        try:
+            capacity = int(_read(battery / "capacity") or "")
+        except ValueError:
+            capacity = -1
+        status = _read(battery / "status")
+        if 0 <= capacity <= 100:
+            details: dict[str, str | int] = {"capacity": capacity, "status": status or "Unknown"}
+            for full_name, design_name in (("energy_full", "energy_full_design"), ("charge_full", "charge_full_design")):
+                try:
+                    full = int(_read(battery / full_name) or "")
+                    design = int(_read(battery / design_name) or "")
+                except ValueError:
+                    continue
+                if full > 0 and design > 0:
+                    details["design_capacity_percent"] = round(full / design * 100)
+                    break
+            batteries.append(details)
+    return batteries
+
+
+def check_internet_connection(timeout: float = 5.0) -> str:
+    """Make a small HTTPS request to Ubuntu; call only after explicit user consent."""
+    request = urllib.request.Request("https://ubuntu.com/", method="HEAD", headers={"User-Agent": "Ubuntu-Start-connectivity-check"})
+    class NoRedirect(urllib.request.HTTPRedirectHandler):
+        def redirect_request(self, request, response, code, message, headers, new_url):
+            return None
+
+    opener = urllib.request.build_opener(NoRedirect())
+    try:
+        with opener.open(request, timeout=timeout) as response:
+            return f"reachable:{response.status}"
+    except urllib.error.HTTPError as error:
+        # An HTTP response, including an error status, proves the host was reached.
+        error.close()
+        return f"reachable:{error.code}"
+    except (OSError, TimeoutError) as error:
+        return f"unreachable:{error.__class__.__name__}"
+
+
+def parse_default_route(output: str) -> tuple[str, str] | None:
+    """Extract an IP default gateway and interface from `ip route` output."""
+    for line in output.splitlines():
+        fields = line.split()
+        if len(fields) >= 5 and fields[0] == "default" and "via" in fields and "dev" in fields:
+            try:
+                gateway = str(ipaddress.ip_address(fields[fields.index("via") + 1]))
+            except (ValueError, IndexError):
+                continue
+            interface = fields[fields.index("dev") + 1]
+            if interface and interface.replace("_", "").replace("-", "").replace(".", "").isalnum():
+                return gateway, interface
+    return None
+
+
+def parse_neighbor_mac(output: str) -> str | None:
+    """Return a valid MAC address from `ip neigh` output."""
+    fields = output.split()
+    if "lladdr" not in fields:
+        return None
+    try:
+        mac = fields[fields.index("lladdr") + 1].upper().replace("-", ":")
+    except IndexError:
+        return None
+    parts = mac.split(":")
+    return mac if len(parts) == 6 and all(len(part) == 2 and all(c in "0123456789ABCDEF" for c in part) for part in parts) else None
+
+
+def lookup_oui_vendor(mac: str | None, databases: tuple[str, ...] = (
+    "/usr/share/ieee-data/oui.txt", "/usr/share/hwdata/oui.txt", "/usr/share/misc/oui.txt",
+)) -> str | None:
+    """Match a MAC prefix against an installed IEEE OUI database; never use a web lookup."""
+    if not mac:
+        return None
+    prefix = mac.upper().replace(":", "-")[:8]
+    for database in databases:
+        try:
+            lines = Path(database).read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            match = re.match(r"^([0-9A-Fa-f-]{8})\s+\(hex\)\s+(.+?)\s*$", line)
+            if match and match.group(1).upper() == prefix:
+                vendor = match.group(2).strip()
+                return vendor or None
+    return None
+
+
+def _run_local(command: list[str], timeout: float = 3.0) -> subprocess.CompletedProcess[str] | None:
+    try:
+        return subprocess.run(command, capture_output=True, text=True, check=False, timeout=timeout)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+
+def run_network_diagnostics(timeout: float = 3.0) -> dict[str, str | float | None]:
+    """Measure configured DNS and gateway latency; call only after user starts the check."""
+    result: dict[str, str | float | None] = {
+        "dns_latency_ms": None, "dns_error": None,
+        "gateway": None, "gateway_interface": None,
+        "gateway_latency_ms": None, "gateway_mac": None, "gateway_vendor": None,
+    }
+    route = _run_local(["ip", "route", "show", "default"], timeout)
+    default = parse_default_route(route.stdout) if route and route.returncode == 0 else None
+    if not default:
+        route = _run_local(["ip", "-6", "route", "show", "default"], timeout)
+        default = parse_default_route(route.stdout) if route and route.returncode == 0 else None
+    if default:
+        gateway, interface = default
+        family = "-6" if ipaddress.ip_address(gateway).version == 6 else "-4"
+        result["gateway"] = gateway
+        result["gateway_interface"] = interface
+        start = time.monotonic()
+        ping = _run_local(["ping", family, "-I", interface, "-n", "-c", "1", "-W", str(max(1, int(timeout))), gateway], timeout + 1)
+        if ping and ping.returncode == 0:
+            timing = re.search(r"time[=<]([0-9.]+)\s*ms", ping.stdout)
+            result["gateway_latency_ms"] = float(timing.group(1)) if timing else round((time.monotonic() - start) * 1000, 1)
+        neighbor = _run_local(["ip", family, "neigh", "show", "to", gateway, "dev", interface], timeout)
+        mac = parse_neighbor_mac(neighbor.stdout) if neighbor and neighbor.returncode == 0 else None
+        result["gateway_mac"] = mac
+        result["gateway_vendor"] = lookup_oui_vendor(mac)
+    else:
+        result["gateway_error"] = "no-default-route"
+
+    start = time.monotonic()
+    dns = _run_local(["getent", "ahosts", "ubuntu.com"], timeout)
+    if dns and dns.returncode == 0 and dns.stdout.strip():
+        result["dns_latency_ms"] = round((time.monotonic() - start) * 1000, 1)
+    else:
+        result["dns_error"] = "lookup-failed"
+    return result

ubuntu_start-0.3.1.data/data/share/metainfo/se.nylander.UbuntuStart.metainfo.xml

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="desktop-application">
+  <id>se.nylander.UbuntuStart</id>
+  <name>Ubuntu Start</name>
+  <summary>A friendly guide to Ubuntu setup and device troubleshooting</summary>
+  <summary xml:lang="sv">En hjälpsam guide för att komma igång med Ubuntu och felsöka enheter</summary>
+  <metadata_license>CC0-1.0</metadata_license>
+  <project_license>GPL-3.0</project_license>
+  <icon type="stock">se.nylander.UbuntuStart</icon>
+  <launchable type="desktop-id">se.nylander.UbuntuStart.desktop</launchable>
+  <developer id="se.nylander"><name>Ubuntu Start contributors</name></developer>
+  <url type="homepage">https://github.com/yeager/ubuntu-start</url>
+  <categories>
+    <category>Utility</category>
+    <category>System</category>
+  </categories>
+  <description>
+    <p>Get started with Ubuntu through step-by-step system guides, practical device troubleshooting, accessibility help and local network and hardware details. Search guides and copy a privacy-conscious system summary when asking for help.</p>
+    <p xml:lang="sv">Kom igång med Ubuntu med tydliga systemguider, praktisk felsökning, hjälpmedelsstöd och lokal information om nätverk och maskinvara. Sök i guiderna och kopiera en integritetsvänlig systemöversikt när du ber om hjälp.</p>
+  </description>
+  <releases>
+    <release version="0.3.1" date="2026-10-28">
+      <description>
+        <p>Provide an installable Debian package and improve the touchpad troubleshooting text so it displays correctly in GTK.</p>
+        <p xml:lang="sv">Lägg till ett installerbart Debianpaket och justera felsökningstexten för styrplattor så att den visas korrekt i GTK.</p>
+      </description>
+    </release>
+    <release version="0.3.0" date="2026-10-28">
+      <description>
+        <p>Search device troubleshooting and system guides together and open a matching guide directly. Add step-by-step help for app installation, accessibility, networking and everyday shortcuts, plus tips for backups and trusted software sources. Ubuntu Start asks before opening App Center because it may contact configured software sources; it never installs apps itself.</p>
+        <p xml:lang="sv">Sök bland enhetsfelsökning och systemguider på en gång och öppna rätt guide direkt. Få steg-för-steg-hjälp med appinstallation, hjälpmedel, nätverk och vanliga genvägar samt råd om säkerhetskopiering och betrodda programkällor. Ubuntu Start frågar innan App Center öppnas eftersom det kan ansluta till programkällor. Ubuntu Start installerar inte appar.</p>
+      </description>
+    </release>
+    <release version="0.2.0" date="2026-10-28">
+      <description>
+        <p>Add searchable troubleshooting guides, Ubuntu support links and a copyable system summary.</p>
+      </description>
+    </release>
+  </releases>
+  <content_rating type="oars-1.1"/>
+</component>

ubuntu_start-0.3.1.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: ubuntu-start
+Version: 0.3.1
+Summary: Ubuntu Desktop first-run and device troubleshooting guide
+Author-email: Daniel Nylander <daniel@nylander.se>
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/yeager/ubuntu-start
+Project-URL: Repository, https://github.com/yeager/ubuntu-start
+Project-URL: Issues, https://github.com/yeager/ubuntu-start/issues
+Keywords: ubuntu,gnome,desktop,troubleshooting,accessibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: GTK
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Ubuntu Start
+
+An Ubuntu Desktop guide for first-run setup and device troubleshooting.
+
+![Ubuntu Start app icon](data/se.nylander.UbuntuStart.png)
+
+![Ubuntu Start welcome screen in English](screenshots/welcome-en.png)
+
+[Swedish welcome screen](screenshots/welcome-sv.png) · [More screenshots](screenshots/)
+
+![Search results for printer troubleshooting](screenshots/search-en.png)
+
+![Step-by-step Wi-Fi system guide](screenshots/system-guides-en.png)
+
+![Accessibility instructions for larger text](screenshots/accessibility-en.png)
+
+![Read-only network and hardware overview](screenshots/network-hardware-en.png)
+
+[More screenshots: network diagnostics (EN)](screenshots/network-diagnostics-en.png) · [audio status (EN)](screenshots/audio-status-en.png) · [Terminal guide (EN)](screenshots/terminal-guide-en.png) · [WiFi Analyzer recommendation (EN)](screenshots/wifi-analyzer-en.png) · [help page (EN)](screenshots/help-en.png) · [hardware summary (EN)](screenshots/help-hardware-en.png)
+
+[Swedish system guides](screenshots/system-guides-sv.png) · [network and hardware overview](screenshots/network-hardware-sv.png) · [network diagnostics](screenshots/network-diagnostics-sv.png) · [audio status](screenshots/audio-status-sv.png) · [Terminal guide](screenshots/terminal-guide-sv.png) · [WiFi Analyzer recommendation](screenshots/wifi-analyzer-sv.png) · [help page](screenshots/help-sv.png) · [hardware summary](screenshots/help-hardware-sv.png) · [accessibility settings](screenshots/accessibility-panel-en.png)
+
+
+Ubuntu Start combines a first-run guide with practical device troubleshooting for Ubuntu Desktop. It is a GTK 4/libadwaita application intended for Ubuntu GNOME.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor guidance and the maintainer pull request review process.
+
+## Current scope
+
+- First steps for language, networking, updates, sound, display and privacy.
+- Everyday tips for search, window management and Files, plus guidance on backups and choosing trusted app sources.
+- Search device checks and step-by-step system guides together, then open a matching guide directly. Topics include sound, Bluetooth, batteries, printers, displays/graphics, keyboards, touchpads, Wi-Fi, Ethernet, cameras, accessibility and Terminal basics.
+- Step-by-step guides for installing apps, updates, Wi-Fi, Ethernet, printers, batteries, keyboards, touchpads, larger text, screen magnification and the Orca screen reader.
+- Accessibility guides explain larger text, zoom, screen reading, the on-screen keyboard, typing assistance and visual sound alerts, with plain-language steps before each change.
+- A beginner-friendly Terminal guide explains the prompt, command output and errors, `pwd`, `ls`, `cd`, paths with spaces, Tab completion, command history, `--help`, `man`, `sudo` and safe ways to stop a command.
+- Optional connection diagnostics report DNS lookup and gateway ping latency in milliseconds, plus the gateway MAC address and a local OUI vendor match. The test asks before running; it sends one DNS lookup to the configured resolver and one ping to the local gateway.
+- Read-only Bluetooth status reports whether a controller is present and powered on without scanning for nearby devices.
+- Read-only audio status checks the default speaker and microphone volume and mute state through PipeWire or PulseAudio without playing sounds or changing settings.
+- Wi-Fi troubleshooting recommends [WiFi Analyzer](https://github.com/yeager/wifi-analyzer) for nearby signal levels and channel use. Opening GitHub requires confirmation.
+- Built-in links to official Ubuntu documentation, Ask Ubuntu and the Ubuntu support forum.
+- Read-only NetworkManager, Bluetooth, hardware and storage summaries, battery charge and estimated capacity versus original design when exposed, plus a copyable support report that omits usernames, host names, serial numbers, network addresses, Wi-Fi names and installed applications.
+- Links into GNOME Control Center and Ubuntu's Additional Drivers tool. System changes remain in Ubuntu's own tools and require the user's confirmation.
+- gettext-based localization with English source strings and a complete Swedish (`sv`) catalog.
+
+## Build and run on Ubuntu
+
+Install the platform dependencies, then build with Meson:
+
+```sh
+sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 gettext meson ninja-build
+meson setup build --prefix=/usr
+meson compile -C build
+sudo meson install -C build
+```
+
+To build an installable Debian package after installing the dependencies, run `scripts/build-deb.sh`. It creates `build/packages/ubuntu-start_0.3.1-1_all.deb`. Install it with `sudo apt install ./build/packages/ubuntu-start_0.3.1-1_all.deb`; APT resolves the declared GTK and Python runtime dependencies.
+
+The PyPI wheel and source distribution are prepared. The initial upload needs a Trusted Publisher registered for this repository; after that, tagged releases publish automatically. Once the package is available, install the GTK platform dependencies with APT first, then install it in an isolated environment that can access system PyGObject bindings:
+
+```sh
+sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 gettext
+python3 -m venv --system-site-packages .venv
+. .venv/bin/activate
+python -m pip install ubuntu-start
+ubuntu-start
+```
+
+For a source checkout, run `python3 src/ubuntu_start.py` to use the English source strings. To try the Swedish catalog from the checkout:
+
+```sh
+mkdir -p build/locale/sv/LC_MESSAGES
+msgfmt po/sv.po -o build/locale/sv/LC_MESSAGES/ubuntu-start.mo
+LANGUAGE=sv UBUNTU_START_LOCALEDIR="$PWD/build/locale" python3 src/ubuntu_start.py
+```
+
+Run the unit tests with `PYTHONPATH=src python3 -m unittest discover -s tests -v`. The CI workflow runs these tests and builds the app for pull requests.
+
+NetworkManager, Bluetooth, audio, storage, battery and hardware summaries use local system information. DNS/gateway tests and the WiFi Analyzer GitHub link ask for confirmation before contacting an external service; DNS uses the configured resolver, ping targets the local gateway, and vendor matching uses a local OUI file when available. The separate internet test sends one HTTPS HEAD request to `ubuntu.com` after confirmation. Opening the Ubuntu App Center asks first because it may contact configured software sources; Ubuntu Start does not install apps. Other help pages open only when selected. No diagnostic report is uploaded, and serial numbers are not read. The app expects GTK 4, libadwaita and PyGObject.
+
+## Validation
+
+Release `v0.3.0` passed GitHub CI and the release workflow. The current 0.3.1 working tree passes all 41 unit tests, source-string coverage, translation checks, Python wheel/sdist builds and `twine check`. The 0.3.1 Debian package was built and installed on Ubuntu 26.10 machine `trv2`; package audit and APT dependency checks passed. A live GTK session exposed and verified a fix for search results with matching guides. Orca's AT-SPI app list detects Ubuntu Start. The network diagnostics remain unrun pending approval in the app's consent dialog. GNOME is selected as the next GDM session; TigerVNC currently uses Openbox because this Ubuntu image provides GNOME only as a Wayland session.
+
+An earlier revision was also launched under Xvfb in English and Swedish. At that point PipeWire reported an unmuted default speaker at 100% and no default microphone. The GNOME Control Center panel list confirmed the Bluetooth, Wi-Fi, printer, display, privacy, sound and keyboard panel identifiers. The two Ubuntu driver/update utilities were installed with `dpkg -i`; Additional Drivers and Update Manager opened in Swedish, and `dpkg --audit` and `apt-get check` reported no package errors. These observations apply to that earlier revision. Xvfb does not verify physical-device behavior or hardware acceleration.
+
+## Localization
+
+English is the source and default language. The app uses the desktop locale to select translations; Swedish strings live in `po/sv.po`. Add more languages through gettext catalogs and list their language codes in `po/LINGUAS`. Regenerate the template with `xgettext` and validate catalogs with `msgfmt --check`.
+
+See [po/README.md](po/README.md) for instructions on updating Swedish translations and contributing another language.
+
+## Current limitations
+
+Device troubleshooting guides are instructional. Optional network diagnostics run only after confirmation, use DNS for `ubuntu.com` and ping the local gateway, and do not upload a report. The app does not install packages or run privileged operations; system changes remain in Ubuntu's own tools. Settings panel names and the Additional Drivers launcher can differ across Ubuntu releases, so validate integrations on each supported release.
+
+
+## Releases
+
+Tagged versions (`v*`) are built by GitHub Actions. Releases include a source archive, an installable `.deb` package and SHA-256 checksums. The workflow also publishes the Python wheel and source distribution to PyPI after the repository is registered as a Trusted Publisher.
+
+## Screenshots
+
+The screenshots show the welcome page, matching printer troubleshooting steps, a Wi-Fi how-to guide, accessibility instructions and local network and hardware status.
+
+
+## License
+
+Ubuntu Start is licensed under the GNU General Public License version 3. See [LICENSE](LICENSE).

ubuntu_start-0.3.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+guide_search.py,sha256=juXK9qDryaIzPJ4OsJQQ1eMXnfkxcuh8J2uD4UmOaU0,1250
+system_diagnostics.py,sha256=aAZ5C5ExSH9WNaTWiG_U7PFpxB6iSko9YFQxKoc_Oyo,14966
+ubuntu_start.py,sha256=9c-90CvrCtMFpNYeBXBSz_IYpKQs7IiJOXhc61wKLwg,51154
+ubuntu_start-0.3.1.data/data/share/icons/hicolor/512x512/apps/se.nylander.UbuntuStart.png,sha256=0ca9r6poPW6bd6GJjmb6M8vOiKuxYTdfLXFpkDFfFkI,259719
+ubuntu_start-0.3.1.data/data/share/locale/sv/LC_MESSAGES/ubuntu-start.mo,sha256=D7DJKol2ORNaMa8sv8xJa3Pf7sfxPQp10VZYFZEeyoI,50787
+ubuntu_start-0.3.1.data/data/share/metainfo/se.nylander.UbuntuStart.metainfo.xml,sha256=SAmb85qf7JjURaeyoo1vfnWjVkIx6ObdnCC6LOMR864,2884
+ubuntu_start-0.3.1.dist-info/licenses/LICENSE,sha256=5X8cMguM-HmKfS_4Om-eBqM6A1hfbgZf6pfx2G24QFI,35150
+ubuntu_start-0.3.1.dist-info/METADATA,sha256=kUCJctEVJJZegyOMbtdPgit5zwmXQbrGCPoeTu81hbY,10251
+ubuntu_start-0.3.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+ubuntu_start-0.3.1.dist-info/entry_points.txt,sha256=sMlgHr4o4br6Vu98OD7R4_jiidXmzN2lJW59HeDbUcE,51
+ubuntu_start-0.3.1.dist-info/top_level.txt,sha256=mV5AGCh77YnoMXUMbGD4hXESvvfFU4oTFKOE7JDDLQo,45
+ubuntu_start-0.3.1.dist-info/RECORD,,

ubuntu_start-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ubuntu_start-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ubuntu-start = ubuntu_start:main