Update README.md and create suse-user-guide-example.md

README.md

@@ -1,2 +1,156 @@
 # suse-autoyast-workflows
 
+**Practical, honestly-labeled AutoYaST deployment workflows for openSUSE Leap, SLES, and Tumbleweed.**
+
+REFER TO ALL RELEVANT OFFICIAL SOFTWARE MANUALS
+
+Public domain. Built in Brianza. Designed for anyone deploying SUSE with AutoYaST.
+
+---
+
+## What This Is
+
+A set of process workflows for partially unattended openSUSE
+installation via AutoYaST — covering client device profiling, VM-based
+pre-deployment testing, and the bare-metal deployment that follows it.
+Built from real, documented deployment experience, not theoretical best
+practice.
+
+[WARNING] This repository is a guiding template, not a source of truth.
+SUSE's own documentation — [documentation.suse.com](https://documentation.suse.com)
+— is authoritative for whatever SLES/Leap/Tumbleweed release is actually
+being deployed. Find and read the AutoYaST Guide for that specific
+release; don't assume an example seen elsewhere still applies. AutoYaST
+syntax, package availability, default groups, and repo layout all shift
+between releases; a detail confirmed here on one version is not a
+standing guarantee for another. Adapt this repo's guidance to the
+current release's own manual before relying on it, every time, not just
+on first use.
+
+This isn't a theoretical caution. The project that generalized into this
+repo burned real time chasing exactly this: assuming a detail true for
+one openSUSE release still held for the target being deployed, when it
+didn't. Thirteen install passes traced back, in part, to not re-checking
+the current release's own guide closely enough at each step. Don't
+repeat that mistake by trusting this repo the way it should have
+trusted the current manual instead.
+
+[WARNING] The same applies to the virtualization tooling this repo's
+workflows depend on. `libvirt`, `virt-install`, `virt-viewer`, and QEMU
+each version independently of the SUSE release being deployed and of
+each other — flag syntax, default behavior, and firmware/TPM support
+change between releases. The
+[libvirt documentation](https://libvirt.org/docs.html) and each tool's
+own man page are authoritative, not this repo. A command confirmed
+working here on one host's package versions is not a standing guarantee
+on a different host, a different tinkerpad13 update cycle, or a
+different distro's packaging of the same tools.
+
+AutoYaST automates the configuration decisions — package selection,
+partitioning, privilege escalation setup — but this is not a walk-away
+install. Physical presence (or its VM equivalent, a watched console)
+matters throughout: AutoYaST's own documentation notes that some
+interactive dialogs bypass suppression entirely, and this repo's
+workflows are built around staying attended for exactly that reason.
+"Partially unattended" is the honest description — the profile does the
+deciding, a person does the watching.
+
+This repository is **in progress**. Several referenced sub-workflows
+don't exist yet (see Status below) — what's here is published as an
+honest work in progress, not withheld until complete. Consider this the
+technical process layer: version selection, media policy, VM tooling,
+test-cycle mechanics. It does not cover AutoYaST profile authoring
+itself, which lives in its own not-yet-written workflow, or any
+business-process content around client engagement — this repo is
+deployment mechanics only.
+
+---
+
+## Where This Comes From
+
+This workflow set was generalized out of a real deployment project —
+migrating a ThinkPad from Alpine to openSUSE Tumbleweed via AutoYaST,
+across thirteen documented install passes. That project surfaced the
+core technical problem this repo's guidance is built around: openSUSE's
+`Defaults targetpw` sudo behavior, which breaks the standard RHEL-style
+privilege escalation pattern unless addressed explicitly.
+
+That original project's full build log — warts, false starts, and all —
+stays a separate, private record. This repository is downstream of it,
+not a sanitized copy of it: everything here is written fresh, as
+general-purpose process, not as an account of what happened on any one
+specific machine.
+
+---
+
+## Scope
+
+**Covered:** openSUSE Leap and SLES, as the primary target — point
+releases where a DVD image stays representative of what actually
+installs, making genuine pre-deploy VM testing possible. Tumbleweed is
+not excluded, but its rolling-release nature changes the guarantees the
+test cycle can offer; see the deploy workflow's own notes on this.
+
+**Not covered:** AutoYaST profile authoring itself (package selection,
+partitioning, post-install script content) — referenced from this
+repo's workflows but documented separately. Client engagement mechanics
+and pricing (how a handoff is billed, structured, or negotiated) are
+deliberately kept out of this repository entirely; that's specific to
+whoever's deploying and isn't this repo's business.
+
+**Covered, at the principle level:** client empowerment as a closing
+step. This repo's deploy workflow recommends ending every deployment
+with a handoff — a portable copy of the deployed VM in whatever
+deliverable form suits the situation, plus a basic usage guide the
+deployer writes for that specific client. What form the guide takes,
+how the copy is delivered, and how any of it is billed are left
+entirely to the deployer; the recommendation is that a handoff happens
+and empowers the client, not a specification of how.
+
+Two example handoff documents are included as reference: a generic
+**user's guide** (`suse-user-guide-example.md`) and a planned
+**administrator's guide**, showing the kind of thing this recommendation
+actually produces. Neither contains, nor should ever contain, real
+credentials, passwords, or any client-specific detail — a guide
+documents how to authenticate, never what to authenticate with. Treat
+them as a starting shape to adapt, not a template to fill in verbatim.
+
+---
+
+## Status
+
+**Early, actively being refined.** One real-world deployment (Tumbleweed)
+informs the current guidance; Leap and SLES guidance is not yet verified
+against an actual test pass. Several sub-workflows this repo's documents
+reference are not yet written:
+
+| Referenced | Covers |
+|---|---|
+| `autoyast-crafting-workflow.md` | Authoring/selecting the AutoYaST profile itself — not yet written |
+| `autoyast-error-debugging-workflow.md` | Diagnosing a failed verification check to root cause — not yet written |
+| `suse-deploy-post-install-testing-workflow.md` | Post-install inspection beyond pass/fail — not yet written |
+| `device-profile.md` | Client device intake sheet — not yet written |
+| `suse-autoyast-deploy-phase2.md` | Bare-metal deployment at the client site — closes with the client handoff recommendation — not yet written |
+| `suse-user-guide-example.md` | ✅ Written — generic user's guide, worked example |
+| `administrator-guide-example.md` | Generic administrator's guide — not yet written |
+
+`[UNVERIFIED]` tags throughout the existing documents mark specific
+claims not yet confirmed on Leap/SLES — check these explicitly before
+relying on them for a real deployment.
+
+---
+
+## Licence
+
+All original content in this repository is released to the public
+domain under the Unlicense.
+
+---
+
+## Project
+
+**Cervello Elettrico OS** — `git.jhoeven.net/ceos`
+
+Brianza, Italy · `servizi@cervelloelettrico.it` · `cervelloelettrico.it`
+
+*Crafted by John A. Hoeven with the ethical assistance of Claude AI (Anthropic).*

suse-user-guide-example.md

@@ -0,0 +1,610 @@
+# tinkerpad13 Quick Reference — Day-to-Day Admin and General Linux Basics
+
+My own enthusiast-level quick reference for my personal device (openSUSE
+Tumbleweed) day-to-day administration. Covers shell navigation, zypper
+package management, systemd services, users/permissions, storage and
+Btrfs/Snapper, networking, logs, troubleshooting, and system updates.
+Most commands are general Linux, not SUSE-specific; sections calling
+out SUSE-specific behavior are tagged explicitly, and a few notes below
+are specific to how *this* system is actually configured, not a general
+SUSE default.
+
+[WARNING] This is a quick reference for common day-to-day tasks, not a
+substitute for the official documentation for the exact SUSE release in
+use. Commands, defaults, and package names shift between versions —
+check documentation.suse.com or `man <command>` when something here
+doesn't match what's on screen.
+
+---
+
+## SECTION: Shell and navigation
+<!-- source: ce-authored -->
+
+To show the current directory:
+
+```sh
+pwd
+```
+
+To list files including sizes and hidden files:
+
+```sh
+ls -lah
+```
+
+To change directory:
+
+```sh
+cd /path/to/directory
+```
+
+`cd ..` moves up one directory level.
+
+To copy a file or folder (recursive for folders):
+
+```sh
+cp -r source destination
+```
+
+To move or rename a file or folder:
+
+```sh
+mv source destination
+```
+
+To delete a folder and its contents:
+
+```sh
+rm -r directory/
+```
+
+[WARNING] `rm -r` has no undo and no trash — deleted files and folders
+are not recoverable this way.
+
+To search for files by name:
+
+```sh
+find / -name "pattern*"
+```
+
+To search inside files for text:
+
+```sh
+grep -r "search text" directory/
+```
+
+To page through a file's contents (press `q` to quit):
+
+```sh
+less filename
+```
+
+To read the manual page for a command:
+
+```sh
+man command
+```
+
+To search past commands:
+
+```sh
+history | grep search-term
+```
+
+[NOTE] Tab-completion works everywhere in the shell — press Tab instead
+of typing full paths or command names.
+
+---
+
+## SECTION: Package management with zypper
+<!-- source: ce-authored -->
+
+zypper is SUSE's command-line package manager, used across Leap, SLES,
+and Tumbleweed.
+
+To search for a package:
+
+```sh
+zypper se search-term
+```
+
+To install a package:
+
+```sh
+zypper in package-name
+```
+
+To remove a package:
+
+```sh
+zypper rm package-name
+```
+
+To show details about a package:
+
+```sh
+zypper info package-name
+```
+
+To check whether a package is installed and which version:
+
+```sh
+zypper if package-name
+```
+
+To list configured repositories:
+
+```sh
+zypper lr
+```
+
+To refresh repository metadata:
+
+```sh
+zypper ref
+```
+
+To update installed packages on Leap or SLES:
+
+```sh
+zypper up
+```
+
+To fully sync packages on Tumbleweed:
+
+```sh
+zypper dup
+```
+
+[WARNING] On Tumbleweed, always use `zypper dup`, never `zypper up`.
+Mixing the two commands can break dependency resolution on a rolling
+release.
+
+To check whether a reboot is actually required after updates:
+
+```sh
+zypper ps -s
+```
+
+---
+
+## SECTION: Users, groups, and permissions
+<!-- source: ce-authored -->
+
+To show the current user:
+
+```sh
+whoami
+```
+
+To show which groups the current user belongs to:
+
+```sh
+groups
+```
+
+To run a single command as root:
+
+```sh
+sudo command
+```
+
+To switch to another user's shell:
+
+```sh
+su - username
+```
+
+To add a new user with a home directory:
+
+```sh
+sudo useradd -m username
+```
+
+To add an existing user to a group:
+
+```sh
+sudo usermod -aG groupname username
+```
+
+To set file permissions (owner/group/other):
+
+```sh
+chmod 750 filename
+```
+
+To change file ownership:
+
+```sh
+chown user:group filename
+```
+
+To change your own password:
+
+```sh
+passwd
+```
+
+[WARNING] If sudo ever asks for root's password on this system, that
+means elevation is not possible — root is locked (confirmed via
+`passwd -l root`), so there is no password that will authenticate
+against it. This is not a "try harder" situation — retyping it more
+carefully won't help, there is no correct answer to give it. It means
+the intended sudo configuration (own-password authentication via
+`sudo-policy-wheel-auth-self` + `wheel` membership) is not in effect,
+and the system needs to be fixed at the console or reinstalled, not
+worked around.
+
+Ask me how I know.
+
+---
+
+## SECTION: Services with systemd
+<!-- source: ce-authored -->
+
+To check whether a service is running, with recent log lines:
+
+```sh
+systemctl status service-name
+```
+
+To start a service immediately:
+
+```sh
+sudo systemctl start service-name
+```
+
+To stop a service immediately:
+
+```sh
+sudo systemctl stop service-name
+```
+
+To restart a service (stop then start):
+
+```sh
+sudo systemctl restart service-name
+```
+
+To make a service start automatically at boot:
+
+```sh
+sudo systemctl enable service-name
+```
+
+To prevent a service from starting at boot:
+
+```sh
+sudo systemctl disable service-name
+```
+
+To list every service that failed to start:
+
+```sh
+systemctl --failed
+```
+
+To list all known services:
+
+```sh
+systemctl list-units --type=service
+```
+
+[NOTE] `enable` and `start` are separate actions — enabling a service
+does not start it immediately, and starting a service does not make it
+survive a reboot. To do both at once:
+
+```sh
+sudo systemctl enable --now service-name
+```
+
+---
+
+## SECTION: Storage and disks
+<!-- source: ce-authored -->
+
+To show free space per mounted filesystem:
+
+```sh
+df -h
+```
+
+To show the total size of a folder:
+
+```sh
+du -sh directory/
+```
+
+To list block devices and partitions:
+
+```sh
+lsblk
+```
+
+To show what's currently mounted and where:
+
+```sh
+mount
+```
+
+To mount a device manually:
+
+```sh
+sudo mount /dev/device-name /mount-point
+```
+
+To check a drive's health quickly:
+
+```sh
+sudo smartctl -H /dev/device-name
+```
+
+---
+
+## SECTION: Btrfs and Snapper — SUSE default root filesystem
+<!-- source: ce-authored -->
+
+SUSE uses Btrfs as the default root filesystem, with Snapper managing
+automatic snapshots.
+
+To list available snapshots:
+
+```sh
+snapper list
+```
+
+To roll back to a specific snapshot number:
+
+```sh
+sudo snapper rollback snapshot-number
+```
+
+To show real Btrfs space usage:
+
+```sh
+btrfs filesystem usage /
+```
+
+[NOTE] Snapper automatically takes snapshots before and after package
+changes — a broken update is usually a rollback away from being fixed,
+without needing to reinstall anything.
+
+---
+
+## SECTION: Networking
+<!-- source: ce-authored -->
+
+To show interfaces and IP addresses:
+
+```sh
+ip a
+```
+
+To show the routing table:
+
+```sh
+ip r
+```
+
+To show what's listening on which port:
+
+```sh
+ss -tlnp
+```
+
+To test basic reachability to a host:
+
+```sh
+ping hostname-or-ip
+```
+
+To show a NetworkManager device overview:
+
+```sh
+nmcli device status
+```
+
+To show current firewall rules for the default zone:
+
+```sh
+sudo firewall-cmd --list-all
+```
+
+To apply firewall configuration changes:
+
+```sh
+sudo firewall-cmd --reload
+```
+
+[WARNING] Firewall changes made with `firewall-cmd` alone are temporary
+and do not survive a reboot. Add `--permanent` to the change itself,
+then run `--reload` to apply it.
+
+---
+
+## SECTION: Logs and troubleshooting
+<!-- source: ce-authored -->
+
+To show recent logs with explanations, newest entries last:
+
+```sh
+journalctl -xe
+```
+
+To show logs for one specific service:
+
+```sh
+journalctl -u service-name
+```
+
+To show logs since the last boot:
+
+```sh
+journalctl -b
+```
+
+To show logs within a specific time window:
+
+```sh
+journalctl --since "1 hour ago"
+```
+
+To show kernel and hardware messages with timestamps:
+
+```sh
+dmesg -T | tail -50
+```
+
+To generate a full diagnostic bundle for SUSE support:
+
+```sh
+sudo supportconfig
+```
+
+[NOTE] When something breaks unexpectedly, check `systemctl --failed`
+first to find what's actually broken, then run
+`journalctl -u <that service> -xe` to see the actual error.
+
+---
+
+## SECTION: Processes and resources
+<!-- source: ce-authored -->
+
+To show a live view of processes and resource usage (press `q` to
+quit):
+
+```sh
+top
+```
+
+A friendlier alternative, if installed:
+
+```sh
+htop
+```
+
+To find a specific running process:
+
+```sh
+ps aux | grep process-name
+```
+
+To ask a process to stop:
+
+```sh
+kill process-id
+```
+
+To force-stop a process as a last resort:
+
+```sh
+kill -9 process-id
+```
+
+To show memory usage in human-readable form:
+
+```sh
+free -h
+```
+
+To show how long since the last reboot and the current load average:
+
+```sh
+uptime
+```
+
+---
+
+## SECTION: Files you'll actually open
+<!-- source: ce-authored -->
+
+| File | Type | Purpose |
+|---|---|---|
+| `/etc/hostname` | `path` | The system's hostname |
+| `/etc/fstab` | `path` | What mounts automatically at boot |
+| `/etc/ssh/sshd_config` | `path` | SSH server settings |
+| `/etc/sudoers.d/` | `path` | Sudo permission drop-in files |
+| `/var/log/` | `path` | Traditional log location — most logging now lives in `journalctl` instead |
+| `~/.bashrc` | `path` | The current user's own shell startup customizations |
+
+[WARNING] Never hand-edit `/etc/sudoers` directly — always use `visudo`
+or a file in `/etc/sudoers.d/`. A syntax error in sudoers can lock out
+sudo access entirely.
+
+---
+
+## SECTION: Updating the system
+<!-- source: ce-authored -->
+
+To refresh and update on Leap or SLES:
+
+```sh
+zypper ref && zypper up
+```
+
+To refresh and fully sync on Tumbleweed:
+
+```sh
+zypper ref && zypper dup
+```
+
+To list available patches on Leap or SLES:
+
+```sh
+zypper lp
+```
+
+To apply patches specifically:
+
+```sh
+zypper patch
+```
+
+To confirm whether a reboot is required after updating:
+
+```sh
+zypper ps -s
+```
+
+[NOTE] A snapshot is taken automatically before most updates via
+Snapper — if an update goes wrong, rollback (Section: Btrfs and Snapper)
+is usually available without reinstalling anything.
+
+---
+
+## SECTION: Quick glossary
+<!-- source: ce-authored -->
+
+| Term | Type | Meaning |
+|---|---|---|
+| `YaST` | `string` | SUSE's central configuration tool, available as TUI or GUI |
+| `zypper` | `string` | SUSE's command-line package manager |
+| `Snapper` | `string` | Automatic Btrfs snapshot manager |
+| `AutoYaST` | `string` | SUSE's unattended/scripted install system |
+| `targetpw` | `string` | SUSE's default sudo behavior — asks for root's password, not the invoking user's own, unless changed |
+| `wheel` | `string` | The group typically granted sudo access |
+
+---
+
+## SECTION: When you're stuck
+<!-- source: ce-authored -->
+
+1. Run `systemctl --failed` — confirm what's actually broken.
+2. Run `journalctl -u <service> -xe` — see what the actual error says.
+3. Run `snapper list` — check whether a rollback is the fastest fix.
+4. Check documentation.suse.com for the exact release in use before
+   assuming a fix found elsewhere applies.
+5. If still stuck, run `sudo supportconfig` and hand the resulting
+   bundle to whoever supports the system.
+
+[WARNING] This reference covers the commands used most days. It is not
+a substitute for the official documentation for the specific SUSE
+release in use — commands, defaults, and package names shift between
+versions.
+
+---
+**Source:** CE OS — tinkerpad13 personal quick reference, developed 2026-07-26
+**Source-type:** `ce-authored`
+**Licence:** John A. Hoeven with the ethical assistance of Claude AI — personal working document
+**Verified-on:** tinkerpad13 (openSUSE Tumbleweed) — sudo/root behavior confirmed on this system directly; general commands are standard SUSE-family behavior
+**Session:** 2026-07-26