/gaia-config-distribution

user-facing
Category:
Configuration
Lifecycle phase:
4 -- Implementation
Arguments:
add | show | clear | set [--channel <c>] [--registry <url>] [--manifest <path>] [--release-workflow <name>] [--force]

What it does

/gaia-config-distribution edits the distribution section of .gaia/config/project-config.yaml. This section defines how the project is published to a registry or marketplace -- the distribution channel, registry URL, manifest path, and optional release workflow. The editor preserves all YAML comments and formatting outside the edited section.

The distribution channel must be one of the closed 10-channel registry: claude-marketplace, npm, pypi, maven, homebrew, github-releases, mobile-app, container-registry, static-site, custom.

All writes go through a diff-preview confirmation gate before anything is written. Pre-write validation enforces schema compliance, path canonicalization, shell-metacharacter rejection, and URL-shape validation.

When to use it

  • You are setting up a new project for distribution and need to add the distribution section.
  • You want to change the distribution channel, registry, manifest, or release workflow.
  • You want to view or remove the current distribution configuration.

Prerequisites

  • project-config.yaml must exist. Run /gaia-init to create one if missing.

How to invoke

/gaia-config-distribution show
/gaia-config-distribution add --channel npm --registry https://registry.npmjs.org --manifest package.json --release-workflow release.yml
/gaia-config-distribution set --channel pypi --registry https://upload.pypi.org/legacy/
/gaia-config-distribution clear

What it does step by step

  1. Locate project-config.yaml Resolves the configuration file path via the canonical resolver.
  2. Dispatch subcommand
    • add -- add a fresh distribution: block. Refuses when one already exists (use set instead). Requires four fields: --channel, --registry, --manifest, --release-workflow. Some channels require additional sub-fields.
    • show -- print the current distribution: block, or "(no distribution section)" when absent.
    • set -- update one or more fields of an existing section. Refuses when no section exists (use add instead).
    • clear -- remove the entire distribution: block.
  3. Pre-write validation For add and set: validates channel against the 10-channel enum, canonicalizes the manifest path, checks the registry URL shape, and rejects shell metacharacters in all string fields. If all environments are deployable and --force is not set, refuses the write.
  4. Diff preview and confirmation Shows a unified diff of what will change. You must confirm before anything is written.
  5. Atomic write Writes only the modified section through the comment-preserving YAML editor.
  6. Post-write verification Re-extracts the section and confirms the round-trip parses correctly.

Inputs

InputSourceDescription
Project configuration.gaia/config/project-config.yamlThe file containing the distribution section.
--channelFlagOne of the 10 closed-registry channels.
--registryFlagHTTPS registry URL.
--manifestFlagRelative path to the version manifest (e.g., package.json).
--release-workflowFlagName or relative path of the release workflow.
--forceFlag (optional)Override the all-deployable-environments gate.

Outputs

OutputLocationDescription
Updated distribution section.gaia/config/project-config.yamlThe modified distribution block (comment-preserving).

Example session

> /gaia-config-distribution show

(no distribution section)

> /gaia-config-distribution add \
    --channel claude-marketplace \
    --registry https://marketplace.claude.ai \
    --manifest plugin.json \
    --release-workflow release.yml

Diff preview:
  + distribution:
  +   channel: claude-marketplace
  +   registry: https://marketplace.claude.ai
  +   manifest: plugin.json
  +   release_workflow: release.yml

Apply this edit? [y/n]
> y

distribution section added. Run /gaia-config-validate to verify.

What to run next

Troubleshooting

distribution section already exists

The add subcommand refuses when a distribution: block already exists. Use set to update individual fields instead.

no distribution section

The set and clear subcommands refuse when no distribution: block exists. Use add to create one first.

distribution typically pairs with branch-only or distribution-only environments

All your environments resolve to kind: deployable. Set at least one environment to non-deployable first, or pass --force to override this gate.

Schema validation failed

The proposed changes did not pass schema validation. Check channel-specific required sub-fields: mobile-app requires --platform, --store-id, --review-required; container-registry requires --image-name, --tag-strategy; and so on.

Shell metacharacter rejected

String fields must not contain ;, &&, ||, |, backtick, $(, >, <, or newline. Remove these characters from the value.