en-US/Gerber-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh">
  <command:command>
    <command:details>
      <command:name>Invoke-Gerber</command:name>
      <maml:description>
        <maml:para>Starts the interactive Gerber DevOps multitool.</maml:para>
      </maml:description>
      <command:verb>Invoke</command:verb>
      <command:noun>Gerber</command:noun>
    </command:details>
    <maml:description>
      <maml:para>`Invoke-Gerber` starts Gerber Core's interactive command palette in the current
working directory. Core provides `/exit`, `/help`, `/plugins`, `/update`,
`/secrets` and `/tools`. Plugins are separate modules, not Core dependencies.
Plugin-contributed commands appear only while active plugins contribute them.
Menus, completion, help and direct lookup share the active registry.

Type `/` to browse or plain text such as `uuid` to search executable leaf actions.
Use Up/Down to select, Tab to complete and Enter to accept the highlighted
suggestion and execute a complete command. Roots prioritize `/exit`, `/help`,
`/plugins`, `/update`; remaining roots are alphabetical. Bare submenu commands
open inline choosers. Esc returns one level; double Esc within 200 ms returns to
the root prompt without exiting.

Startup attempts a bounded, noninteractive Core-only update check through
PSModuleUpdate. An available-version notification refers to `/update list`.
Startup never installs, asks for installation consent, requests credentials or
checks plugins. Failed checks leave the session usable without claiming currency.
Importing the module alone performs no update check or Nova lifecycle operation.

`/update list` checks Core and eligible installed plugins afresh. Core is bound to
official PSGallery and CurrentUser scope, without override, automatic repository
registration or alternate-feed fallback. Plugin repositories come from the installed
manifest's `PrivateData.Gerber.Repository` object: `Name` is displayed; `Uri` is
passed to PMU. Absent metadata defaults to PSGallery; invalid explicit metadata
never falls back. Legacy `RepositoryUri` is supported; canonical metadata wins.

With plugin rows present, Up/Down and Space select available updates, then Enter
reviews them. Selected packages are temporarily downloaded for manifest inspection
without a separate inspection prompt. A required permitted Core update is visibly
added; unsatisfied requirements block the dependent plugin.
Installation confirmation defaults to Cancel. With nothing available, continue
returns without a selection or installation prompt.

Updates run sequentially through PMU, Core first when required. Dependent plugins
are blocked on Core failure; independent selections can continue. Cancellation
stops later attempts. Results distinguish installation, verification, recovery and
fresh-process activation. Activation failure does not erase successful installation.
There is no first installation, hot reload or batch rollback. Repository credentials
are operation-local, not saved in metadata or fetched from native storage.

`/update policy` saves Stable only (default) or Include prereleases for Core startup
and manual Core/plugin discovery. Select Include prereleases to receive preview
updates. Enter saves the current selection; Esc leaves it unchanged. Policy
selection performs no discovery or installation; a change clears the old startup
notification and requires a fresh `/update list` plan.

After an update requiring restart, Continue with current version is the default;
Esc also continues with a retained reminder. Exit Gerber returns to PowerShell
without unloading modules. Console hosts also offer Exit Gerber and PowerShell;
other hosts require restarting the session from the host. Restart PowerShell,
then run `gerber` to activate installed updates.

`/plugins list` and `info` are read-only and do not import unknown, declined or
disabled plugins for inspection. Unknown plugins require GUID approval before
import, with decline as the default. Decisions persist across sessions. Approval
survives routine version updates but does not authenticate a publisher.
`/plugins enable` explicitly approves and activates a selected installed inactive
plugin without another approval prompt. `/plugins disable` removes its commands
immediately while preserving approval and installation. There are no remove or
revoke commands; uninstall the PowerShell module outside Gerber to remove or revoke it.

`/plugins create` asks for a suffix behind the fixed `Gerber.` prefix,
description, unused namespace, repository and destination parent (cwd by default).
PSGallery is preselected and writes an explicit Repository object. A custom source
takes a name and safe absolute URI; unknown URIs become
`REPLACE_WITH_REPOSITORY_URI`, which must be replaced and rebuilt before remote
publishing or updates. Creation validates a staged Plugin API v1 Nova project
without overwriting existing files, then approves, associates and enables the GUID.
It does not install or load the plugin. Generated name/version are available to
read-only inventory before installation. NovaModuleTools and PSModuleUpdate are
required runtime modules; Nova lifecycle operations run on demand.

`/tools create-uuid` displays a hyphenated UUID and copies it when possible; Enter
repeats and Esc returns to tools. `/tools base-64 encode` and `decode` convert
UTF-8 text, optionally copy results and reopen after continue. Invalid input
produces a recoverable error.

`/secrets` offers list, get, test, set and remove backed by native credential
storage. Listing and testing do not retrieve values. Get copies when possible
before asking to reveal the value. Set uses non-echoing input and confirms
overwrite; remove confirms deletion. No plaintext fallback is used.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Invoke-Gerber</maml:name>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters />
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>None</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>You cannot pipe input to this cmdlet.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>None</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>Gerber renders terminal-oriented status and help rather than returning pipeline objects.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>Requires PowerShell 7.4 or later, NovaModuleTools and PSModuleUpdate.
Plugin updates additionally require a PMU release exporting
`Get-PSModuleUpdateTargetManifest`; the numeric minimum alone does not guarantee it.
Live update has been verified on macOS only.

The startup child-process wait budget is 2,000 ms, without a persistent cache.
Noninteractive update views do not prompt or install. Failed discovery remains
Unavailable; NoMatchingPackage requires PMU's structured PackageNotFound identifier.
Neither result proves Core is current or offers installation.

Core configuration uses `GerberCore.json` in the platform-resolved user directory.
`GERBER_CONFIG_PATH` overrides the absolute Core file; a legacy `config.json` filename
selects sibling `GerberCore.json`. Plugin JSON files follow the Core file's directory,
using each module name. Plugin Configuration.Read/Save is identity-bound, with
missing-file null results, strict JSON errors and atomic writes.
The optional `coreUpdates.channel` is Stable or IncludePrerelease. Missing values
default without creating configuration; explicit invalid values are errors.
Obsolete `updates.modules.Gerber` settings cannot override PSGallery.

Credential identifiers are case-insensitive `gerber:&lt;scope&gt;:&lt;name&gt;` values; plugin
credentials use the manifest GUID's namespace. Secrets belong in native storage,
not JSON or traces. Linux storage needs a desktop Secret Service session, D-Bus
and libsecret. Unavailable storage fails with guidance, not plaintext fallback.

Set `GERBER_PROMPT_TRACE=1` before launch to write JSON lines under
`.gerber/prompt-debug.log` in cwd. Ordinary prompt input can appear in traces;
review and redact before sharing.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- Example 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Start Gerber from PowerShell.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
Invoke-Gerber
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>Start the same session through its alias.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```powershell
gerber
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 3 ---------</maml:title>
        <maml:introduction>
          <maml:para>After starting Gerber, use built-in help and Core tools.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```text
/help
/tools create-uuid
/tools base-64 encode
/tools base-64 decode
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 4 ---------</maml:title>
        <maml:introduction>
          <maml:para>Inside Gerber, inspect plugins and choose the preview update channel before
checking available updates. Review the confirmation; Cancel is the default.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```text
/plugins list
/update policy
/update list
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 5 ---------</maml:title>
        <maml:introduction>
          <maml:para>Inside Gerber, list stored identifiers or check one without retrieving its value.</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>```text
/secrets list
/secrets test
```</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <maml:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Test-GerberPluginBoundary</maml:linkText>
        <maml:uri>./Test-GerberPluginBoundary.md</maml:uri>
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Gerber project</maml:linkText>
        <maml:uri>https://github.com/stiwicourage/GerberCore</maml:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Test-GerberPluginBoundary</command:name>
      <maml:description>
        <maml:para>Checks authored plugin source for identifiable private Gerber Core dependencies.</maml:para>
      </maml:description>
      <command:verb>Test</command:verb>
      <command:noun>GerberPluginBoundary</command:noun>
    </command:details>
    <maml:description>
      <maml:para>Parses source without executing it.
Returns IsValid, FileCount, PublicApi and
deterministic Diagnostics.
This development check is not a PowerShell sandbox.
It does not start Gerber or invoke Nova lifecycle operations. Importing Gerber
still requires the declared NovaModuleTools and PSModuleUpdate runtime modules.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Test-GerberPluginBoundary</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Path</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">string</command:parameterValue>
          <dev:type>
            <maml:name>System.String</maml:name>
          </dev:type>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Path</maml:name>
        <maml:description>
          <maml:para>Plugin project directory containing a src directory. Authored PowerShell under
src, scripts and root entrypoints is inspected.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
        <dev:type>
          <maml:name>System.String</maml:name>
        </dev:type>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>System.Management.Automation.PSObject</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>One result with IsValid, FileCount, PublicApi and Diagnostics. Each diagnostic
contains project-relative File, one-based Line and Column, Dependency, Reason
and actionable Resolution. Diagnostics are sorted deterministically.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>PowerShell 7.4 or later. Authored .ps1, .psm1 and .psd1 files beneath src and scripts
are parsed recursively, along with root PowerShell files. Generated dist/artifacts
and tests outside those authored roots are not scanned. Parse failures
are diagnostics; missing paths or src directories are terminating errors.

This is a development-time architecture check, not runtime isolation, permissions
or a PowerShell sandbox. It recognizes static commands and literal imports,
simple literal concatenation and unambiguous prior literal variable assignments.
It does not prove arbitrary dynamic targets safe, follow aliases or perform
interprocedural dataflow. Local/plugin-owned function declarations are respected.
Review computed dependencies manually and request missing public capabilities.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
$result = Test-GerberPluginBoundary -Path ./Gerber.Example
$result.Diagnostics | Format-Table File, Line, Dependency, Reason, Resolution -Wrap
if (-not $result.IsValid) { throw 'Fix plugin boundary diagnostics before building.' }
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Checks an uninstalled plugin without executing its source. Invalid source produces
structured diagnostics; callers decide whether to fail their build.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
(Test-GerberPluginBoundary -Path .).PublicApi
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Inspects operations derived from the installed Core's actual API v1 declarations.
This does not start Gerber, load plugins or read user configuration.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <maml:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>Invoke-Gerber</maml:linkText>
        <maml:uri>./Invoke-Gerber.md</maml:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
</helpItems>