Add help docs and man page

Author: Your Name

README.adoc

@@ -791,3 +791,7 @@ For the latest updates, see link:ROADMAP.adoc[ROADMAP.adoc] and link:STATE.scm[S
 == Problems → Solutions
 
 See link:problems-solutions/README.adoc[problems-solutions] for real-world failure cases and how OPSM should resolve them.
+
+== Help
+
+See link:docs/HELP.adoc[HELP].

docs/HELP.adoc

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= OPSM Help
+:toc: preamble
+:toclevels: 2
+
+== Quick Start
+
+[source,bash]
+----
+opsm install @npm lodash
+opsm search "http client"
+opsm install [rpm-ostree: gcc clang] [toolbox: zig ocaml]
+----
+
+== Smart Install (Dry‑Run)
+
+Use backend grouping to plan installs across rpm‑ostree, toolbox, containers, and source.
+
+[source,bash]
+----
+opsm install [rpm-ostree: gnat ada] [toolbox: zig ghc]
+----
+
+== Policies
+
+* `¬python` — block Python ecosystems
+* Approved‑only installs for users
+* Dry‑run plans always available
+
+== Troubleshooting
+
+If a package is missing or unmaintained, OPSM should:
+
+* warn clearly
+* suggest alternatives
+* provide a reversible plan
+
+See link:../problems-solutions/README.adoc[problems‑solutions].

man/opsm.1

@@ -0,0 +1,48 @@
+.TH OPSM 1 "January 2026" "OPSM" "User Commands"
+.SH NAME
+opsm \- Odds-and-sods package manager
+.SH SYNOPSIS
+.B opsm
+.RI [command] " [options]"
+.SH DESCRIPTION
+OPSM is a federated package manager that resolves across multiple ecosystems and system package managers.
+It supports dry-run planning, trust pipeline checks, and reversible operations.
+.SH COMMANDS
+.TP
+.B install [@forth] <pkg>
+Install a package from a specific registry.
+.TP
+.B install [backend:] ...
+Smart install grouping (dry-run plan by backend).
+.TP
+.B remove <pkg>
+Remove an installed package.
+.TP
+.B search <query>
+Search across registries.
+.TP
+.B info <pkg>
+Show package info.
+.TP
+.B audit <pkg>
+Run sustainability + license analysis.
+.TP
+.B ports
+List available system package managers.
+.SH OPTIONS
+.TP
+.B -n, --dry-run
+Show what would be done.
+.TP
+.B --apply
+Apply smart install plan (when wired).
+.SH CONFIG
+Default config lookup order:
+.BR $OPSM_CONFIG
+, ./opsm.toml, ~/.config/opsm/opsm.toml.
+.SH EXAMPLES
+.nf
+opsm install @npm lodash
+opsm install [rpm-ostree: gcc clang] [toolbox: zig ocaml]
+opsm search "http client"
+.fi