Enhance Nova CLI commands and improve deployment help links

.github/agents/architect.agent.md

@@ -37,6 +37,7 @@ Design or reshape changes that cross public commands, private helper boundaries,
 ## Skills to use
 
 - `/powershell-module-development`
+- `/terminal-ux-design`
 - `/release-and-changelog`
 - `/markdown-authoring`
 - `/building-maintainable-code`

.github/agents/docs-site.agent.md

@@ -14,6 +14,7 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
 - Update `docs/*.html` when end-user workflows, examples, or website wording change.
 - Preserve the separation between CLI-oriented website docs and PowerShell cmdlet help.
 - Check whether source, tests, help docs, and website docs still agree after a change.
+- Keep command-surface-toggle pages honest by splitting CLI-only and PowerShell-only wording into the matching `data-command-visibility` blocks instead of mixing both spellings in shared prose.
 
 ## Inputs to inspect
 
@@ -37,15 +38,18 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
 - Treat `docs/*.html` as end-user website docs, not cmdlet help.
 - Keep CLI and cmdlet surfaces clearly separated.
 - Mention PowerShell-only commands in CLI-oriented docs only when there is no CLI equivalent for that scenario, such as installing NovaModuleTools with `Install-Module`.
+- On pages with the surface toggle, only show `--option` spellings in command-line-visible blocks and only show `-Parameter` spellings in PowerShell-visible blocks unless the wording is fully surface-neutral.
 
 ## Definition of done
 
 - The changed website docs reflect the current behavior.
 - CLI-oriented docs do not drift into cmdlet-help wording.
+- Surface-specific labels, flags, and parameter names match the active website command surface.
 - Relevant contributor docs and changelog were reviewed for follow-up impact.
 
 ## Must not do
 
 - Must not mix cmdlet syntax into CLI docs when a CLI variant exists.
+- Must not leave shared always-visible HTML copy with both CLI flags and PowerShell parameters when the page already has the command-surface toggle.
 - Must not use `docs/*.html` as a duplicate of `docs/NovaModuleTools/en-US/*.md`.
 - Must not leave installation/documentation exceptions implicit; state them clearly.

.github/agents/powershell-developer.agent.md

@@ -32,6 +32,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 ## Skills to use
 
 - `/powershell-module-development`
+- `/terminal-ux-design`
 - `/pester-testing`
 - `/building-maintainable-code`
 - `/codescene-quality`

.github/agents/reviewer.agent.md

@@ -41,6 +41,7 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 
 ## Skills to use
 
+- `/terminal-ux-design`
 - `/codescene-quality`
 - `/safeguarding-ai-generated-code`
 - `/building-maintainable-code`

.github/copilot-instructions.md

@@ -37,15 +37,15 @@ For new or not-yet-scoped work, use the `architect` agent with `.github/prompts/
 
 The table below shows how to route work. Prompts are the task entry points; each prompt delegates to its agent, which uses the listed skills, which in turn enforce the listed instructions.
 
-| Task                          | Prompt                                     | Agent                  | Primary skills                                                                       | Primary instructions                                                              |
-| ----------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
-| Design or scope a change      | `design-change.prompt.md`                  | `architect`            | `powershell-module-development`, `github-actions`, `release-and-changelog`, `markdown-authoring` | `repository-conventions`, `code-quality-matrix`                                   |
-| Implement an issue            | `implement-issue.prompt.md`                | `powershell-developer` | `powershell-module-development`, `pester-testing`, `building-maintainable-code`, `codescene-quality`, `safeguarding-ai-generated-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` |
-| Review a change               | `review-change.prompt.md`                  | `reviewer`             | `codescene-quality`, `safeguarding-ai-generated-code`, `building-maintainable-code`, `docs-site`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `github-actions` | All `.github/instructions/*.instructions.md`                                       |
-| Improve test coverage         | `improve-test-coverage.prompt.md`          | `test-engineer`        | `pester-testing`, `building-maintainable-code`, `codescene-quality`, `github-actions`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code` | `testing-policy`, `psscriptanalyzer`                                              |
-| Prepare a release             | `prepare-release.prompt.md`                | `release-manager`      | `release-and-changelog`, `markdown-authoring`                                        | `release-policy`, `repository-conventions`                                         |
-| Fix a CI failure              | `fix-ci-failure.prompt.md`                 | `powershell-developer` (or `test-engineer`) | `github-actions`, `pester-testing`                                                   | `testing-policy`, `psscriptanalyzer`, `repository-conventions`                     |
-| Update website docs           | (no dedicated prompt — invoke agent)        | `docs-site`            | `docs-site`, `markdown-authoring`                                                    | `documentation-separation`                                                         |
+| Task                     | Prompt                               | Agent                                       | Primary skills                                                                                                                                                                                            | Primary instructions                                                                                               |
+|--------------------------|--------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| Design or scope a change | `design-change.prompt.md`            | `architect`                                 | `powershell-module-development`, `terminal-ux-design`, `github-actions`, `release-and-changelog`, `markdown-authoring`                                                                                    | `repository-conventions`, `code-quality-matrix`                                                                    |
+| Implement an issue       | `implement-issue.prompt.md`          | `powershell-developer`                      | `powershell-module-development`, `terminal-ux-design`, `pester-testing`, `building-maintainable-code`, `codescene-quality`, `safeguarding-ai-generated-code`                                              | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` |
+| Review a change          | `review-change.prompt.md`            | `reviewer`                                  | `terminal-ux-design`, `codescene-quality`, `safeguarding-ai-generated-code`, `building-maintainable-code`, `docs-site`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `github-actions` | All `.github/instructions/*.instructions.md`                                                                       |
+| Improve test coverage    | `improve-test-coverage.prompt.md`    | `test-engineer`                             | `pester-testing`, `building-maintainable-code`, `codescene-quality`, `github-actions`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code`                                           | `testing-policy`, `psscriptanalyzer`                                                                               |
+| Prepare a release        | `prepare-release.prompt.md`          | `release-manager`                           | `release-and-changelog`, `markdown-authoring`                                                                                                                                                             | `release-policy`, `repository-conventions`                                                                         |
+| Fix a CI failure         | `fix-ci-failure.prompt.md`           | `powershell-developer` (or `test-engineer`) | `github-actions`, `pester-testing`                                                                                                                                                                        | `testing-policy`, `psscriptanalyzer`, `repository-conventions`                                                     |
+| Update website docs      | (no dedicated prompt — invoke agent) | `docs-site`                                 | `docs-site`, `markdown-authoring`                                                                                                                                                                         | `documentation-separation`                                                                                         |
 
 ## Notation
 
@@ -61,5 +61,6 @@ The table below shows how to route work. Prompts are the task entry points; each
 - PSScriptAnalyzer workflow: `.github/instructions/psscriptanalyzer.instructions.md`
 - PowerShell coding standards: `.github/instructions/powershell-coding-standards.instructions.md`
 - PlatyPS help generation: `.github/instructions/platyps-help.instructions.md`
+- Terminal UX: `.github/instructions/terminal-ux-design.instructions.md` + `terminal-ux-design` skill
 - Release flow: `.github/instructions/release-policy.instructions.md` + `release-and-changelog` skill
 - Documentation separation: `.github/instructions/documentation-separation.instructions.md` + `docs-site` skill

.github/instructions/documentation-separation.instructions.md

@@ -20,6 +20,10 @@ NovaModuleTools has multiple documentation surfaces with different audiences. Ke
 - Do not write cmdlet help markdown as if it were `nova` CLI documentation.
 - Use CLI syntax in CLI-oriented website docs when a CLI variant exists.
 - Use cmdlet syntax in help markdown and PowerShell-specific contributor guidance.
+- On website pages that support the command-surface toggle, keep surface-specific wording behind the matching visibility gate.
+    - CLI-only flags, labels, and guidance belong in elements marked with `data-command-visibility="command-line"`.
+    - PowerShell-only parameters, labels, and guidance belong in elements marked with `data-command-visibility="powershell"`.
+    - Shared prose should stay surface-neutral instead of mixing `--option` and `-Parameter` spellings in the same always-visible paragraph.
 
 ## Allowed exception
 
@@ -33,6 +37,7 @@ NovaModuleTools has multiple documentation surfaces with different audiences. Ke
 - Does this page describe a `nova` workflow or a PowerShell cmdlet workflow?
 - If a `nova` command exists, is the website doc using it instead of the cmdlet?
 - If a cmdlet is shown in website docs, is it there because no CLI variant exists?
+- If the page uses the command-surface toggle, do the visible labels, flags, and parameter names match the selected surface?
 - Would an end user mistake this page for cmdlet help?
 
 ## Follow-up expectations

.github/instructions/platyps-help.instructions.md

@@ -66,6 +66,9 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 - The `external help file` field must always use the module name, not the command name: `NovaModuleTools-Help.xml`. The `Module Name` field must match the project name. When both fields use the module name, Nova build produces a single `<ModuleName>-Help.xml` under `dist/<ModuleName>/en-US/`. If either field contains a command name instead, the build produces per-command XML files and the module manifest cannot find its help.
 - Keep the H1 title equal to the exact command name.
 - Preserve the standard PlatyPS section order with uppercase H2 headers: `SYNOPSIS`, `SYNTAX`, optional `ALIASES`, `DESCRIPTION`, `EXAMPLES`, `PARAMETERS`, `INPUTS`, `OUTPUTS`, `NOTES`, and `RELATED LINKS`.
+- In `## RELATED LINKS`, use only a bulleted list of Markdown links. Do not use bare URLs or backticked command names as list items.
+- Prefer relative links to sibling command-help files when the related topic has a matching file in `docs/NovaModuleTools/en-US/`, for example `[Invoke-NovaBuild](./Invoke-NovaBuild.md)`.
+- Do not use GitHub blob URLs in shipped command help. If a relative command-help link is not suitable after PlatyPS validation, use the related topic's `novamoduletools.com` `HelpUri` instead.
 - Keep at least one example under `## EXAMPLES`.
 - Keep parameter sections as `### -ParameterName` blocks with the PlatyPS-generated YAML metadata code block.
 - Only hand-edit parameter metadata when PlatyPS cannot infer it correctly, especially `DefaultValue` and `SupportsWildcards`.
@@ -82,6 +85,7 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 - Use `Update-MarkdownCommandHelp` after command or parameter changes so syntax, aliases, and parameter metadata stay synchronized with the implementation.
 - Use `Test-MarkdownCommandHelp` as the quick structural gate before handoff; use `Import-MarkdownCommandHelp` diagnostics when you need more detail.
 - Use existing valid files under `docs/NovaModuleTools/en-US/` as the structural template before inventing a new layout.
+- Validate any new `RELATED LINKS` target style through the real PlatyPS import/export path before applying it repo-wide.
 - Keep command help separate from contributor docs and project/site docs.
 
 ## Review expectations
@@ -90,4 +94,5 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 - Reviewers should flag help files where `external help file` contains a command name (e.g., `Get-Something-Help.xml`) instead of the module name (`NovaModuleTools-Help.xml`). This produces per-command XML files that the module manifest cannot locate at runtime.
 - Reviewers should flag help files that would fail `Test-MarkdownCommandHelp` or produce diagnostics/errors when imported with `Import-MarkdownCommandHelp`.
 - Reviewers should flag any new public entry point that does not add its matching command-help file in the same change.
+- Reviewers should flag `RELATED LINKS` entries that use GitHub blob URLs, plain URLs, or bare/backticked command names instead of Markdown links.
 - Treat build errors from `Import-MarkdownCommandHelp` as a sign that the file is not valid PlatyPS help yet.

.github/instructions/terminal-ux-design.instructions.md

@@ -0,0 +1,21 @@
+---
+applyTo: "**"
+---
+
+# Terminal UX design
+
+Use the `terminal-ux-design` skill when a change touches any user-facing command, terminal output, prompt, help surface, progress indicator, warning, error message, or scaffold guidance for those surfaces.
+
+This applies to:
+
+- PowerShell cmdlets
+- `% nova` CLI routes
+- private helpers that shape user-visible terminal behavior
+- contributor docs, command help, and scaffold content that teach those workflows
+
+Keep PowerShell cmdlet UX and `% nova` CLI UX distinct, but hold both to the same terminal UX bar.
+
+The skill is authoritative for:
+
+- Atlassian's 10 design principles for delightful CLIs
+- Jakob Nielsen's 10 usability heuristics for user interface design

.github/pull_request_template.md

@@ -20,6 +20,7 @@
 - [ ] Dependency or manifest changes (`project.json`, workflow dependencies, release tooling)
 - [ ] Security-sensitive change
 - [ ] Documentation-only change
+- [ ] Agentic Copilot Workflow + scaffold mirror + scaffold-sync guardrail test.
 - [ ] Other
 
 ## Review guidance

.github/skills/docs-site/SKILL.md

@@ -24,17 +24,20 @@ Use this skill when changing `docs/*.html`, end-user examples, installation guid
 - Use CLI-oriented examples when the workflow has a `nova` variant.
 - Mention PowerShell cmdlets only when no CLI equivalent exists for that scenario.
 - Keep installation guidance explicit about PowerShell-only steps such as `Install-Module`.
+- On pages with the command-surface toggle, keep option/parameter wording aligned with the active surface by using `data-command-visibility="command-line"` and `data-command-visibility="powershell"` blocks instead of one shared paragraph that mixes CLI flags with PowerShell parameters.
 - Recheck the matching command-help markdown when public behavior changes.
 
 ## Common pitfalls
 
 - Mixing `Get-/Set-/Invoke-/Install-` cmdlets into CLI docs where `nova` exists
+- Leaving `--option` text visible in PowerShell mode, or `-Parameter` text visible in command-line mode, because the surrounding prose was not split by `data-command-visibility`
 - Duplicating cmdlet help text in website docs instead of adapting it for end users
 - Forgetting that `docs/NovaModuleTools/en-US/*.md` and `docs/*.html` serve different audiences
 - Updating website docs without reviewing changelog or contributor-doc impact
 
 ## Verification
 
 - Read the touched HTML page as an end-user flow
+- Toggle the page mentally between PowerShell and command-line surfaces and confirm the visible option/parameter names still match that surface
 - Check whether the same behavior is documented consistently in help markdown or contributor docs
 - Use docs-only validation when no executable behavior changed