--- name: night-market-operations description: "Run and ship this repo: make targets, artifacts, release runbook. Use when testing, linting, or releasing. Do not use for setup; use night-market-build-and-env." ---

# Night Market Operations

This skill is the runbook for operating the claude-night-market repo: what each make target actually executes, where artifacts land, and the exact sequence that ships a release. Every command below was verified against the Makefile, scripts/, and .github/workflows/ on 2026-07-02 (repo v1.9.15).

Terms used once and reused throughout:

- **Plugin**: a directory under `plugins/` with a `.claude-plugin/plugin.json` manifest. Most have their own Makefile, pyproject.toml, and tests/. - **skrills**: a Rust CLI for skill validation and token analysis, vendored at `plugins/abstract/bin/skrills`. Every skrills target has a Python fallback, so a missing binary never blocks you. - **ClawHub export**: a cross-framework skill package format written to `clawhub/` by `scripts/clawhub_export.py`.

All commands run from the repo root unless a `cd` is shown. `uv` is required for everything Python. For environment setup, see night-market-build-and-env.

## Command anatomy

| Command | What it actually executes | When to use | Expected output shape | |---------|---------------------------|-------------|-----------------------| | `make test` | `./scripts/run-plugin-tests.sh --all`: per plugin, runs `make test --quiet` if the plugin Makefile has a `test:` target, else `uv run python -m pytest tests/ --tb=short --quiet` if pyproject mentions pytest. Skips plugins without `tests/`. | Full sweep before a PR or release. | Per-plugin pass/fail/skip lines. Failures re-run verbose. | | `make lint` | `uv run ruff format plugins/`, then `uv run ruff check --fix plugins/`, then ruff format again, then `uv run bandit --quiet -c pyproject.toml -r plugins/`. All use root pyproject.toml config. | Before every commit. Mutates files (auto-fix). | Four staged sections ending "Lint Complete". | | `make typecheck` | `./scripts/run-plugin-typecheck.sh --all`: per-plugin `uv run mypy` under each plugin's own strict config, plus a separate `uv run mypy hooks/` pass when `hooks/*.py` exists. | After type-touching changes and before release. | Per-plugin pass/fail. Hooks checked as a sub-step. | | `make validate-all` | `python3 plugins/abstract/scripts/validate_plugin.py <plugin>` for every plugin. Failures print "(validation failed)" but do NOT stop the loop or fail the target. | Structure audit after manifest edits. | One validation block per plugin. Read output, not exit code. | | `make plugin-check` | For each plugin whose Makefile has a `plugin-check:` target: `timeout 180 make -C plugins/<p> plugin-check`. Failures and timeouts print a note, exit code stays 0. | Dogfood/demo sweep before release. | Per-plugin sections. Watch for "(plugin-check failed or timed out)". | | `make docs-sync-check` | `bash scripts/capabilities-sync-check.sh` | PR touches plugin manifests or skills (mirrors capabilities-sync.yml CI). | Drift list or clean pass. Fix drift with `/sanctum:sync-capabilities --fix`. | | `make supply-chain-scan` | `python3 scripts/supply_chain_scan.py` | After dependency or lockfile changes. | Scan report between banner lines. | | `make validate-skills` | `skrills validate --skill-dir plugins --target claude` (plugin bin, then PATH). Falls back to `uv run python scripts/check_plugin_hooks.py`. | Skill frontmatter/structure check. | skrills report, or the Python fallback notice plus its output. | | `make analyze-skills` | `skrills analyze --skill-dir plugins`. Falls back to `uv run python scripts/generate_dependency_map.py`. | Skill token-budget and dependency analysis. | Token/dependency stats. | | `make status` | `make -C <plugin> status` for every plugin. | Quick overview. | Per-plugin status or "(status unavailable)". | | `make clean` | `make -C <plugin> clean` for every plugin, errors ignored. | Reset build artifacts. | "Done." |

Two targets have soft failure modes worth repeating: `make validate-all` and `make plugin-check` keep going past failures and can exit 0 while a plugin is broken. Read their output. Do not treat a green exit as proof.

## Scoping runs: one plugin, one file

The root Makefile auto-generates delegation targets for every plugin that has a Makefile. `make <plugin>-<target>` is identical to `make -C plugins/<plugin> <target>`:

```bash make sanctum-test # run sanctum's test suite make imbue-lint # run imbue's lint target make abstract-help # list a plugin's own targets ```

Run a single test file from inside the plugin directory:

```bash cd plugins/imbue && uv run pytest tests/unit/test_deferred_capture.py -x -q ```

Rules that save you an hour:

- Never run root `pytest` expecting plugin tests to run. Root pyproject.toml sets `norecursedirs = ["plugins/*", ...]` because plugin conftest.py files collide on import paths. Plugin tests run per-plugin, always. - Some plugins force coverage on every run. imbue's pytest `addopts` include `--cov=scripts`, `--cov-report=html:htmlcov`, and `--cov-report=xml`, so even a single-file run writes `htmlcov/` and `coverage.xml` into `plugins/imbue/`. This is normal, not a mess you made. - Coverage thresholds: root coverage `fail_under = 85`. Per-plugin overrides live in each plugin's `[tool.nightmarket]` `coverage_threshold` (per-plugin values: see night-market-validation-and-qa, the designated home for the threshold inventory). `run-plugin-tests.sh` reads that value and passes `--cov-fail-under=<n>` when the plugin runs via the pytest path.

## Artifact conventions

| Artifact | Producer | Location | Committed? | |----------|----------|----------|------------| | `htmlcov/`, `coverage.xml` | pytest coverage addopts | Repo root and per-plugin dirs | Present in tree but regenerated. Never hand-edit | | `reports/skill-graph.json` | skill-graph tooling | `reports/` | No, generated locally (`reports/` is gitignored). Rebuild with the skill-graph tooling | | `clawhub/` | `make clawhub-export` | `clawhub/manifest.json` plus one `nm-<plugin>-<skill>/` dir per exported skill | No, generated locally. `make clawhub-export` rebuilds it, and the release workflow regenerates it in CI | | `bridge/openclaw/`, `bridge/a2a/` | `make bridge-build`, `make a2a-cards` | `bridge/` | Build outputs. `make bridge-clean` removes skills and a2a | | `book/build/` | `mdbook build` (book/book.toml sets `build-dir = "build"`) | `book/build/` | No, CI-built | | `trust-report.json` | CI only: trust-attestation.yml on push to master | Workflow workspace, SLSA-attested | No, never in tree |

## Release runbook

The ecosystem ships as one version. `.claude-plugin/marketplace.json` is the version source of truth, fanned out to every plugin manifest. Gates and review policy are night-market-change-control territory. This is the mechanical sequence.

1. **Preflight.** Run `Skill(sanctum:git-workspace-review)` for a read-only workspace check. Confirm you are on a `<topic>-<version>` branch. Do not release from master.

2. **Bump the version everywhere.** Dry-run first:

```bash uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 --dry-run uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 git diff --stat ```

The script rejects any version that does not match `^\d+\.\d+\.\d+$`. It then rewrites the version field in every match of these globs, and it skips cache and venv directories:

- `**/pyproject.toml` - `**/Cargo.toml` - `**/package.json` - `**/.claude-plugin/plugin.json` - `**/.claude-plugin/metadata.json` - `**/.claude-plugin/marketplace.json` - `**/openpackage.yml` - any `**/__init__.py` that contains `__version__`

Expect a large diff of roughly 100 files. That is the design.

3. **Add the CHANGELOG entry.** CHANGELOG.md follows Keep a Changelog 1.1.0 with SemVer. Keep `## [Unreleased]` at the top. Insert `## [X.Y.Z] - YYYY-MM-DD` directly below it. Do not rewrite or de-slop historical entries.

4. **Sync the docs.** Update the per-plugin version column in `docs/api-overview.md`. Then run:

```bash make docs-sync-check ```

The check compares plugin.json registrations against the generated capabilities reference in `book/src/reference/`. If it reports drift, run `/sanctum:sync-capabilities --fix`.

5. **Open the PR and clear the gates.** Follow night-market-change-control. The gates are the pre-commit hooks, the slop check on docs, capabilities-sync, typecheck, and the security workflows.

6. **Merge to master.**

`trust-attestation.yml` fires on the push. It runs `make test`. It writes `trust-report.json`. It attaches a SLSA provenance attestation with `actions/attest-build-provenance@v4`.

7. **Tag the release.** Run `/sanctum:create-tag v1.9.16`. The command pushes a v-prefixed annotated tag. It then confirms that the release pipeline started.

8. **Let the release pipeline run.**

`cross-framework-publish.yml` fires on `v*` tags. It strips the `v` and validates the version against `^[0-9]+\.[0-9]+\.[0-9]+`. It runs the cross-framework unit tests: clawhub_export, build_bridge, a2a_cards, and framework_detect. It runs `make cross-framework`. It packages four tarballs:

- `night-market-clawhub` - `night-market-openclaw-bridge` - `night-market-a2a-cards` - `night-market-cross-framework`

It then creates the GitHub release.

One precondition applies. The publish job fails when `clawhub/manifest.json` does not exist. It also fails when `total_exported` is 0. The current count is 188.

ClawHub submission after the release stays manual. Run `./scripts/clawhub-submit.sh v<version>`.

Release checklist:

- [ ] `make test`, `make lint`, `make typecheck` all pass locally - [ ] `update_versions.py` diff reviewed and marketplace.json shows the new version - [ ] CHANGELOG has the new section, `[Unreleased]` still on top - [ ] `make docs-sync-check` clean - [ ] Tag pushed, both workflows green, release has 4 tarball assets

## Book publishing

The mdBook under `book/` deploys via deploy-book.yml:

- Triggers: push to master or main touching `book/**` or the workflow file itself, plus PRs on the same paths (build-only) and manual dispatch. - Build: `peaceiris/actions-mdbook@v2` with `mdbook-version: 'latest'`, then `mdbook build` with working-directory `book`. Output `book/build` uploads via `actions/upload-pages-artifact@v5` and deploys with `actions/deploy-pages@v5`, with one retry step if the first deploy fails. - Known fragility: mdbook is unpinned ("latest"), so a new upstream mdbook release can break the build with no change in this repo. If the book job fails right after an mdbook release, suspect that first.

Local preview, if mdbook is installed:

```bash cd book && mdbook build # output in book/build/ ```

## Cross-framework export surface

```bash make clawhub-export # export all skills to clawhub/, then validate make clawhub-export-top # top 20 most marketable skills only make clawhub-validate # re-validate an existing export make clawhub-stats # export statistics, no writes make bridge-build # (depends on clawhub-export) build bridge/openclaw/ make a2a-cards # generate A2A agent cards into bridge/a2a/ make a2a-list # list agents eligible for card generation make detect-framework # detect the active agentic framework make cross-framework # all of the above: export + bridge + cards ```

`make cross-framework` is exactly what the release pipeline runs, so running it locally before tagging catches export failures early. It prints skill and agent counts and ends with framework detection.

## When NOT to use

| You want | Use instead | |----------|-------------| | Set up uv, Python, tools from scratch | night-market-build-and-env

--- name: night-market-operations description: "Run and ship this repo: make targets, artifacts, release runbook. Use when testing, linting, or releasing. Do not use for setup; use night-market-build-and-env." ---

# Night Market Operations

This skill is the runbook for operating the claude-night-market repo: what each make target actually executes, where artifacts land, and the exact sequence that ships a release. Every command below was verified against the Makefile, scripts/, and .github/workflows/ on 2026-07-02 (repo v1.9.15).

Terms used once and reused throughout:

- **Plugin**: a directory under `plugins/` with a `.claude-plugin/plugin.json` manifest. Most have their own Makefile, pyproject.toml, and tests/. - **skrills**: a Rust CLI for skill validation and token analysis, vendored at `plugins/abstract/bin/skrills`. Every skrills target has a Python fallback, so a missing binary never blocks you. - **ClawHub export**: a cross-framework skill package format written to `clawhub/` by `scripts/clawhub_export.py`.

All commands run from the repo root unless a `cd` is shown. `uv` is required for everything Python. For environment setup, see night-market-build-and-env.

## Command anatomy

| Command | What it actually executes | When to use | Expected output shape | |---------|---------------------------|-------------|-----------------------| | `make test` | `./scripts/run-plugin-tests.sh --all`: per plugin, runs `make test --quiet` if the plugin Makefile has a `test:` target, else `uv run python -m pytest tests/ --tb=short --quiet` if pyproject mentions pytest. Skips plugins without `tests/`. | Full sweep before a PR or release. | Per-plugin pass/fail/skip lines. Failures re-run verbose. | | `make lint` | `uv run ruff format plugins/`, then `uv run ruff check --fix plugins/`, then ruff format again, then `uv run bandit --quiet -c pyproject.toml -r plugins/`. All use root pyproject.toml config. | Before every commit. Mutates files (auto-fix). | Four staged sections ending "Lint Complete". | | `make typecheck` | `./scripts/run-plugin-typecheck.sh --all`: per-plugin `uv run mypy` under each plugin's own strict config, plus a separate `uv run mypy hooks/` pass when `hooks/*.py` exists. | After type-touching changes and before release. | Per-plugin pass/fail. Hooks checked as a sub-step. | | `make validate-all` | `python3 plugins/abstract/scripts/validate_plugin.py <plugin>` for every plugin. Failures print "(validation failed)" but do NOT stop the loop or fail the target. | Structure audit after manifest edits. | One validation block per plugin. Read output, not exit code. | | `make plugin-check` | For each plugin whose Makefile has a `plugin-check:` target: `timeout 180 make -C plugins/<p> plugin-check`. Failures and timeouts print a note, exit code stays 0. | Dogfood/demo sweep before release. | Per-plugin sections. Watch for "(plugin-check failed or timed out)". | | `make docs-sync-check` | `bash scripts/capabilities-sync-check.sh` | PR touches plugin manifests or skills (mirrors capabilities-sync.yml CI). | Drift list or clean pass. Fix drift with `/sanctum:sync-capabilities --fix`. | | `make supply-chain-scan` | `python3 scripts/supply_chain_scan.py` | After dependency or lockfile changes. | Scan report between banner lines. | | `make validate-skills` | `skrills validate --skill-dir plugins --target claude` (plugin bin, then PATH). Falls back to `uv run python scripts/check_plugin_hooks.py`. | Skill frontmatter/structure check. | skrills report, or the Python fallback notice plus its output. | | `make analyze-skills` | `skrills analyze --skill-dir plugins`. Falls back to `uv run python scripts/generate_dependency_map.py`. | Skill token-budget and dependency analysis. | Token/dependency stats. | | `make status` | `make -C <plugin> status` for every plugin. | Quick overview. | Per-plugin status or "(status unavailable)". | | `make clean` | `make -C <plugin> clean` for every plugin, errors ignored. | Reset build artifacts. | "Done." |

Two targets have soft failure modes worth repeating: `make validate-all` and `make plugin-check` keep going past failures and can exit 0 while a plugin is broken. Read their output. Do not treat a green exit as proof.

## Scoping runs: one plugin, one file

The root Makefile auto-generates delegation targets for every plugin that has a Makefile. `make <plugin>-<target>` is identical to `make -C plugins/<plugin> <target>`:

```bash make sanctum-test # run sanctum's test suite make imbue-lint # run imbue's lint target make abstract-help # list a plugin's own targets ```

Run a single test file from inside the plugin directory:

```bash cd plugins/imbue && uv run pytest tests/unit/test_deferred_capture.py -x -q ```

Rules that save you an hour:

- Never run root `pytest` expecting plugin tests to run. Root pyproject.toml sets `norecursedirs = ["plugins/*", ...]` because plugin conftest.py files collide on import paths. Plugin tests run per-plugin, always. - Some plugins force coverage on every run. imbue's pytest `addopts` include `--cov=scripts`, `--cov-report=html:htmlcov`, and `--cov-report=xml`, so even a single-file run writes `htmlcov/` and `coverage.xml` into `plugins/imbue/`. This is normal, not a mess you made. - Coverage thresholds: root coverage `fail_under = 85`. Per-plugin overrides live in each plugin's `[tool.nightmarket]` `coverage_threshold` (per-plugin values: see night-market-validation-and-qa, the designated home for the threshold inventory). `run-plugin-tests.sh` reads that value and passes `--cov-fail-under=<n>` when the plugin runs via the pytest path.

## Artifact conventions

| Artifact | Producer | Location | Committed? | |----------|----------|----------|------------| | `htmlcov/`, `coverage.xml` | pytest coverage addopts | Repo root and per-plugin dirs | Present in tree but regenerated. Never hand-edit | | `reports/skill-graph.json` | skill-graph tooling | `reports/` | No, generated locally (`reports/` is gitignored). Rebuild with the skill-graph tooling | | `clawhub/` | `make clawhub-export` | `clawhub/manifest.json` plus one `nm-<plugin>-<skill>/` dir per exported skill | No, generated locally. `make clawhub-export` rebuilds it, and the release workflow regenerates it in CI | | `bridge/openclaw/`, `bridge/a2a/` | `make bridge-build`, `make a2a-cards` | `bridge/` | Build outputs. `make bridge-clean` removes skills and a2a | | `book/build/` | `mdbook build` (book/book.toml sets `build-dir = "build"`) | `book/build/` | No, CI-built | | `trust-report.json` | CI only: trust-attestation.yml on push to master | Workflow workspace, SLSA-attested | No, never in tree |

## Release runbook

The ecosystem ships as one version. `.claude-plugin/marketplace.json` is the version source of truth, fanned out to every plugin manifest. Gates and review policy are night-market-change-control territory. This is the mechanical sequence.

1. **Preflight.** Run `Skill(sanctum:git-workspace-review)` for a read-only workspace check. Confirm you are on a `<topic>-<version>` branch. Do not release from master.

2. **Bump the version everywhere.** Dry-run first:

```bash uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 --dry-run uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 git diff --stat ```

The script rejects any version that does not match `^\d+\.\d+\.\d+$`. It then rewrites the version field in every match of these globs, and it skips cache and venv directories:

- `**/pyproject.toml` - `**/Cargo.toml` - `**/package.json` - `**/.claude-plugin/plugin.json` - `**/.claude-plugin/metadata.json` - `**/.claude-plugin/marketplace.json` - `**/openpackage.yml` - any `**/__init__.py` that contains `__version__`

Expect a large diff of roughly 100 files. That is the design.

3. **Add the CHANGELOG entry.** CHANGELOG.md follows Keep a Changelog 1.1.0 with SemVer. Keep `## [Unreleased]` at the top. Insert `## [X.Y.Z] - YYYY-MM-DD` directly below it. Do not rewrite or de-slop historical entries.

4. **Sync the docs.** Update the per-plugin version column in `docs/api-overview.md`. Then run:

```bash make docs-sync-check ```

The check compares plugin.json registrations against the generated capabilities reference in `book/src/reference/`. If it reports drift, run `/sanctum:sync-capabilities --fix`.

5. **Open the PR and clear the gates.** Follow night-market-change-control. The gates are the pre-commit hooks, the slop check on docs, capabilities-sync, typecheck, and the security workflows.

6. **Merge to master.**

`trust-attestation.yml` fires on the push. It runs `make test`. It writes `trust-report.json`. It attaches a SLSA provenance attestation with `actions/attest-build-provenance@v4`.

7. **Tag the release.** Run `/sanctum:create-tag v1.9.16`. The command pushes a v-prefixed annotated tag. It then confirms that the release pipeline started.

8. **Let the release pipeline run.**

`cross-framework-publish.yml` fires on `v*` tags. It strips the `v` and validates the version against `^[0-9]+\.[0-9]+\.[0-9]+`. It runs the cross-framework unit tests: clawhub_export, build_bridge, a2a_cards, and framework_detect. It runs `make cross-framework`. It packages four tarballs:

- `night-market-clawhub` - `night-market-openclaw-bridge` - `night-market-a2a-cards` - `night-market-cross-framework`

It then creates the GitHub release.

One precondition applies. The publish job fails when `clawhub/manifest.json` does not exist. It also fails when `total_exported` is 0. The current count is 188.

ClawHub submission after the release stays manual. Run `./scripts/clawhub-submit.sh v<version>`.

Release checklist:

- [ ] `make test`, `make lint`, `make typecheck` all pass locally - [ ] `update_versions.py` diff reviewed and marketplace.json shows the new version - [ ] CHANGELOG has the new section, `[Unreleased]` still on top - [ ] `make docs-sync-check` clean - [ ] Tag pushed, both workflows green, release has 4 tarball assets

## Book publishing

The mdBook under `book/` deploys via deploy-book.yml:

- Triggers: push to master or main touching `book/**` or the workflow file itself, plus PRs on the same paths (build-only) and manual dispatch. - Build: `peaceiris/actions-mdbook@v2` with `mdbook-version: 'latest'`, then `mdbook build` with working-directory `book`. Output `book/build` uploads via `actions/upload-pages-artifact@v5` and deploys with `actions/deploy-pages@v5`, with one retry step if the first deploy fails. - Known fragility: mdbook is unpinned ("latest"), so a new upstream mdbook release can break the build with no change in this repo. If the book job fails right after an mdbook release, suspect that first.

Local preview, if mdbook is installed:

```bash cd book && mdbook build # output in book/build/ ```

## Cross-framework export surface

```bash make clawhub-export # export all skills to clawhub/, then validate make clawhub-export-top # top 20 most marketable skills only make clawhub-validate # re-validate an existing export make clawhub-stats # export statistics, no writes make bridge-build # (depends on clawhub-export) build bridge/openclaw/ make a2a-cards # generate A2A agent cards into bridge/a2a/ make a2a-list # list agents eligible for card generation make detect-framework # detect the active agentic framework make cross-framework # all of the above: export + bridge + cards ```

`make cross-framework` is exactly what the release pipeline runs, so running it locally before tagging catches export failures early. It prints skill and agent counts and ends with framework detection.

## When NOT to use

| You want | Use instead | |----------|-------------| | Set up uv, Python, tools from scratch | night-market-build-and-env

--- name: night-market-operations description: "Run and ship this repo: make targets, artifacts, release runbook. Use when testing, linting, or releasing. Do not use for setup; use night-market-build-and-env." ---

# Night Market Operations

This skill is the runbook for operating the claude-night-market repo: what each make target actually executes, where artifacts land, and the exact sequence that ships a release. Every command below was verified against the Makefile, scripts/, and .github/workflows/ on 2026-07-02 (repo v1.9.15).

Terms used once and reused throughout:

- **Plugin**: a directory under `plugins/` with a `.claude-plugin/plugin.json` manifest. Most have their own Makefile, pyproject.toml, and tests/. - **skrills**: a Rust CLI for skill validation and token analysis, vendored at `plugins/abstract/bin/skrills`. Every skrills target has a Python fallback, so a missing binary never blocks you. - **ClawHub export**: a cross-framework skill package format written to `clawhub/` by `scripts/clawhub_export.py`.

All commands run from the repo root unless a `cd` is shown. `uv` is required for everything Python. For environment setup, see night-market-build-and-env.

## Command anatomy

| Command | What it actually executes | When to use | Expected output shape | |---------|---------------------------|-------------|-----------------------| | `make test` | `./scripts/run-plugin-tests.sh --all`: per plugin, runs `make test --quiet` if the plugin Makefile has a `test:` target, else `uv run python -m pytest tests/ --tb=short --quiet` if pyproject mentions pytest. Skips plugins without `tests/`. | Full sweep before a PR or release. | Per-plugin pass/fail/skip lines. Failures re-run verbose. | | `make lint` | `uv run ruff format plugins/`, then `uv run ruff check --fix plugins/`, then ruff format again, then `uv run bandit --quiet -c pyproject.toml -r plugins/`. All use root pyproject.toml config. | Before every commit. Mutates files (auto-fix). | Four staged sections ending "Lint Complete". | | `make typecheck` | `./scripts/run-plugin-typecheck.sh --all`: per-plugin `uv run mypy` under each plugin's own strict config, plus a separate `uv run mypy hooks/` pass when `hooks/*.py` exists. | After type-touching changes and before release. | Per-plugin pass/fail. Hooks checked as a sub-step. | | `make validate-all` | `python3 plugins/abstract/scripts/validate_plugin.py <plugin>` for every plugin. Failures print "(validation failed)" but do NOT stop the loop or fail the target. | Structure audit after manifest edits. | One validation block per plugin. Read output, not exit code. | | `make plugin-check` | For each plugin whose Makefile has a `plugin-check:` target: `timeout 180 make -C plugins/<p> plugin-check`. Failures and timeouts print a note, exit code stays 0. | Dogfood/demo sweep before release. | Per-plugin sections. Watch for "(plugin-check failed or timed out)". | | `make docs-sync-check` | `bash scripts/capabilities-sync-check.sh` | PR touches plugin manifests or skills (mirrors capabilities-sync.yml CI). | Drift list or clean pass. Fix drift with `/sanctum:sync-capabilities --fix`. | | `make supply-chain-scan` | `python3 scripts/supply_chain_scan.py` | After dependency or lockfile changes. | Scan report between banner lines. | | `make validate-skills` | `skrills validate --skill-dir plugins --target claude` (plugin bin, then PATH). Falls back to `uv run python scripts/check_plugin_hooks.py`. | Skill frontmatter/structure check. | skrills report, or the Python fallback notice plus its output. | | `make analyze-skills` | `skrills analyze --skill-dir plugins`. Falls back to `uv run python scripts/generate_dependency_map.py`. | Skill token-budget and dependency analysis. | Token/dependency stats. | | `make status` | `make -C <plugin> status` for every plugin. | Quick overview. | Per-plugin status or "(status unavailable)". | | `make clean` | `make -C <plugin> clean` for every plugin, errors ignored. | Reset build artifacts. | "Done." |

Two targets have soft failure modes worth repeating: `make validate-all` and `make plugin-check` keep going past failures and can exit 0 while a plugin is broken. Read their output. Do not treat a green exit as proof.

## Scoping runs: one plugin, one file

The root Makefile auto-generates delegation targets for every plugin that has a Makefile. `make <plugin>-<target>` is identical to `make -C plugins/<plugin> <target>`:

```bash make sanctum-test # run sanctum's test suite make imbue-lint # run imbue's lint target make abstract-help # list a plugin's own targets ```

Run a single test file from inside the plugin directory:

```bash cd plugins/imbue && uv run pytest tests/unit/test_deferred_capture.py -x -q ```

Rules that save you an hour:

- Never run root `pytest` expecting plugin tests to run. Root pyproject.toml sets `norecursedirs = ["plugins/*", ...]` because plugin conftest.py files collide on import paths. Plugin tests run per-plugin, always. - Some plugins force coverage on every run. imbue's pytest `addopts` include `--cov=scripts`, `--cov-report=html:htmlcov`, and `--cov-report=xml`, so even a single-file run writes `htmlcov/` and `coverage.xml` into `plugins/imbue/`. This is normal, not a mess you made. - Coverage thresholds: root coverage `fail_under = 85`. Per-plugin overrides live in each plugin's `[tool.nightmarket]` `coverage_threshold` (per-plugin values: see night-market-validation-and-qa, the designated home for the threshold inventory). `run-plugin-tests.sh` reads that value and passes `--cov-fail-under=<n>` when the plugin runs via the pytest path.

## Artifact conventions

| Artifact | Producer | Location | Committed? | |----------|----------|----------|------------| | `htmlcov/`, `coverage.xml` | pytest coverage addopts | Repo root and per-plugin dirs | Present in tree but regenerated. Never hand-edit | | `reports/skill-graph.json` | skill-graph tooling | `reports/` | No, generated locally (`reports/` is gitignored). Rebuild with the skill-graph tooling | | `clawhub/` | `make clawhub-export` | `clawhub/manifest.json` plus one `nm-<plugin>-<skill>/` dir per exported skill | No, generated locally. `make clawhub-export` rebuilds it, and the release workflow regenerates it in CI | | `bridge/openclaw/`, `bridge/a2a/` | `make bridge-build`, `make a2a-cards` | `bridge/` | Build outputs. `make bridge-clean` removes skills and a2a | | `book/build/` | `mdbook build` (book/book.toml sets `build-dir = "build"`) | `book/build/` | No, CI-built | | `trust-report.json` | CI only: trust-attestation.yml on push to master | Workflow workspace, SLSA-attested | No, never in tree |

## Release runbook

The ecosystem ships as one version. `.claude-plugin/marketplace.json` is the version source of truth, fanned out to every plugin manifest. Gates and review policy are night-market-change-control territory. This is the mechanical sequence.

1. **Preflight.** Run `Skill(sanctum:git-workspace-review)` for a read-only workspace check. Confirm you are on a `<topic>-<version>` branch. Do not release from master.

2. **Bump the version everywhere.** Dry-run first:

```bash uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 --dry-run uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 git diff --stat ```

The script rejects any version that does not match `^\d+\.\d+\.\d+$`. It then rewrites the version field in every match of these globs, and it skips cache and venv directories:

- `**/pyproject.toml` - `**/Cargo.toml` - `**/package.json` - `**/.claude-plugin/plugin.json` - `**/.claude-plugin/metadata.json` - `**/.claude-plugin/marketplace.json` - `**/openpackage.yml` - any `**/__init__.py` that contains `__version__`

Expect a large diff of roughly 100 files. That is the design.

3. **Add the CHANGELOG entry.** CHANGELOG.md follows Keep a Changelog 1.1.0 with SemVer. Keep `## [Unreleased]` at the top. Insert `## [X.Y.Z] - YYYY-MM-DD` directly below it. Do not rewrite or de-slop historical entries.

4. **Sync the docs.** Update the per-plugin version column in `docs/api-overview.md`. Then run:

```bash make docs-sync-check ```

The check compares plugin.json registrations against the generated capabilities reference in `book/src/reference/`. If it reports drift, run `/sanctum:sync-capabilities --fix`.

5. **Open the PR and clear the gates.** Follow night-market-change-control. The gates are the pre-commit hooks, the slop check on docs, capabilities-sync, typecheck, and the security workflows.

6. **Merge to master.**

`trust-attestation.yml` fires on the push. It runs `make test`. It writes `trust-report.json`. It attaches a SLSA provenance attestation with `actions/attest-build-provenance@v4`.

7. **Tag the release.** Run `/sanctum:create-tag v1.9.16`. The command pushes a v-prefixed annotated tag. It then confirms that the release pipeline started.

8. **Let the release pipeline run.**

`cross-framework-publish.yml` fires on `v*` tags. It strips the `v` and validates the version against `^[0-9]+\.[0-9]+\.[0-9]+`. It runs the cross-framework unit tests: clawhub_export, build_bridge, a2a_cards, and framework_detect. It runs `make cross-framework`. It packages four tarballs:

- `night-market-clawhub` - `night-market-openclaw-bridge` - `night-market-a2a-cards` - `night-market-cross-framework`

It then creates the GitHub release.

One precondition applies. The publish job fails when `clawhub/manifest.json` does not exist. It also fails when `total_exported` is 0. The current count is 188.

ClawHub submission after the release stays manual. Run `./scripts/clawhub-submit.sh v<version>`.

Release checklist:

- [ ] `make test`, `make lint`, `make typecheck` all pass locally - [ ] `update_versions.py` diff reviewed and marketplace.json shows the new version - [ ] CHANGELOG has the new section, `[Unreleased]` still on top - [ ] `make docs-sync-check` clean - [ ] Tag pushed, both workflows green, release has 4 tarball assets

## Book publishing

The mdBook under `book/` deploys via deploy-book.yml:

- Triggers: push to master or main touching `book/**` or the workflow file itself, plus PRs on the same paths (build-only) and manual dispatch. - Build: `peaceiris/actions-mdbook@v2` with `mdbook-version: 'latest'`, then `mdbook build` with working-directory `book`. Output `book/build` uploads via `actions/upload-pages-artifact@v5` and deploys with `actions/deploy-pages@v5`, with one retry step if the first deploy fails. - Known fragility: mdbook is unpinned ("latest"), so a new upstream mdbook release can break the build with no change in this repo. If the book job fails right after an mdbook release, suspect that first.

Local preview, if mdbook is installed:

```bash cd book && mdbook build # output in book/build/ ```

## Cross-framework export surface

```bash make clawhub-export # export all skills to clawhub/, then validate make clawhub-export-top # top 20 most marketable skills only make clawhub-validate # re-validate an existing export make clawhub-stats # export statistics, no writes make bridge-build # (depends on clawhub-export) build bridge/openclaw/ make a2a-cards # generate A2A agent cards into bridge/a2a/ make a2a-list # list agents eligible for card generation make detect-framework # detect the active agentic framework make cross-framework # all of the above: export + bridge + cards ```

`make cross-framework` is exactly what the release pipeline runs, so running it locally before tagging catches export failures early. It prints skill and agent counts and ends with framework detection.

## When NOT to use

| You want | Use instead | |----------|-------------| | Set up uv, Python, tools from scratch | night-market-build-and-env

--- name: night-market-operations description: "Run and ship this repo: make targets, artifacts, release runbook. Use when testing, linting, or releasing. Do not use for setup; use night-market-build-and-env." ---

# Night Market Operations

This skill is the runbook for operating the claude-night-market repo: what each make target actually executes, where artifacts land, and the exact sequence that ships a release. Every command below was verified against the Makefile, scripts/, and .github/workflows/ on 2026-07-02 (repo v1.9.15).

Terms used once and reused throughout:

- **Plugin**: a directory under `plugins/` with a `.claude-plugin/plugin.json` manifest. Most have their own Makefile, pyproject.toml, and tests/. - **skrills**: a Rust CLI for skill validation and token analysis, vendored at `plugins/abstract/bin/skrills`. Every skrills target has a Python fallback, so a missing binary never blocks you. - **ClawHub export**: a cross-framework skill package format written to `clawhub/` by `scripts/clawhub_export.py`.

All commands run from the repo root unless a `cd` is shown. `uv` is required for everything Python. For environment setup, see night-market-build-and-env.

## Command anatomy

| Command | What it actually executes | When to use | Expected output shape | |---------|---------------------------|-------------|-----------------------| | `make test` | `./scripts/run-plugin-tests.sh --all`: per plugin, runs `make test --quiet` if the plugin Makefile has a `test:` target, else `uv run python -m pytest tests/ --tb=short --quiet` if pyproject mentions pytest. Skips plugins without `tests/`. | Full sweep before a PR or release. | Per-plugin pass/fail/skip lines. Failures re-run verbose. | | `make lint` | `uv run ruff format plugins/`, then `uv run ruff check --fix plugins/`, then ruff format again, then `uv run bandit --quiet -c pyproject.toml -r plugins/`. All use root pyproject.toml config. | Before every commit. Mutates files (auto-fix). | Four staged sections ending "Lint Complete". | | `make typecheck` | `./scripts/run-plugin-typecheck.sh --all`: per-plugin `uv run mypy` under each plugin's own strict config, plus a separate `uv run mypy hooks/` pass when `hooks/*.py` exists. | After type-touching changes and before release. | Per-plugin pass/fail. Hooks checked as a sub-step. | | `make validate-all` | `python3 plugins/abstract/scripts/validate_plugin.py <plugin>` for every plugin. Failures print "(validation failed)" but do NOT stop the loop or fail the target. | Structure audit after manifest edits. | One validation block per plugin. Read output, not exit code. | | `make plugin-check` | For each plugin whose Makefile has a `plugin-check:` target: `timeout 180 make -C plugins/<p> plugin-check`. Failures and timeouts print a note, exit code stays 0. | Dogfood/demo sweep before release. | Per-plugin sections. Watch for "(plugin-check failed or timed out)". | | `make docs-sync-check` | `bash scripts/capabilities-sync-check.sh` | PR touches plugin manifests or skills (mirrors capabilities-sync.yml CI). | Drift list or clean pass. Fix drift with `/sanctum:sync-capabilities --fix`. | | `make supply-chain-scan` | `python3 scripts/supply_chain_scan.py` | After dependency or lockfile changes. | Scan report between banner lines. | | `make validate-skills` | `skrills validate --skill-dir plugins --target claude` (plugin bin, then PATH). Falls back to `uv run python scripts/check_plugin_hooks.py`. | Skill frontmatter/structure check. | skrills report, or the Python fallback notice plus its output. | | `make analyze-skills` | `skrills analyze --skill-dir plugins`. Falls back to `uv run python scripts/generate_dependency_map.py`. | Skill token-budget and dependency analysis. | Token/dependency stats. | | `make status` | `make -C <plugin> status` for every plugin. | Quick overview. | Per-plugin status or "(status unavailable)". | | `make clean` | `make -C <plugin> clean` for every plugin, errors ignored. | Reset build artifacts. | "Done." |

Two targets have soft failure modes worth repeating: `make validate-all` and `make plugin-check` keep going past failures and can exit 0 while a plugin is broken. Read their output. Do not treat a green exit as proof.

## Scoping runs: one plugin, one file

The root Makefile auto-generates delegation targets for every plugin that has a Makefile. `make <plugin>-<target>` is identical to `make -C plugins/<plugin> <target>`:

```bash make sanctum-test # run sanctum's test suite make imbue-lint # run imbue's lint target make abstract-help # list a plugin's own targets ```

Run a single test file from inside the plugin directory:

```bash cd plugins/imbue && uv run pytest tests/unit/test_deferred_capture.py -x -q ```

Rules that save you an hour:

- Never run root `pytest` expecting plugin tests to run. Root pyproject.toml sets `norecursedirs = ["plugins/*", ...]` because plugin conftest.py files collide on import paths. Plugin tests run per-plugin, always. - Some plugins force coverage on every run. imbue's pytest `addopts` include `--cov=scripts`, `--cov-report=html:htmlcov`, and `--cov-report=xml`, so even a single-file run writes `htmlcov/` and `coverage.xml` into `plugins/imbue/`. This is normal, not a mess you made. - Coverage thresholds: root coverage `fail_under = 85`. Per-plugin overrides live in each plugin's `[tool.nightmarket]` `coverage_threshold` (per-plugin values: see night-market-validation-and-qa, the designated home for the threshold inventory). `run-plugin-tests.sh` reads that value and passes `--cov-fail-under=<n>` when the plugin runs via the pytest path.

## Artifact conventions

| Artifact | Producer | Location | Committed? | |----------|----------|----------|------------| | `htmlcov/`, `coverage.xml` | pytest coverage addopts | Repo root and per-plugin dirs | Present in tree but regenerated. Never hand-edit | | `reports/skill-graph.json` | skill-graph tooling | `reports/` | No, generated locally (`reports/` is gitignored). Rebuild with the skill-graph tooling | | `clawhub/` | `make clawhub-export` | `clawhub/manifest.json` plus one `nm-<plugin>-<skill>/` dir per exported skill | No, generated locally. `make clawhub-export` rebuilds it, and the release workflow regenerates it in CI | | `bridge/openclaw/`, `bridge/a2a/` | `make bridge-build`, `make a2a-cards` | `bridge/` | Build outputs. `make bridge-clean` removes skills and a2a | | `book/build/` | `mdbook build` (book/book.toml sets `build-dir = "build"`) | `book/build/` | No, CI-built | | `trust-report.json` | CI only: trust-attestation.yml on push to master | Workflow workspace, SLSA-attested | No, never in tree |

## Release runbook

The ecosystem ships as one version. `.claude-plugin/marketplace.json` is the version source of truth, fanned out to every plugin manifest. Gates and review policy are night-market-change-control territory. This is the mechanical sequence.

1. **Preflight.** Run `Skill(sanctum:git-workspace-review)` for a read-only workspace check. Confirm you are on a `<topic>-<version>` branch. Do not release from master.

2. **Bump the version everywhere.** Dry-run first:

```bash uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 --dry-run uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 git diff --stat ```

The script rejects any version that does not match `^\d+\.\d+\.\d+$`. It then rewrites the version field in every match of these globs, and it skips cache and venv directories:

- `**/pyproject.toml` - `**/Cargo.toml` - `**/package.json` - `**/.claude-plugin/plugin.json` - `**/.claude-plugin/metadata.json` - `**/.claude-plugin/marketplace.json` - `**/openpackage.yml` - any `**/__init__.py` that contains `__version__`

Expect a large diff of roughly 100 files. That is the design.

3. **Add the CHANGELOG entry.** CHANGELOG.md follows Keep a Changelog 1.1.0 with SemVer. Keep `## [Unreleased]` at the top. Insert `## [X.Y.Z] - YYYY-MM-DD` directly below it. Do not rewrite or de-slop historical entries.

4. **Sync the docs.** Update the per-plugin version column in `docs/api-overview.md`. Then run:

```bash make docs-sync-check ```

The check compares plugin.json registrations against the generated capabilities reference in `book/src/reference/`. If it reports drift, run `/sanctum:sync-capabilities --fix`.

5. **Open the PR and clear the gates.** Follow night-market-change-control. The gates are the pre-commit hooks, the slop check on docs, capabilities-sync, typecheck, and the security workflows.

6. **Merge to master.**

`trust-attestation.yml` fires on the push. It runs `make test`. It writes `trust-report.json`. It attaches a SLSA provenance attestation with `actions/attest-build-provenance@v4`.

7. **Tag the release.** Run `/sanctum:create-tag v1.9.16`. The command pushes a v-prefixed annotated tag. It then confirms that the release pipeline started.

8. **Let the release pipeline run.**

`cross-framework-publish.yml` fires on `v*` tags. It strips the `v` and validates the version against `^[0-9]+\.[0-9]+\.[0-9]+`. It runs the cross-framework unit tests: clawhub_export, build_bridge, a2a_cards, and framework_detect. It runs `make cross-framework`. It packages four tarballs:

- `night-market-clawhub` - `night-market-openclaw-bridge` - `night-market-a2a-cards` - `night-market-cross-framework`

It then creates the GitHub release.

One precondition applies. The publish job fails when `clawhub/manifest.json` does not exist. It also fails when `total_exported` is 0. The current count is 188.

ClawHub submission after the release stays manual. Run `./scripts/clawhub-submit.sh v<version>`.

Release checklist:

- [ ] `make test`, `make lint`, `make typecheck` all pass locally - [ ] `update_versions.py` diff reviewed and marketplace.json shows the new version - [ ] CHANGELOG has the new section, `[Unreleased]` still on top - [ ] `make docs-sync-check` clean - [ ] Tag pushed, both workflows green, release has 4 tarball assets

## Book publishing

The mdBook under `book/` deploys via deploy-book.yml:

- Triggers: push to master or main touching `book/**` or the workflow file itself, plus PRs on the same paths (build-only) and manual dispatch. - Build: `peaceiris/actions-mdbook@v2` with `mdbook-version: 'latest'`, then `mdbook build` with working-directory `book`. Output `book/build` uploads via `actions/upload-pages-artifact@v5` and deploys with `actions/deploy-pages@v5`, with one retry step if the first deploy fails. - Known fragility: mdbook is unpinned ("latest"), so a new upstream mdbook release can break the build with no change in this repo. If the book job fails right after an mdbook release, suspect that first.

Local preview, if mdbook is installed:

```bash cd book && mdbook build # output in book/build/ ```

## Cross-framework export surface

```bash make clawhub-export # export all skills to clawhub/, then validate make clawhub-export-top # top 20 most marketable skills only make clawhub-validate # re-validate an existing export make clawhub-stats # export statistics, no writes make bridge-build # (depends on clawhub-export) build bridge/openclaw/ make a2a-cards # generate A2A agent cards into bridge/a2a/ make a2a-list # list agents eligible for card generation make detect-framework # detect the active agentic framework make cross-framework # all of the above: export + bridge + cards ```

`make cross-framework` is exactly what the release pipeline runs, so running it locally before tagging catches export failures early. It prints skill and agent counts and ends with framework detection.

## When NOT to use

| You want | Use instead | |----------|-------------| | Set up uv, Python, tools from scratch | night-market-build-and-env