`punix help`¶

Show the help overview, or print a focused page for a specific topic.

punix help [TOPIC]

What it does¶

No argument — prints a short overview (quick-command list, where to go for what) followed by the catalogue of available topic pages.
With a topic — renders the named markdown topic page to your terminal (ANSI-coloured headings + inline code on a TTY; plain-text but same structure when piped).
Unknown topic — exits 2 with a message that names every available topic.

The pages live in the wheel itself (importlib.resources lookup) so they ship with every install — no docs-site fetch, no network.

The renderer is hand-rolled (no rich/mistune dep) and handles # / ## / ### headings, **bold**, `inline code`, ``` fenced blocks, - lists, pipe tables (via tabulate), and [label](url) links.

Topics shipped today¶

Topics are listed in reading order (not alphabetical) — start at the top if you're new:

Topic	Covers
`install-workflow`	one-time setup, install/uninstall/list/profile daily loop
`collections`	`packages/official/` + `packages/experimental/from-X/` layout, default discovery, promotion
`generations`	atomic flip on install/uninstall, rollback, garbage-collection pinning
`upstream`	`meta.upstream` declaration, `punix upgrade --check-all`
`migration`	porting recipes from Homebrew / nixpkgs / slapos into `experimental/`
`secrets`	`{from_env}` / `{from_file}` references, what's NOT in the cache
`env`	environment variables Punix reads (`PUNIX_PACKAGES`, `PUNIX_STORE_DIR`, `PATH`)
`errors`	`[E1]`–`[E15]` cheat sheet with cross-references

Example¶

$ punix help
punix — typed declarative build & service deployer.

Quick commands:
  punix install <pkg>     # build + put on $PATH
  punix uninstall <pkg>   # drop from active profile
  punix list              # what's installed
  punix search <regex>    # find packages
  punix info <pkg>        # recipe metadata + predicted store path
  punix upgrade --check-all  # report newer upstream versions
  punix profile list      # generation history
  punix profile switch N  # atomic rollback to gen-N

Per-command flags: `punix <cmd> --help`.
Concept pages:     `punix help <topic>` (topics below).
Full docs:         https://punix.lab.abilian.com/cli/

Topics:
  collections
  errors
  generations
  install-workflow
  migration
  secrets
  upstream

$ punix help collections | head -3
# Package collections

A Punix repository organizes packages into independent **collections**.

$ punix help nope
error: no such help topic 'nope'. Available: collections, errors,
generations, install-workflow, migration, secrets, upstream

Why `punix help` and not just `--help`?¶

--help (built into every command) lists flags and positionals. punix help covers concepts and workflows that span commands — things like "what does a generation manifest record?" or "where does the brew translator put its output?". The two are complementary; the help pages cross-link via punix help <topic> mentions.

Adding a topic¶

Drop a markdown file into src/punix/help/<topic>.md and it shows up automatically next install. No code change. The loader picks up every *.md resource under the package and exposes its filename stem (lowercase, hyphenated) as the topic name.

punix help¶