# Contribute, build, and publish

Edit declarative source entries and keep downloads, indexes, and pages consistent.

## Edit the correct source file

Each entry has one JSON file in data/entries/. Choose bot-role or task-workflow and describe mission, inputs, outputs, steps, prerequisites, sources, and license. Exclude scripts, credentials, conversations, and private memory.

| Source field | Meaning | Check |
| --- | --- | --- |
| id / version | Stable identity and template version | Preserve published version bytes |
| collection | bot-role or task-workflow | Classify by responsibility or output |
| inputs / outputs / workflow | Materials, outputs, and steps | Can a checkable first task be written? |
| requirements / references / license | Prerequisites, sources, and license | Avoid unsupported capabilities or official status |

## The CLI plans or exports

scripts/market.mjs supports help, list, info, plan, and install. install generates a file and requires --out and a target host version; it does not install into a running App. Users explicitly choose whether to accept community content and an unpinned trust source.

```sh
npm run market -- help
npm run market -- list --query=research
npm run market -- info awesome/grok-researchy
# Replace 0.9.9 with the actual target host version.
npm run market -- plan awesome/grok-researchy --openbot=0.9.9 --allow-community --allow-unpinned
npm run market -- install awesome/grok-researchy --openbot=0.9.9 --allow-community --allow-unpinned --out=./researchy.fleet.json
```

The standalone CLI exposes no upgrade or rollback patches. Fleet imports can rename IDs; host reconciliation of actual Bot IDs must precede upgrades that preserve user edits.

## Check generated bilingual output

1. Use Node.js 22+, read the contribution guide, then edit a declarative entry.
2. Maintain complete English content; Chinese fallback is not a translation.
3. Generate and check, then inspect generated diffs and individual downloads.
4. Stage only intended public files before the public-content audit.

```sh
npm ci --ignore-scripts
npm run build
npm run check
npm run check:versions
npm test
npm run build:site
npm run audit:public
```

## Publish immutable versions

Published template versions and release assets are immutable. Correct instructions in a new version while retaining licenses and historical digests. CI checks the catalogue, exports, and site. The Pages workflow builds the static site, and version tags must match package.json. A workflow file does not prove deployment; check deployment results and pages afterward.

```sh
npm run pack:release
# From the release download directory on macOS:
shasum -a 256 -c SHA256SUMS
```

- [Contribution guide](https://github.com/Harzva/awesome-bot/blob/main/CONTRIBUTING.md)
- [Publishing details](https://github.com/Harzva/awesome-bot/blob/main/docs/publishing.md)

## Understand CLI output and failures

--json selects the command result format; trust checks can still write warnings to stdout. Invoking npm run market may add npm script banners. Do not JSON.parse the entire stdout or assume a dedicated flag removes all diagnostic output. For file export, use --out=\<file\>, then read and parse that file after command success. Keep the exit code and diagnostic output.

install generates a Fleet configuration file; it does not write a Bot into the running App. This wrapper requires an explicit target --openbot and does not detect the running host version. npm run market -- help shows usage and a 0.9.9 example, not the current host or default planning version. Before retrying, verify the actual version using the target host’s own version information. If it is unknown, stop compatibility planning rather than guess 0.9.9 or a default. Acceptance of community content and an unpinned source is an explicit user choice; repairing a parameter error must not silently add acceptance flags.

| Failure or symptom | Meaning and recovery |
| --- | --- |
| plan / install missing --openbot | The error starts with Provide --openbot=\<target-version\>. This wrapper requires the actual target version and does not detect the running host. Check the target host’s own version information, then retry with --openbot=\<target-version\>. If unknown, stop compatibility planning; do not copy the help example or guess a default. |
| install missing --out | The error is Provide --out=\<file\>; this command generates a configuration file and does not install into your App. Choose a writable new destination file, add --out=\<file\>, and retain the correct --openbot. If both are missing, the --out error comes first. |
| --out= or --out without a path | The error is --out requires a file path. Supply a nonempty file path; a bare flag does not select a destination automatically. |
| Warnings or banners precede JSON on stdout | Mixed output does not imply a corrupted Fleet file. Check the exit code and read warnings. Read exported data from the --out file; inspect wrapper help with npm run market -- help. |

## Sources

Sources checked: 2026-10-25

- [Contribution guide](https://github.com/Harzva/awesome-bot/blob/main/CONTRIBUTING.md)
- [Actual CLI wrapper](https://github.com/Harzva/awesome-bot/blob/main/scripts/market.mjs)
- [CI and publishing rules](https://github.com/Harzva/awesome-bot/blob/main/docs/publishing.md)
- [Complete entry example](https://github.com/Harzva/awesome-bot/blob/main/data/entries/status-report-writer.json)