docs(oo): comment where the new helpers are used

- link.go/links.go: third-party doc packs (fileid links), id-stability caveat
- auth.go AuthenticateAs / users check: email-vs-userName login finding
- projects files replace-in: version-history rationale

cmd/oo/link.go

@@ -9,6 +9,11 @@ func init() {
 	rootCmd.AddCommand(linkCmd())
 }
 
+// linkCmd prints deep links for file ids. Used to build the third-party
+// document packs (e.g. the arc-1 "Lisbon apartment" Info cover embeds links to
+// passports, contracts and the income documents). File ids come from
+// `oo projects files list` / `oo dav ls`; `oo projects files replace-in` keeps
+// them clean when a document is re-uploaded.
 func linkCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "link FILE_ID [FILE_ID...]",

cmd/oo/projects_files.go

@@ -157,7 +157,12 @@ func prjFilesReplaceInCmd() *cobra.Command {
 		Short: "Replace same-named file(s) in a folder: hard delete + fresh upload (no version history)",
 		Long: `Deletes any file in FOLDER_ID with the same stem|ext (hard delete — the CLI
 delete is permanent) and uploads the local file fresh. Unlike 'update' this
-leaves a single clean version, which matters when the file id is shared.
+leaves a single clean version.
+
+Why it exists: on the arc-1 portal, repeated 'update' of a shared document
+(the apartment "Info" cover and the Edelweiss contract) accumulated a visible
+version history and a stale id. replace-in yields one clean revision; then
+point links at the returned id (or keep an nginx alias for the legacy fileid).
 
 Note: file ids are server-assigned; a fresh upload gets a new id.`,
 		Args: cobra.MinimumNArgs(2),

cmd/oo/users.go

@@ -319,8 +319,13 @@ func usersCheckCmd() *cobra.Command {
 		Use:   "check",
 		Short: "Check that a login can authenticate (userName or email)",
 		Long: `Probes POST /api/2.0/authentication.json with the given credentials and
-discards the token. On this portal the account email is the reliable login
-identifier (userName login may fail); use this before sharing credentials.`,
+discards the token.
+
+Where this is used: before handing portal credentials to an external party
+(e.g. a landlord given read access to the apartment document pack), verify the
+login actually works. On the arc-1 portal the account email is the reliable
+login identifier — the userName login fails with 500 for a freshly created
+user, so share the email, not the userName.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if login == "" {
 				return fmt.Errorf("--login is required (userName or email)")