matlab-publish-toolbox

# matlab-publish-toolbox — Release Publisher

You handle the final release step: version stamping, re-packaging with the release version baked in, and distribution. This is an irreversible action — you always confirm with the user before proceeding.

## When to Use

- After `matlab-build-toolbox` produces a verified `.mltbx`
- User says "publish this" or "release it"
- As the final step in the full pipeline

## When NOT to Use

- The toolbox has not been built yet — use `matlab-build-toolbox` first
- User wants to iterate on packaging or fix issues — use `matlab-assess-toolbox`
- User wants to update the spec or API — use `matlab-define-toolbox-api`
- User wants to do a dry-run build without publishing — use `matlab-build-toolbox`

## Key Functions

| Function | Purpose |
|----------|---------|
| `matlab.addons.toolbox.ToolboxOptions` | Load packaging configuration and set version |
| `matlab.addons.toolbox.packageToolbox` | Package the toolbox with version baked in |
| `matlab.addons.install` | Install a toolbox from `.mltbx` (for verification/distribution) |

## Inputs

- **project_root**: Path to the project (default: current directory)
- **version** (optional): Version to release (e.g., `"1.2.0"`). Must be valid semver — minimum `"1.0"`, accepts `"1.2.3"` or `"1.2.3.4"`.
- **target** (optional): Where to distribute — `"local"`, `"github"`, `"internal"`

## Workflow

### Step 0 — Confirm with User

**ALWAYS** present what you're about to do and wait for explicit confirmation:

```
I'm about to publish this toolbox:

- Toolbox: My Toolbox
- Identifier: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- Version: 1.2.0
- Output: release/1.2.0/My_Toolbox.mltbx
- Target: [where it's going]

This will:
1. Re-package the toolbox with version "1.2.0" baked in
2. Update version in all project locations (toolboxSpecification, buildfile, Contents.m)
3. [Distribute to target]

This action is not easily reversible. Proceed? [yes/no]
```

**Do NOT proceed without explicit "yes" from the user.**

### Step 1 — Validate Version

If version was not provided, ask the user. Never guess.

Validate the version string by assigning it to `ToolboxOptions.ToolboxVersion` — this accepts all formats MATLAB supports:
- Minimum: `"1.0"`
- Standard: `"1.2.3"` (MAJOR.MINOR.PATCH)
- Extended: `"1.2.3.4"` (with build number)
- Prerelease: `"1.0.0-beta"` (semver prerelease tag)

```matlab
% Validate by attempting assignment — errors if format is invalid
opts.ToolboxVersion = version;
```

Follow semantic versioning: MAJOR = breaking API changes, MINOR = new functionality (backwards-compatible), PATCH = bug fixes.

### Step 2 — Confirm Readiness

This skill does not re-check documentation, help text, or spec drift — that is `matlab-assess-toolbox`'s job. Simply confirm that readiness has passed:

1. If `buildUtilities/toolboxSpecification.m` exists, confirm `matlab-assess-toolbox` reported no blockers
2. If no pipeline context, confirm the user has verified their project is release-ready

If readiness has not been run, direct the user to `matlab-assess-toolbox` before proceeding.

### Step 3 — Update Version Everywhere (BEFORE Packaging)

**MANDATORY — do this BEFORE packaging.** The version must be consistent across all source files before the `.mltbx` is built. If `buildfile.m` reads the version from `toolboxSpecification.m` or has it hardcoded, it must already be correct when `packageToolbox` runs.

Update the version string in ALL of the following locations that exist:

| Location | What to update | How to find it |
|----------|---------------|----------------|
| `buildUtilities/toolboxSpecification.m` | `spec.toolbox.version = "X.Y.Z"` | Always present if pipeline was used |
| `buildfile.m` | `opts.ToolboxVersion = "X.Y.Z"` in the `packageTask` function (if version is hardcoded there) | Read the package task and check for a literal version string |
| `Contents.m` | Version line (format: `% Version X.Y.Z DD-Mon-YYYY`) | At project root or in `toolbox/` |
| `toolboxPackaging.prj` | Version XML element | Only if PRJ-based packaging is used |

**Search strategy:** Grep the project for the OLD version string to find any other locations that hardcode it (README badges, CITATION files, etc.). Update those too.

```bash
# Find all files containing the old version
grep -r "1.0.0" . --include="*.m" --include="*.md" --include="*.prj"
```

Do NOT skip this step. Do NOT defer it to after packaging. A released toolbox with version "1.1.0" in its `.mltbx` metadata but "1.0.0" in `buildfile.m` or `toolboxSpecification.m` will produce the wrong version on the next build.

### Step 4 — Re-package with Release Version

Version is baked into the `.mltbx` at packaging time. After updating all source files (Step 3), package:

```matlab
% Load packaging configuration
if isMATLABReleaseOlderThan("R2025a")
    opts = matlab.addons.toolbox.ToolboxOptions("toolboxPackaging.prj");
else
    opts = matlab.addons.toolbox.ToolboxOptions("<projectname>.prj");
end

% Set the release version
opts.ToolboxVersion = "1.2.0";

% Set output to release/<version>/ with underscored filename
% Including version in the path prevents overwriting previous releases
% and makes it easy to find/distribute a specific version.
releaseDir = fullfile("release", "1.2.0");
if ~isfolder(releaseDir), mkdir(releaseDir); end
opts.OutputFile = fullfile(releaseDir, "<Toolbox_Name>.mltbx");

% Set Getting Started guide (use the actual filename — .m or .mlx — found in the project)
opts.ToolboxGettingStartedGuide = fullfile("toolbox", "doc", "GettingStarted.m");

% Package with version baked in
matlab.addons.toolbox.packageToolbox(opts);
```

After packaging, verify:

```matlab
mltbxFile = opts.OutputFile;
assert(isfile(mltbxFile), "Package not created");
info = dir(mltbxFile);
assert(info.bytes > 0, "Package file is empty");
fprintf("Package: %s (%.1f KB)\n", mltbxFile, info.bytes / 1024);
fprintf("Identifier: %s\n", opts.Identifier);
```

### Step 5 — Distribute

| Target | Action |
|---