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/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),