Polish docs and demo assets for first-time adopters

[paul-cch]

Polish docs and demo assets for first-time adopters

Labels: good first issue, roadmap, docs, demo

Summary

Improve first-run docs and demo material so a new adopter can understand the
proof ladder, run the CLI, and see a passing source-only check quickly.

Why

Homelab Operator is easiest to trust when the examples make the proof boundary
obvious. A compact demo path can show the value without exposing private
infrastructure or implying live verification.

Proposed Scope

• Add or polish a short demo script using synthetic fixtures.
• Add screenshots, terminal transcript snippets, or asciinema-style notes only
  if they are fully synthetic.
• Tighten first-run docs around install, commands, expected output, and blockers.
• Add a checklist for reviewers evaluating a source-only PR.

Acceptance Criteria

• A new user can run one documented source-only flow from a clean checkout.
• Demo output uses synthetic names and no private operational material.
• Docs distinguish repo proof from runtime or live-service proof.
• Existing validation commands still pass.

Out Of Scope

• Demoing real deployments.
• Publishing private runbooks or logs.
• Changing package behavior unless needed for a documented demo command.

[13-Prabhat]

Hi @paul-cch 👋

I'd love to take this on if it's available.

I'm a CS student and have been contributing to open-source projects recently. I went through the issue and my plan is to:

Add a short demo script using synthetic fixtures
Improve the first-run documentation (installation, commands, and expected output)
Add a simple reviewer checklist for source-only PRs
Make sure all demo output remains fully synthetic with no private data involved

If that sounds good, could you assign this issue to me? I'm happy to share a quick outline before I start working on it.

[paul-cch]

This was generated by AI during triage.

Thanks, @13-Prabhat. I've assigned this to you. Please go ahead.

Keep the demo, fixtures, and any screenshots or transcript snippets fully
synthetic. Keep the proof at repo_only and do not claim runtime or
live-service proof. Update the relevant first-run docs, run the repository
tests, homelab-operator doctor --root ., and the privacy scan, then use the
pull request template to list the changed paths, validation, and claim
boundary. Please reference this issue in the pull request.