From 520d6d05c8dc10bdde09afe2118d3471ce71980f Mon Sep 17 00:00:00 2001
From: Andriy Oblivantsev <eslider@gmail.com>
Date: Tue, 22 Sep 2026 19:56:54 +0100
Subject: [PATCH] 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
---
 auth.go                  |  6 ++++--
 cmd/oo/link.go           |  5 +++++
 cmd/oo/projects_files.go |  7 ++++++-
 cmd/oo/users.go          |  9 +++++++--
 links.go                 | 11 +++++++++++
 5 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/auth.go b/auth.go
index 1057743..5a11348 100644
--- a/auth.go
+++ b/auth.go
@@ -103,8 +103,10 @@ func (c *Client) authenticateOnce(ctx context.Context) error {
 // token, and the portal error otherwise.
 //
 // OnlyOffice accepts either the userName or the account email as the login. On
-// some portals the userName login fails while the email works — use this probe
-// to tell them apart before sharing credentials.
+// the arc-1 portal (office.produktor.io) the account userName login returns
+// HTTP 500 "User authentication failed" while the account email succeeds —
+// confirmed for a freshly created guest user. Use this probe before sharing
+// credentials (see `oo users check`), and prefer the email as the login.
 func (c *Client) AuthenticateAs(ctx context.Context, login, password string) error {
 	body, err := json.Marshal(Credentials{User: login, Password: password})
 	if err != nil {
diff --git a/cmd/oo/link.go b/cmd/oo/link.go
index 05aa00e..34a8eae 100644
--- a/cmd/oo/link.go
+++ b/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...]",
diff --git a/cmd/oo/projects_files.go b/cmd/oo/projects_files.go
index c6dbc57..9b63d71 100644
--- a/cmd/oo/projects_files.go
+++ b/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),
diff --git a/cmd/oo/users.go b/cmd/oo/users.go
index 9fa1b69..5fafe58 100644
--- a/cmd/oo/users.go
+++ b/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)")
diff --git a/links.go b/links.go
index eb22fab..3439608 100644
--- a/links.go
+++ b/links.go
@@ -1,6 +1,17 @@
 package onlyoffice
 
 // Deep links to OnlyOffice portal objects.
+//
+// Where this is used: third-party-facing document packs (e.g. the arc-1
+// office.produktor.io "Lisbon apartment" project) embed per-file links of the
+// form /Products/Files/DocEditor.aspx?fileid=<id> in a cover document and in
+// chat messages. Those links must be generated consistently so they match the
+// file ids returned by `oo projects files list` / `oo link`.
+//
+// Caveat proven on the arc-1 portal: file ids are server-assigned and a
+// re-upload/delete yields a NEW id, so an already-shared link can go stale.
+// Use `oo projects files replace-in` (keep the id clean) and, if a legacy link
+// must keep working, an nginx alias can 302 the old fileid to the new one.
 
 import (
 	"fmt"