# Distribution & Publishing

Minions is distributed as an npm package (`@yemi33/minions`) from a sanitized package boundary. The source lives across two GitHub remotes, with a strict one-way port direction (see [Two-Remote Topology](#two-remote-topology)).

## Two-Remote Topology

| Remote (local name on `D:/squad`) | URL | Role |
|-----------------------------------|-----|------|
| `origin` | `https://github.com/yemi33/minions` | **Authoring source of truth.** All normal code changes (engine, dashboard, playbooks, agents, etc.) land here first. Triggers npm publish + downstream mirror. |
| `opg` | `https://github.com/opg-microsoft/minions` | **Enterprise/compliance flavor.** Carries opg-only commits (compliance files, enterprise workflows). Sync from yemi33 is a manual cherry-pick PR onto `opg/main`; opg → yemi33 backports are handled by `backport-to-yemi33.yml` running on opg. |

### Port direction

**Strictly one-way: `yemi33` → `opg`.**

- **Do NOT port from `opg` back into `yemi33`.** Its `main` branch may carry org-specific compliance content (`.github/policies/*`, `.github/acl/*`, `.github/compliance/*`, JIT access policy, internal access lists, MS-org issue templates) that has no business in the personal-fork authoring source.
- **Direct pushes to `opg-microsoft/minions` are allowed for enterprise/compliance-specific changes only.** Examples: editing `.github/policies/jit.yml`, updating `.github/acl/access.yml`, modifying `.github/compliance/inventory.yml`. These changes stay on `opg` and are not backported.
- Other teams (Microsoft infra, compliance review) may also push to `opg-microsoft/minions` directly. Treat its `main` as potentially ahead of `yemi33` on policy files.

### Why opg uses a manual sync-PR pattern

The two repos are peers. To bring yemi33 changes onto `opg/main`, a maintainer opens a manual sync PR (cherry-picking the commits needed; example: PR #96). To bring opg changes onto `yemi33/master`, the opg-side `backport-to-yemi33.yml` workflow files PRs against `yemi33/master`. Neither direction is automatic — drift between the two repos is expected and reconciled on demand.

### Required secrets on `yemi33/minions`

| Secret | Purpose | Workflow |
|--------|---------|----------|
| `NPM_TOKEN` | npm publish | `publish.yml` |
| `EMU_PACKAGES_TOKEN` | Publish to `@yemishin_microsoft` internal registry | `publish-internal-github-packages.yml` |

Each downstream publish workflow gracefully skips with a warning if its token secret is unset, so unconfigured downstreams never block the primary publish path.

## Distribution Boundary

| Surface | Purpose | What's included |
|------|---------|----------------|
| **source repository** | Private development and automation | Working code, project history, and release workflows |
| **npm package** (`@yemi33/minions`) | Public installation for users | Engine, dashboard, playbooks, charters, skills, docs, and package files |

## What Gets Stripped

These files are excluded from published packages:

| Category | Pattern | Reason |
|----------|---------|--------|
| Agent history | `agents/*/history.md` | Session-specific task logs |
| Notes archive | `notes/archive/*` | Historical agent findings |
| Notes inbox | `notes/inbox/*` | Pending agent findings |
| Notes summary | `notes.md` | Consolidated knowledge (runtime) |
| Work items | `work-items.json` | Runtime dispatch tracking |
| Project instructions | `CLAUDE.md` | Org-specific context |

## npm Package

**Package:** `@yemi33/minions`
**Registry:** https://www.npmjs.com/package/@yemi33/minions

### What's in the package

Controlled by the `files` field in `package.json`:
- `bin/minions.js` — CLI entry point
- `engine.js`, `dashboard.js`, `dashboard/` (fragments), `minions.js` — core scripts
- `engine/spawn-agent.js`, `engine/ado-mcp-wrapper.js` — engine helpers
- `agents/*/charter.md` — agent role definitions
- `playbooks/*.md` — task templates
- `config.template.json` — starter config
- `routing.md`, `team.md` — editable team config
- `skills/`, `docs/` — documentation and workflows

### How `minions init` works

1. Copies all package files from `node_modules/@yemi33/minions/` to `~/.minions/`
2. Creates `config.json` from `config.template.json` if it doesn't exist
3. Creates runtime directories (`engine/`, `notes/inbox/`, `notes/archive/`, etc.)
4. Runs `minions.js init` to populate config with default agents
5. On `--force`, overwrites `.js` and `.html` files but preserves user-modified `.md` files

### How updates work

- Users run `npm install -g @yemi33/minions@latest` then `minions init --force` to update engine code (avoids the `npm update -g` Windows footgun where the bin shim gets removed mid-update)
- `npx @yemi33/minions` always fetches the latest version

## Auto-Publishing

A GitHub Action on the personal repo auto-publishes to npm on every push to master.

### How it works

1. Push to `yemi33/minions` master triggers `.github/workflows/publish.yml`
2. Action queries npm for the current published version
3. Bumps patch version (e.g., `0.1.5` → `0.1.6`)
4. Publishes to npm with the new version
5. Commits the version bump back to the repo with `[skip ci]` to prevent loops

### Why version comes from npm, not the repo

The sync-to-personal workflow force-pushes, which overwrites any version bump commits from previous action runs. So the action reads the latest version from the npm registry and bumps from there.

### Setup requirements

- `NPM_TOKEN` secret on `yemi33/minions` — a granular access token with publish permissions and 2FA bypass enabled
- The workflow file (`.github/workflows/publish.yml`) is not included in the npm package

## Sync Workflow

Repository and package publishing automation should keep private repository names, tokens, runtime state, and internal-only metadata out of public docs and public package contents.

