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 context set by sqlcmd config use-context earlier in the same command, else the 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	Dropped. page archive --unarchive is listed in --help, but UnarchivePage (internal/api/confluence.go, v1.14.0 and main) returns an error without calling any API, because Confluence Cloud has no restore endpoint. The existing "410 Gone (unarchive removed - use web UI)" note and the "via web UI only - no restore API" tip are kept unchanged.
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 header now requires v1.14.0, so --reply-to (which notifies the author since v1.14.0) is documented without the old v1.13.0 branches.
n8nctl transfer note	workflow transfer moves the workflow's credentials unless --skip-credentials is passed: "Credentials move too (changing who can use them) unless --skip-credentials", and the doc says to confirm the target project with the user first.
atl 1.14.0 / n8nctl 1.3.0 additions	jira assets attributes <object-type-id>, jira api --api-version 2 (v3 stays the default), and n8nctl variable … --project <id> for project-scoped variables. The m365 Tips bullet that repeated Safety rule 3 is removed.
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.
• 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 ${.
• At 11ed9dd: npm test 6 pass, 0 fail; eslint and prettier --check clean. The atl 1.14.0 and n8nctl 1.3.0 additions were checked against the tagged sources (gh api …/contents/…?ref=<tag>).

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]

Ratatoskr reviewed this pull request.

Approved on 6ae37a94. See the review.

Finished 2026-10-07 06:18 UTC.

[fank]

APPROVE: 0 blocking findings. The earlier --unarchive blocker is fixed at 6ae37a9, and the new flags match the tool sources.

Review details

Reviewed head 6ae37a9484572b79247db2353f52e549b90d58e9. It is up to date with main, and the only changed file is lib/llm/index.js.

Earlier blocker: resolved

• The confluence page archive --unarchive example is removed. lib/llm/index.js:396 again has the "410 Gone (unarchive removed - use web UI)" note, and :403 again has "Archive is reversible (via web UI only - no restore API), delete is not". Both lines now match main.

Verified against source

• atl-cli v1.14.0:
  • jira issue attachment has -d/--download ("requires --id"), --id, -a/--download-all, -o/--output (default .) and a repeatable -u/--upload (internal/cmd/issue/attachment.go:78-83).
  • jira issue assign --assignee accepts @me, and - unassigns it (assign.go:53,79).
  • jira issue changelog --field exists (changelog.go:68).
  • transition -c/--comment exists (transition.go:61).
  • confluence page edit -a/--append exists (confluence/page/edit.go:60).
  • auth refresh --hostname exists (auth/refresh.go:48), and so does doctor (internal/cmd/doctor/).
• n8n-cli v1.3.0: workflow transfer <workflow-id> <project-id> transfers the credentials unless --skip-credentials is passed (internal/cmd/workflow/workflow.go:540-578). The new "confirm the target project with the user first" note fits that behavior.
• m365 (public pnp/cli-microsoft365 source): spo file remove documents -f, --force ("Don't prompt for confirming…"). Commands such as spo cdn origin remove define only force (alias f) and no confirm option. That supports replacing --confirm with -f/--force in step 3 and in the tip (:782, :878, :1251). --confirm no longer appears anywhere in the file.
• sqlcmd: the doc rule (:65-67) and the generated block (:1240-1242) now both resolve the -S server first. The two copies match each other.
• Wording changes: I compared every changed CRITICAL/NEVER/DO NOT/NOT line with the old text. Each rule and step is still there; only the emphasis changed.

Optional, non-blocking

• :639-640: in "Credentials move too unless --skip-credentials, which changes who can use them", the "which" could be read as referring to --skip-credentials instead of the credential move. Something like "Credentials move too (changing who can use them) unless --skip-credentials is passed" would remove the ambiguity.

Tests and checks

• This is a docs-only change inside a template string. No test pins the CLI_DOCS content, which is how the repository already works, so it does not block this PR.
• node --check lib/llm/index.js passes. I could not run npm test because node_modules is not installed in the review checkout, and I did not run npm install. CI Lint, Check format and CodeQL pass. The License Check was skipped, and the PR checks have no test job.
• The atl, n8nctl and m365 binaries are not installed here, so I checked flags against source at the tagged versions, not with --help.

Earlier discussions

• r4195690670 (mine, --unarchive example): verified fixed, replied and resolved.
• r4195690676 (mine, archive-reversible tip): verified fixed, replied and resolved.
• r4184646231 (gemini-code-assist, quoting "Done"): already resolved, and the current head quotes it at :265. I left it alone.

[ravor-x]

/gemini review

[gemini-code-assist]

Code Review

This pull request updates the LLM system prompt and tool documentation in lib/llm/index.js. Key changes include refining safety rules for sqlcmd and m365 (such as resolving the target server/database and warning against -f/--force instead of --confirm), updating various CLI commands for atl (adding token refresh, doctor, issue assignment, transition comments, and attachment options), documenting the --append flag for Confluence, and adding n8nctl workflow transfer and project listing commands. Additionally, several instances of uppercase emphasis (e.g., 'CRITICAL', 'NEVER', 'DO NOT') were toned down to standard casing or replaced with 'Safety'. There are no review comments, and I have no additional feedback to provide.

[ravor-x]

/gemini review

[ravor-x]

Dispositions for the Ratatoskr reviews (changes-requested summary, changes-requested review, approve summary):

• Blocker, --unarchive is a stub: FIXED in 6ae37a9, as the approving review confirmed. Both original notes are restored.
• Optional note, "which" in the n8nctl transfer line is ambiguous: FIXED in 11ed9dd. It now reads "Credentials move too (changing who can use them) unless --skip-credentials".

11ed9dd also fixes what the independent readiness reviews found:

• The header now requires atl v1.14.0, and --reply-to is documented without the v1.13.0 branches.
• It adds jira assets attributes, jira api --api-version 2 and n8nctl --project for project-scoped variables.
• sqlcmd step 1 now says "the context set by sqlcmd config use-context earlier in the same command, else the current context" instead of "chained".
• It removes the m365 tip that repeated Safety rule 3.

[gemini-code-assist]

Code Review

This pull request updates the documentation and instructions for various CLI tools (such as sqlcmd, atl, n8nctl, and m365) in lib/llm/index.js, adding new commands, updating safety rules, and softening capitalization. A review comment suggests improving the Git documentation by using origin/HEAD instead of the placeholder to make the commands fully copy-pasteable and directly executable.

[ravor-x]

🔏 Readiness attested — the pr-readiness-check gate completed for PR #131 at 11ed9dd2487ec7f51dce8bbc241ddcd9c78244af (2026-10-07T14:17:53Z). If the branch head has moved, this evidence covers the earlier state only.

Readiness summary

PR Readiness Check (#131, 11ed9dd)
Review mode INITIAL
Branch/base PASS (contains origin/main; clean; head pushed)
Local verification PASS (node --test 6/6; eslint clean; prettier --check clean)
Remote CI PASS: NPM (Lint, Check format) run 37633638010 success; CodeQL 37633632134 success. DEFERRED UNTIL READY: License NPM (37633637908 skipped on draft; ready_for_review type). Excluded: Publish (release only).
Coverage NOT REPORTED
Automated reviewers PASS (gemini-code-assist reviewed 11ed9dd)
Review threads PASS (0 unresolved; Gemini origin/HEAD suggestion ADVISORY with reason)
Review comments PASS (open-review-comments.sh exit 0; Florian's blocker FIXED in 6ae37a9, optional note FIXED in 11ed9dd)
Council findings DISPOSITIONED, 2 rounds, both DEGRADED (jury 1/3; deepseek auth failure). R1: 1 Minor REFUTED (m365 11.11.0 --help shows -f, --force). R2: 1 Important + 1 Minor REFUTED (flags verified against atl-cli v1.14.0 source). Stopped: no new actionable finding.
Standards review DISPOSITIONED (1 Important + 3 Minor FIXED in 11ed9dd)
Spec review DISPOSITIONED (1 Important + 1 Minor FIXED in 11ed9dd; alias note needed no change)
PR description PASS (updated for 11ed9dd)
SQL/UI evidence SKIP
Rollout: needs an llm-cli-setup release and a version bump in environment-setup.
Dispositions: ~/dev/.files/llm-cli-setup-pr-131/council-dispositions.md
Result: READY