docs: clarify /new vs /reset semantics in slash-commands

[mosabbirrakib]

Summary

• Problem: docs/tools/slash-commands.md:127 summarizes /new and /reset as aliases. They are not. /new archives the current session and starts a fresh one; /reset wipes the current session in place. The line directly below already admits this (Control UI intercepts /new to create a fresh dashboard session, while typed /reset runs the Gateway's in-place reset), so the summary contradicts itself.
• Why it matters: users reading the summary line believe the two commands are interchangeable and pick /reset thinking they can recover the old context. They cannot — the previous transcript is gone. Reported as docs: "/reset is the reset alias" is misleading — /new and /reset are not aliases #76592 with a real user-impact framing ("until they lose their session data").
• What changed: rewrote the one misleading bullet in docs/tools/slash-commands.md to give an accurate one-line distinction and explicitly state they are not aliases. Pointer to the existing follow-up bullets for the Control UI session.dmScope: "main" case and the ACP-bound channel case where they do collapse to an in-place reset.
• What did NOT change (scope boundary): no other docs surfaces, no source code, no behavior change. Skipped the issue's optional suggestion Images not passed to Claude CLI - only path reference in text #4 (renaming /reset to /clear or /wipe) because that is a behavior/UX change, not a docs fix.

Change Type (select all)

• Docs

Scope (select all touched areas)

• UI / DX

Linked Issue/PR

• Closes docs: "/reset is the reset alias" is misleading — /new and /reset are not aliases #76592
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: docs/tools/slash-commands.md:127 documented /reset as "the reset alias" of /new. That phrasing told users the commands were interchangeable, while the very next bullet in the same file already noted the Control UI//reset paths behave differently. This PR replaces the misleading bullet with an accurate one-line distinction (/new archives + starts fresh; /reset wipes in place; not aliases) and points to the existing follow-up bullets for the contexts where both collapse to the same in-place reset.

• Real environment tested: Local macOS workstation with Node 22.17.1 against the new branch docs/fix-reset-alias-misleading branched from openclaw/openclaw:main at 7a9613e66b. Verified the misleading wording occurrence count, the rewritten bullet, MDX validity, doc formatting, and internal link health using the repo's own docs scripts via node.

• Exact steps or command run after this patch:

  # 1. Confirm the misleading "reset alias" phrasing no longer exists anywhere in docs
  grep -rn "reset alias\|is the reset alias" docs/ src/
  
  # 2. Confirm the new wording is in place on the touched line
  sed -n '125,130p' docs/tools/slash-commands.md
  
  # 3. Validate the file as MDX
  node scripts/check-docs-mdx.mjs docs/tools/slash-commands.md
  
  # 4. Repo-wide docs formatting check
  node scripts/format-docs.mjs --check docs/tools/slash-commands.md
  
  # 5. Internal docs link audit (catches any new broken anchor introduced)
  node scripts/docs-link-audit.mjs
  
  # 6. Confirm diff scope is exactly one line on the intended file
  git diff --stat upstream/main..HEAD -- docs/
  

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Terminal output captured from the steps above against the branch tip:

  $ grep -rn "reset alias\|is the reset alias" docs/ src/
  (no matches)
  
  $ sed -n '125,130p' docs/tools/slash-commands.md
  <AccordionGroup>
    <Accordion title="Sessions and runs">
      - `/new [model]` archives the current session and starts a fresh one; `/reset` wipes the current session in place. They are not aliases — see the bullet below for Control UI and ACP-bound channel contexts where both collapse to the same in-place reset.
      - Control UI intercepts typed `/new` to create and switch to a fresh dashboard session, except when `session.dmScope: "main"` is configured and the current parent is the agent's main session; in that case `/new` resets the main session in place. Typed `/reset` still runs the Gateway's in-place reset.
      - `/reset soft [message]` keeps the current transcript, drops reused CLI backend session ids, and reruns startup/system-prompt loading in-place.
  
  $ node scripts/check-docs-mdx.mjs docs/tools/slash-commands.md
  Docs MDX check passed (1 files, 26ms).
  
  $ node scripts/format-docs.mjs --check docs/tools/slash-commands.md
  Docs formatting clean (623 files).
  
  $ node scripts/docs-link-audit.mjs
  checked_internal_links=4345
  broken_links=0
  
  $ git diff --stat upstream/main..HEAD -- docs/
   docs/tools/slash-commands.md | 2 +-
   1 file changed, 1 insertion(+), 1 deletion(-)
  

• Observed result after fix: The repo-wide grep for "reset alias" or "is the reset alias" returns zero matches, confirming the misleading phrasing has been removed from both docs/ and src/. The rewritten bullet at line 127 reads as a clear one-sentence distinction (/new archives + starts fresh; /reset wipes in place) followed by an explicit "They are not aliases" statement and a pointer to the existing follow-up bullet that already documents the Control UI session.dmScope: "main" carve-out and the ACP-bound channel context (the only places where both commands collapse to the same in-place reset). MDX parses cleanly, oxfmt reports the touched file is already formatted, and the docs link audit reports zero broken internal links across 4345 checked references. The diff is exactly 1 line changed on 1 file.

• What was not tested: Production Mintlify rendering at docs.openclaw.ai/tools/slash-commands#sessions-and-runs, which only resolves after merge. The actual runtime behavior of /new vs /reset was not exercised because this PR makes no runtime change; the new wording is verified against the existing, separately-documented behavior in the next bullet of the same accordion (Control UI dmScope main carve-out) and the cross-references in docs/tools/acp-agents.md and the per-channel docs.

• Before evidence (optional but encouraged): The misleading line as it stood before this patch:

  - `/new [model]` starts a new session; `/reset` is the reset alias.
  

  Public-docs URL of the existing page on production Mintlify: https://docs.openclaw.ai/tools/slash-commands. The same accordion already contained the line Typed /reset still runs the Gateway's in-place reset. directly below the removed bullet, which is the self-contradiction the original issue flagged.

Root Cause (if applicable)

N/A — this is a docs-only correction, not a bug fix.

Regression Test Plan (if applicable)

N/A — no behavior change. A docs/grammar regression of this exact kind would be caught by a reviewer reading the file or by a maintainer noticing the contradiction across adjacent bullets. There is no narrowly-scoped automated test that would flag a misleading English summary inside an accordion bullet.

User-visible / Behavior Changes

• Documentation only. Users reading https://docs.openclaw.ai/tools/slash-commands will no longer be told that /reset is an alias of /new. They will instead see a one-sentence distinction (/new archives + starts fresh; /reset wipes in place; not aliases) plus a pointer to the existing follow-up bullets that already document the Control UI and ACP-bound channel contexts where both collapse to the same in-place reset.
• No CLI flag, config, default, or runtime behavior changed.

Diagram (if applicable)

N/A

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS (any host that can render Mintlify docs)
• Runtime/container: N/A (docs change)
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Open docs/tools/slash-commands.md and locate the Sessions and runs accordion under Core built-in commands.
2. Read the first bullet.
3. Compare against the immediately following bullet describing Control UI and /reset behavior.

Expected

• The summary bullet for /new and /reset accurately distinguishes the two commands and does not call /reset an alias.
• The summary is consistent with the next bullet, which already documents that Control UI intercepts /new to create a fresh dashboard session while typed /reset runs the Gateway's in-place reset.

Actual

• After this patch: bullet at line 127 reads /new [model] archives the current session and starts a fresh one; /reset wipes the current session in place. They are not aliases — see the bullet below for Control UI and ACP-bound channel contexts where both collapse to the same in-place reset.
• Repo-wide grep for the old "reset alias" phrasing returns zero matches in docs/ and src/.

Evidence

• Trace/log snippets (terminal output of grep, check-docs-mdx, format-docs --check, docs-link-audit, and git diff --stat above)

Human Verification (required)

• Verified scenarios:
  • The exact misleading phrasing in docs: "/reset is the reset alias" is misleading — /new and /reset are not aliases #76592 (/reset is the reset alias) is the only occurrence in the repo and has been removed.
  • The replacement bullet is internally consistent with the next bullet in the same accordion (Control UI dmScope main carve-out + typed /reset runs in-place reset).
  • The replacement is consistent with the existing wording in docs/tools/acp-agents.md:459, docs/channels/discord.md:846, docs/channels/imessage.md:331, and docs/channels/matrix.md:544, which describe the ACP-bound channel context where both commands do collapse to an in-place reset of the bound session.
  • Repo MDX validation, oxfmt formatting check, and docs link audit pass against the new branch tip.
• Edge cases checked:
  • Confirmed there is no second misleading "alias" sentence elsewhere in docs/ (grep across the tree).
  • Confirmed /reset soft continues to be documented separately on the next-next bullet and is unaffected by this change.
  • Confirmed the linked issue [Bug]: /new command spawns subagent instead of resetting session #53335 (which the original issue cites as having been closed using the misleading wording as justification) is not re-opened by this PR; this PR only fixes the docs sentence.
• What you did not verify:
  • Live Mintlify production render at docs.openclaw.ai/tools/slash-commands after merge.
  • The behavioral suggestion in requirement Images not passed to Claude CLI - only path reference in text #4 of the issue (renaming /reset to /clear or /wipe) — out of scope for a docs PR.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: the new wording overstates the difference and confuses users in ACP-bound channels who do experience both commands as equivalent.

  • Mitigation: the new bullet explicitly points to the follow-up bullet, and the ACP-bound channel docs (docs/tools/acp-agents.md, docs/channels/discord.md, docs/channels/imessage.md, docs/channels/matrix.md) continue to document the "both reset the bound ACP session in place" behavior in their own context. The cross-reference keeps users from being surprised.

• Risk: future code changes that genuinely make /reset an alias of /new would silently leave this docs line wrong.

  • Mitigation: low likelihood given the existing Control UI carve-out (session.dmScope: "main") and the ACP-bound channel binding mechanism both rely on the commands behaving differently in the default case. If the policy is ever reversed, the file will need to be updated again — but that is true of any behavior-specific documentation.

[clawsweeper]

Codex review: passed.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
The PR changes one bullet in docs/tools/slash-commands.md to distinguish /new from /reset and remove the misleading alias wording.

Reproducibility: yes. Reading current main reproduces the misleading docs line at docs/tools/slash-commands.md:127, and adjacent source/tests show /new and /reset take different paths in the Control UI.

PR rating
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Summary: Focused docs-only correction with source-aligned wording, supplied terminal proof, and no blocking findings.

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

PR egg
✨ Hatched: 🥚 common Neon Lint Imp

        /\     /\            
      _/  \___/  \_          
     /  ( o   o )  \         
    |      \_/      |        
    |   /\  ===  /\ |        
     \_/  \_____/  \_/       
        _/|_| |_|\_          
       /__| | | |__\         
          ' ' ' '            
         /_/     \_\         
       .-----------.         
      '-------------'        

Rarity: 🥚 common.
Trait: hums during re-review.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Neon Lint Imp in ClawSweeper.

What is this egg doing here?

• Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
• The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
• How to hatch it: reach status: 👀 ready for maintainer look or status: 🚀 automerge armed; that usually means sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness.
• The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
• Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

Real behavior proof
Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Next step before merge
No repair lane is needed because the final head already contains the narrow docs fix and is suitable for normal exact-head automerge gating.

Security
Cleared: Cleared: the diff is a one-line Markdown documentation change and does not alter code execution, dependencies, workflows, permissions, networking, or secrets handling.

Review details

Best possible solution:

Merge the one-line docs correction through the exact-head automerge path; treat command renaming or stronger reset-warning policy as separate product work.

Do we have a high-confidence way to reproduce the issue?

Yes. Reading current main reproduces the misleading docs line at docs/tools/slash-commands.md:127, and adjacent source/tests show /new and /reset take different paths in the Control UI.

Is this the best way to solve the issue?

Yes. For this PR's scope, replacing the misleading sentence is the narrowest maintainable fix; the optional /reset rename or extra warning would be a separate product decision.

Label justifications:

• P3: This is a low-risk documentation clarification with no runtime, config, dependency, or workflow change.

What I checked:

• PR diff is narrowly scoped: Final head changes only the Sessions and runs bullet so /new [model] archives and starts fresh, while /reset wipes the current session in place, and explicitly says they are not aliases. Public docs: docs/tools/slash-commands.md. (docs/tools/slash-commands.md:127, bb92b6050aab)
• Current main still has the misleading line: Current main says /reset is the reset alias immediately before a bullet that distinguishes Control UI /new from Gateway /reset, so the docs problem is still present before this PR merges. Public docs: docs/tools/slash-commands.md. (docs/tools/slash-commands.md:127, edcf862da5d0)
• Control UI behavior supports the distinction: The UI dispatches typed /new through the new-session slash action, while typed /reset is sent to the Gateway as /reset. (ui/src/ui/app-chat.ts:654, edcf862da5d0)
• Tests cover the non-alias paths: Current tests assert typed /new routes through the fresh-session action and typed /reset is dispatched as a Gateway message. (ui/src/ui/app-chat.test.ts:679, edcf862da5d0)
• Session implementation archives prior transcript on reset-triggered rollover: initSessionState captures the previous session entry, archives transcripts, and tests assert the old transcript is archived on /new, supporting the proposed wording that /new starts fresh rather than being an alias sentence. (src/auto-reply/reply/session.ts:487, edcf862da5d0)
• ACP docs preserve the bound-session carve-out: Existing ACP docs already document that bound conversations treat /new and /reset as in-place resets of the same ACP session key, so the PR does not need to duplicate that caveat in the summary bullet. Public docs: docs/tools/acp-agents.md. (docs/tools/acp-agents.md:459, edcf862da5d0)

Likely related people:

• gumadeiras: The slash-command docs refresh in 17a2290f4932ff193f456ba2fb64b6ef8791d21e reworked this command-list section and is the earliest local -S'reset alias' hit tied to the misleading wording. (role: introduced docs wording; confidence: high; commits: 17a2290f4932; files: docs/tools/slash-commands.md)
• Takhoffman: Recent history shows c37e49f275fbf76b89f3f51a4b950a795a3f5917 changing the same slash-command docs, and the current PR discussion shows Takhoffman enabling automerge for this docs correction. (role: recent adjacent contributor and reviewer; confidence: medium; commits: c37e49f275fb; files: docs/tools/slash-commands.md)
• steipete: Local shortlog shows Peter Steinberger as the largest contributor to this docs file, and the latest release commit 50a2481652b6a62d573ece3cead60400dc77020d still carries the old wording in the shipped docs snapshot. (role: heavy docs file contributor and release carrier; confidence: medium; commits: 50a2481652b6; files: docs/tools/slash-commands.md)

Codex review notes: model gpt-5.5, reasoning high; reviewed against edcf862da5d0.

[mosabbirrakib]

Thanks @clawsweeper — addressed the P3 finding in 158e46be14. The new sentence no longer points at the bullet below for ACP-bound context. It now just states the distinction and stops there; the Control UI carve-out and the ACP-bound channel semantics keep being documented in their existing owning bullets/pages.

Final line:

- /new [model]archives the current session and starts a fresh one;/reset wipes the current session in place. They are not aliases.

[mosabbirrakib]

FYI on the two red checks (security-dependency-audit, security-fast): unrelated to this PR's diff. Reproduced locally on upstream/main (7a9613e66b) with node scripts/pre-commit/pnpm-audit-prod.mjs --audit-level=high:

Found 4 high or higher advisories in production dependencies:
- HIGH protobufjs · id=1118641 · GHSA-66ff-xgx4-vchm · range=<=7.5.5
- HIGH protobufjs · id=1118645 · GHSA-75px-5xx7-5xc7 · range=<=7.5.5
- HIGH protobufjs · id=1118647 · GHSA-jvwf-75h9-cwgg · range=<=7.5.5
- HIGH protobufjs · id=1118649 · GHSA-685m-2w69-288q · range=<=7.5.5

pnpm why protobufjs shows it is a transitive dep via @google/genai, @grpc/proto-loader -> @grpc/grpc-js, and @larksuiteoapi/node-sdk — none of which this PR touches. The diff for this PR is one line in docs/tools/slash-commands.md. Fix needs a maintainer-owned protobufjs bump (or pnpm.overrides), which is explicitly out of scope per CLAUDE.md ("Patching dependencies ... requires explicit approval").

Happy to rebase once main has been patched, or you can apply a proof: style override on these security gates if you'd rather merge first.

[Takhoffman]

@clawsweeper automerge

[clawsweeper]

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=bb92b6050aab85335061028404d59c762cee3125)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-05-19T17:51:49Z
Merge commit: e00cb664ad4b

What merged:

• The PR changes one bullet in docs/tools/slash-commands.md to distinguish /new from /reset and remove the misleading alias wording.
• Reproducibility: yes. Reading current main reproduces the misleading docs line at docs/tools/slash-commands.md:127, and adjacent source/tests show /new and /reset take different paths in the Control UI.

Automerge notes:

• PR branch already contained follow-up commit before automerge: docs/slash-commands: drop inaccurate Control UI/ACP cross-reference (…
• PR branch already contained follow-up commit before automerge: Merge branch 'main' into docs/fix-reset-alias-misleading

The automerge loop is complete.

Automerge progress:

• 2026-05-19 17:44:48 UTC review queued bb92b6050aab (queued)

• 2026-05-19 17:51:32 UTC review passed bb92b6050aab (structured ClawSweeper verdict: pass (sha=bb92b6050aab85335061028404d59c762cee3...)

• 2026-05-19 17:36:02 UTC repair queued bb92b6050aab (autonomous) Run: https://github.com/openclaw/clawsweeper/actions/runs/26114305256

• 2026-05-19 17:51:52 UTC merged bb92b6050aab (merged by ClawSweeper automerge)