docs: Fix commands.md numbering, missing sections, and flag inconsistencies

[Copilot]

docs/commands.md had a duplicate ### 5. heading, missing Aliases/Options sections on two commands, a misleading option entry, a markdown escape artifact, and an undocumented runtime requirement.

Changes

• Numbering: Renumber VersionCommand → 6, CompatibilityCheckCommand → 7, TokensCommand → 8, InspectorCommand → 9
• Aliases sections: Promote frontend:build and frontend:watch from prose in Implementation Details to dedicated **Aliases** blocks (consistent with CompatibilityCheckCommand / TokensCommand)
• Options section for ThemeWatchCommand: Add --theme=THEME description block, matching the pattern used by other commands
• Remove --third-party-only / -t: Option was listed but third-party-only is the default; --include-vendor is the actual toggle — the phantom flag entry is removed
• Magento_* rendering: Remove stray backslash escape (Magento\_\* → Magento_*)
• composer.lock note in VersionCommand: Add a callout that the command requires composer.lock to be present to resolve the current installed version

Original prompt

Problem

The file docs/commands.md contains several issues that need to be fixed:

1. 🔴 Duplicate numbering (two "### 5.")

Both SystemCheckCommand and VersionCommand are labeled as "### 5.". Fix the numbering so all commands are sequentially numbered:

• 5. SystemCheckCommand ✅
• 6. VersionCommand (was 5)
• 7. CompatibilityCheckCommand (was 6)
• 8. TokensCommand (was 7)
• 9. InspectorCommand (was 8)

2. 🟡 Missing Aliases sections for BuildThemeCommand and ThemeWatchCommand

Both commands have aliases mentioned only inside "Implementation Details". Add a dedicated Aliases section (like CompatibilityCheckCommand and TokensCommand have) for consistency:

• BuildThemeCommand → alias: frontend:build
• ThemeWatchCommand → alias: frontend:watch

3. 🟡 Missing Options section for ThemeWatchCommand

The --theme=THEME option is only shown in the usage line but not described in a dedicated Options section. Add one for consistency with other commands.

4. 🟡 Inconsistency with --third-party-only / -t flag in CompatibilityCheckCommand

The options section lists --third-party-only / -t as an option, but the Default Behavior section states that third-party-only scanning is the default behavior. The flag --include-vendor is the actual toggle. Clarify or remove the misleading --third-party-only option entry if it is redundant/non-existent.

5. 🟢 Magento\_\* escape rendering artifact

On line with --third-party-only description, Magento\_\* renders with a visible backslash in markdown. Change to Magento_*.

6. 🟢 Add a note about composer.lock requirement in VersionCommand

The implementation reads from composer.lock, but this file may not always be present. Add a brief note/requirement about this.

File to change

docs/commands.md

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: /review

Assistant: Here's a thorough review of docs/commands.md:

---

✅ Overall Assessment

The documentation is well-structured, thorough, and developer-friendly. Commands are consistently formatted with Purpose, File, Dependencies, Usage, and Implementation Details. A few issues worth fixing are noted below.

---

🐛 Issues Found

1. Duplicate numbering — Commands 5 & 5

Both SystemCheckCommand and VersionCommand are labeled as "### 5." The VersionCommand should be "### 6.", and all subsequent commands need to be renumbered accordingly.

Current	Should Be
5. SystemCheckCommand	5. SystemCheckCommand ✅
5. VersionCommand	6. VersionCommand
6. CompatibilityCheckCommand	7. CompatibilityCheckCommand
7. TokensCommand	8. TokensCommand
8. InspectorCommand	9. InspectorCommand

---

2. Incorrect --third-party-only / -t flag description (CompatibilityCheckCommand)

The options section (line 214) lists --third-party-only / -t, but the Default Behavior section explicitly states third-party-only is the default. This option either doesn't exist or is misleading. If it's the default, this flag may be redundant/removed — the actual differentiating flag is --include-vendor. This should be clarified or the option removed if it no longer exists.

---

3. Inconsistency: mageforge:theme:watch option name

The usage shows:

bin/magento mageforge:theme:watch [--theme=THEME]

But the implementation details say "If no theme code is provided, displays an interactive prompt" — this is fine, but the option --theme is not described in an Options section like other commands (e.g., CompatibilityCheckCommand). Consider adding a small Options block for consistency.

---

4. CleanCommand path discrepancy

The Purpose line (line 100) mentions var/view_preprocessed, pub/static, var/page_cache, var/tmp, and generated. The Implementation Details section lists these same directories but omits var/view_preprocessed/source/... from the purpose summary. Minor, but the purpose blurb could be updated to mention both view_preprocessed subdirectories, or the detail section could be considered the authoritative list.

---

5. VersionCommand reads from composer.lock — potentially fragile

Line 184 states it reads the current version from composer.lock. This is worth a documentation note since composer.lock may not always be present (e.g., in development setups where it's gitignored or in some CI environments). A brief note about this requirement would improve the docs.

---

💡 Minor Suggestions

• Line 215 — Magento\_\* renders with a visible backslash escape in markdown. It should be Magento_* (no backslash needed in a plain list item, only in table cells or when escaping is needed).
• "Command Services" section — The MagentoStandard\Builder note (lines 475–479) is detailed but indented under builder services; t...

This pull request was created from Copilot chat.

[Copilot]

Pull request overview

Updates docs/commands.md to improve the accuracy and consistency of MageForge CLI command documentation (numbering, sections, and option descriptions).

Changes:

• Renumbered command headings to remove duplicate numbering and keep a sequential list.
• Added dedicated Aliases blocks for mageforge:theme:build and mageforge:theme:watch, and added an Options block for mageforge:theme:watch.
• Updated mageforge:version documentation with a composer.lock requirement note and removed a misleading compatibility-check option entry / markdown escape artifact.