docs(llm): fix m365 force flag, atl attachment/unarchive syntax, safety labels

[ravor-x]

Problem

An audit of the generated CLI docs (lib/llm/index.js) found flags and subcommands that don't exist in the installed tools. Target models follow the docs literally, so a wrong flag produces a wrong command. The audit also found shouting labels (**CRITICAL**, NEVER, DO NOT) that add pressure without adding information.

Changes

Item	Change
8 m365 force flag	m365 v11 has no --confirm; the prompt-skipping flag is -f, --force. Step 3 of the m365 rule (cli-m365 doc and generated CLAUDE.md block) and the cli-m365 tip now name -f/--force. Steps 1–2 are unchanged.
10 sqlcmd write target	Steps 1–2 of the sqlcmd write rule (cli-sqlcmd doc and generated CLAUDE.md block) now resolve and show the actual target: the -S server if the command passes one, otherwise the chained or current context. Before, they showed sqlcmd config current-context, which shows stage/local while a -S write goes to the production MI. Step 3 (explicit confirmation) is unchanged.
14 register	**CRITICAL**: → **Safety**: in cli-sqlcmd, cli-m365, cli-hcloud and cli-ovhcloud, which matches the generated block. Steps are unchanged; the sqlcmd write-safety steps are untouched. Caps were lowered only where the line already gives its reason (gh reviews endpoint, ADF mention syntax, gcx stack-login restart, gcx --cloud-token, playwright Basic Auth, Confluence --body). No constraint was removed.
26 atl attachment	--download <id> → --download --id <id>; added --download-all and --upload.
27 atl unarchive	Removed "410 Gone (unarchive removed - use web UI)". Added page archive <id> --unarchive. The tip now reads "Archive is reversible (archive --unarchive), delete is not".
28 aliases/pins	Removed the deprecated-alias sentence; the doc now points only to the jira … command forms. Removed the v1.12.0+ pins: every example passes --context, which needs ≥ v1.13.0 (the doc header already requires this). The --reply-to version note stays, because it describes a behavior difference rather than a feature gate.
29 gh fetch	git fetch origin main → git fetch origin <default-branch> (master or main).
31 missing capabilities	Atlassian CLI: jira issue assign, jira issue changelog, doctor, auth refresh, transition --comment, confluence page edit --append, attachment --upload. n8nctl: project list, workflow transfer. Skipped: n8nctl variable (already documented). Skipped: gh attach list/get, because gh attach is not documented in this package. Its doc (negsoft-pr-screenshots.md) comes from environment-setup src/llm_internal.js, so it is a follow-up there.

Verification

Each flag and subcommand was checked against the installed binaries with read-only --help. go version -m reports atl-cli v1.14.0, n8n-cli v1.3.0 and m365 v11.11.0:

• m365 spo file remove --help, spo list remove --help and spo site remove --help all show -f, --force — Don't prompt for confirm…. None of them has --confirm.
• jira issue attachment --help shows -d, --download Download a specific attachment (requires --id), --id, -a, --download-all, -u, --upload stringArray and -o, --output.
• confluence page archive --help shows -u, --unarchive Unarchive (restore) pages instead of archiving.
• jira issue assign --help shows --assignee (@me, or - to unassign). jira issue changelog --help shows --field and --limit. jira issue transition --help shows -c, --comment. confluence page edit --help shows -a, --append. doctor --help and auth refresh --help (--hostname) both exist.
• n8nctl project --help lists only list. n8nctl workflow transfer --help shows <workflow-id> <project-id> and --skip-credentials.
• The rendered CLI_DOCS content contains no leftover --confirm, CRITICAL or NEVER, and no stray ${.
• npm test: 6 pass, 0 fail. npm run lint: clean. npm run check-format: clean.

Rollout

environment-setup uses the published @enthus-appdev/llm-cli-setup package, so these docs reach developer machines only after a release of this package and a bump in environment-setup.

[gemini-code-assist]

Code Review

This pull request updates the documentation in lib/llm/index.js for several CLI tools, including sqlcmd, git, atl, n8nctl, gcx, and m365. Key updates include renaming 'CRITICAL' safety headers to 'Safety', replacing hardcoded branch names with placeholders, adding new commands for Jira, Confluence, and n8nctl, and clarifying safety guidelines regarding the -f/--force flag. The review feedback suggests enclosing the transition name 'Done' in double quotes in the newly added Jira transition example to maintain consistency and prevent potential shell parsing issues.

[fank]

Ratatoskr reviewed this pull request.

Changes requested on 22c4afd6 with 2 inline comments. See the review.

Finished 2026-10-06 13:13 UTC.

[fank]

REQUEST_CHANGES: 1 blocking finding. The new confluence page archive --unarchive guidance documents a command that always fails in every atl-cli release.

Review details

Reviewed head 22c4afd6b107c8fbe076a11d8a7c51581328360f.

Blocking

1. archive --unarchive is a stub that always fails (item 27): lib/llm/index.js:382, :403, and the removed note at old line 388

The --unarchive flag exists in --help, but the implementation never calls an API. In atl-cli v1.13.0, v1.14.0 and current main, internal/api/confluence.go contains:

// UnarchivePage restores an archived page.
// NOTE: Confluence Cloud has no REST API for unarchiving pages.
// The v1 workaround using PUT /content/{id} was deprecated (410 Gone).
// Users must restore archived pages via the Confluence web UI.
func (s *ConfluenceService) UnarchivePage(ctx context.Context, pageID string) error {
	return fmt.Errorf("unarchive is not supported via API - ... Please use the Confluence web UI to restore archived pages")
}

runArchive in internal/cmd/confluence/page/archive.go calls it for each page ID and reports Failed to unarchive page …. The text this PR removes ("410 Gone (unarchive removed - use web UI)" and "reversible (via web UI only - no restore API)") was correct. The replacement is wrong in two ways:

• It sends agents to a command that cannot succeed.
• The tip "Archive is reversible (archive --unarchive)" tells the model that it can undo an archive itself. An agent that believes this may archive pages more readily. In practice, only a human in the web UI can restore them.

Checking --help alone can't catch this. The flag is registered, but nothing behind it calls an API.

Fix: drop the --unarchive example line and restore both the API note and the "via web UI only" tip. Option: keep a line that says --unarchive exists but returns an error, so agents don't try it.

Verified correct (against atl-cli v1.13.0 source, the floor named in the doc header, and n8n-cli v1.3.0)

• jira issue attachment: --download requires --id (attachment.go:70-71). --download-all, --upload (stringArray, repeatable) and --output all exist.
• jira issue assign --assignee (@me, a user, or -), jira issue changelog --field, transition --comment/-c, confluence page edit --append/-a, doctor and auth refresh --hostname all exist in v1.13.0. Removing the v1.12.0+ pins therefore loses nothing.
• The deprecated top-level aliases are still registered (hidden) in v1.14.0 (internal/cmd/root.go:75-79). Dropping the sentence only removes a pointer to a deprecated form, so that change is fine.
• n8nctl workflow transfer <workflow-id> <project-id> with --skip-credentials, and project list, both exist in v1.3.0 (internal/cmd/workflow/workflow.go:540-578, internal/cmd/project/project.go).
• m365 -f/--force replacing --confirm: I did not check this against the m365 binary because it isn't installed here. It does match the PnP CLI's documented change from --confirm to --force since v7, and no --confirm remains in the file.
• sqlcmd write rule: step 1 now names the -S server first. That fixes the real mismatch where current-context showed stage while a -S write went elsewhere. The doc and the generated block (:65, :1239) are in sync.
• Label softening: every rule and step is still present. Only the emphasis changed.

Optional, non-blocking

• n8nctl workflow transfer (:639-640) moves credentials across projects by default. The n8nctl section has no safety rule, which matches how activate is documented today. Still, a short "confirm before transferring" note may be worth adding, because this command changes who can use a credential.

Tests and checks

• This is a docs-only change in a template string, and no test covers CLI_DOCS content. That is consistent with the repository today, so it is not a blocker.
• I could not run node --test locally because dependencies (chalk) are not installed in the review checkout, and I did not run npm install there. CI lint, format and CodeQL pass. There is no test job in the PR checks.

Earlier discussions

• One review thread exists (gemini-code-assist, quoting "Done"). It is already resolved, and the current head quotes the name at :265. No action needed. I did not author it, so I did not touch it.

[fank]

This always fails. In atl-cli v1.13.0, v1.14.0 and current main, UnarchivePage (internal/api/confluence.go) returns unarchive is not supported via API ... Please use the Confluence web UI without making any request. The flag exists in --help, but nothing behind it calls an API. Please drop this line and restore the removed use web UI API note.

[fank]

Archive is only reversible by a human in the Confluence web UI. With this wording, an agent may think it can undo an archive itself and archive more readily. Please restore the previous wording: Archive is reversible (via web UI only - no restore API), delete is not.