@mcptoolshop/promo-kit 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +88 -41
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.2 — 2026-02-16
4
+
5
+ ### Changed
6
+
7
+ - Rewrite npm README for scannability (product-page layout, split seed/artifact tables, KIT_CONFIG example)
8
+ - Logo sized to 420px (was 200→300, still too small on npmjs.com)
9
+
3
10
  ## 0.1.1 — 2026-02-16
4
11
 
5
12
  ### Fixed
package/README.md CHANGED
@@ -1,54 +1,74 @@
1
- <div align="center">
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/mcp-tool-shop/mcp-tool-shop/main/logo.png" width="420" alt="mcp-tool-shop logo" />
3
+ </p>
2
4
 
3
- <img src="https://raw.githubusercontent.com/mcp-tool-shop/mcp-tool-shop/main/logo.png" alt="MCP Tool Shop" width="200">
5
+ <h1 align="center">@mcptoolshop/promo-kit</h1>
4
6
 
5
- # @mcptoolshop/promo-kit
7
+ <p align="center">
8
+ <b>Portable promotion engine for tool catalogs.</b><br/>
9
+ Receipt-backed promotions · freeze modes · drift detection · <b>zero dependencies</b>
10
+ </p>
6
11
 
7
- **Portable promotion engine for tool catalogs. Receipt-backed promotions, freeze modes, drift detection — zero dependencies.**
8
-
9
- </div>
12
+ ---
10
13
 
11
14
  ## What it does
12
15
 
13
- `promo-kit` gives your tool catalog a complete promotion pipeline:
16
+ `promo-kit` gives your tool catalog a complete, governed promotion pipeline:
17
+
18
+ - **Bootstraps** a zero-state data model (governance, promo queue, experiments, submissions)
19
+ - **Generates** promotion decisions, baselines, drift reports, and trust receipts
20
+ - **Verifies inputs** with SHA-256 hashes (and ties outputs back to commits)
21
+ - **Supports freeze modes** when you need human review
22
+ - **Keeps data local** (no cloud services, no trackers, no runtime npm deps)
14
23
 
15
- - **Bootstrap** 17 zero-state seed files (governance, promo queue, experiments, etc.)
16
- - **Generate** promotion decisions, baselines, drift reports, and trust receipts
17
- - **Verify** everything with SHA-256 hashed inputs and commit SHAs
18
- - **Freeze** automation when you need human review
24
+ If your catalog needs "trust you can audit," this is the boring machinery that makes it real.
19
25
 
20
- All data stays local. No cloud dependencies. No runtime npm dependencies.
26
+ ---
21
27
 
22
28
  ## Quickstart
23
29
 
30
+ Install:
31
+
24
32
  ```bash
25
- npm install @mcptoolshop/promo-kit
33
+ npm i @mcptoolshop/promo-kit
34
+ ```
26
35
 
27
- # Initialize (auto-creates kit.config.json from template)
36
+ Initialize (creates `kit.config.json` from a template if missing, then seeds data):
37
+
38
+ ```bash
28
39
  npx promo-kit init
40
+ ```
29
41
 
30
- # Edit kit.config.json with your org details:
31
- # org.name, org.account, site.title, contact.email
42
+ Edit `kit.config.json` (minimum):
32
43
 
33
- # Validate the installation
44
+ - `org.name`
45
+ - `org.account`
46
+ - `site.title`
47
+ - `contact.email`
48
+
49
+ Validate the installation:
50
+
51
+ ```bash
34
52
  npx promo-kit selftest
35
53
  ```
36
54
 
37
- ## CLI Commands
55
+ ---
56
+
57
+ ## CLI
38
58
 
39
59
  ### `promo-kit init`
40
60
 
41
- Creates `kit.config.json` (if absent) and bootstraps 17 seed files in your data directory.
61
+ Creates `kit.config.json` (if absent) and bootstraps seed files in your configured data directory.
42
62
 
43
63
  ```bash
44
- promo-kit init # create config + seeds
45
- promo-kit init --dry-run # show what would be created
46
- promo-kit init --force # overwrite existing kit.config.json
64
+ promo-kit init
65
+ promo-kit init --dry-run
66
+ promo-kit init --force
47
67
  ```
48
68
 
49
69
  ### `promo-kit selftest`
50
70
 
51
- Validates config, seed files, and runs all portable core generators in dry-run mode.
71
+ Validates config + seeds and runs the portable core generators in dry-run mode.
52
72
 
53
73
  ```bash
54
74
  promo-kit selftest
@@ -56,7 +76,7 @@ promo-kit selftest
56
76
 
57
77
  ### `promo-kit migrate`
58
78
 
59
- Applies schema version upgrades when `kitVersion` changes.
79
+ Applies schema upgrades when `kitVersion` changes.
60
80
 
61
81
  ```bash
62
82
  promo-kit migrate
@@ -65,25 +85,33 @@ promo-kit migrate
65
85
  ### Flags
66
86
 
67
87
  ```bash
68
- promo-kit --version # show version
69
- promo-kit --help # show usage
70
- promo-kit --print-config # show resolved config after defaults
88
+ promo-kit --version
89
+ promo-kit --help
90
+ promo-kit --print-config
71
91
  ```
72
92
 
93
+ ---
94
+
73
95
  ## Programmatic API
74
96
 
75
97
  ```js
76
- import { bootstrap, migrate, getConfig, getRoot, loadKitConfig } from "@mcptoolshop/promo-kit";
77
-
78
- // Bootstrap seed files in a directory
79
- const result = bootstrap("/path/to/your/project");
98
+ import {
99
+ bootstrap,
100
+ migrate,
101
+ getConfig,
102
+ getRoot,
103
+ loadKitConfig
104
+ } from "@mcptoolshop/promo-kit";
105
+
106
+ // Create seed files (idempotent)
107
+ const result = bootstrap("/path/to/project");
80
108
  // => { success: true, errors: [], created: [...], skipped: [...] }
81
109
 
82
- // Get resolved config (deep-merged with defaults)
110
+ // Read resolved config (deep-merged with defaults)
83
111
  const config = getConfig();
84
112
 
85
- // Run migrations
86
- const migrationResult = migrate("/path/to/your/project");
113
+ // Apply migrations (if needed)
114
+ const migrationResult = migrate("/path/to/project");
87
115
  ```
88
116
 
89
117
  Config utilities are also available as a separate export:
@@ -92,36 +120,55 @@ Config utilities are also available as a separate export:
92
120
  import { getConfig, getRoot } from "@mcptoolshop/promo-kit/config";
93
121
  ```
94
122
 
123
+ ---
124
+
95
125
  ## What it generates
96
126
 
97
- `promo-kit init` creates these seed files in your data directory:
127
+ By default, `promo-kit init` creates a set of seed files in your configured data directory.
128
+
129
+ **Core seeds:**
98
130
 
99
131
  | File | Purpose |
100
132
  |------|---------|
101
- | `governance.json` | Freeze modes, promo caps, hard rules |
133
+ | `governance.json` | Freeze modes, caps, hard rules |
102
134
  | `promo-queue.json` | Weekly promotion candidates |
103
- | `experiments.json` | Active A/B experiments |
135
+ | `experiments.json` | Active experiments |
104
136
  | `submissions.json` | External tool submissions |
105
137
  | `overrides.json` | Per-tool metadata overrides |
106
138
  | `ops-history.json` | Workflow run history |
107
139
  | `feedback.jsonl` | Append-only feedback log |
108
140
  | `worthy.json` | Worthiness rubric and scores |
141
+
142
+ **Generated artifacts** (produced by the pipeline):
143
+
144
+ | File | Purpose |
145
+ |------|---------|
109
146
  | `promo-decisions.json` | Generated promotion decisions |
110
147
  | `experiment-decisions.json` | Generated experiment decisions |
111
148
  | `baseline.json` | Computed baseline metrics |
112
149
  | `feedback-summary.json` | Aggregated feedback |
113
150
  | `queue-health.json` | Queue health metrics |
114
151
  | `recommendations.json` | Advisory recommendations |
115
- | `recommendation-patch.json` | Recommended data patches |
152
+ | `recommendation-patch.json` | Recommended governed data patches |
116
153
  | `decision-drift.json` | Week-over-week drift report |
117
154
  | `telemetry/rollup.json` | Telemetry aggregates |
118
155
 
156
+ ---
157
+
119
158
  ## Environment
120
159
 
121
160
  | Variable | Purpose |
122
161
  |----------|---------|
123
162
  | `KIT_CONFIG` | Path to an alternate `kit.config.json` (overrides cwd discovery) |
124
163
 
164
+ Example:
165
+
166
+ ```bash
167
+ KIT_CONFIG=examples/pilot-org/kit.config.json npx promo-kit selftest
168
+ ```
169
+
170
+ ---
171
+
125
172
  ## Requirements
126
173
 
127
174
  - Node.js >= 22
@@ -129,9 +176,9 @@ import { getConfig, getRoot } from "@mcptoolshop/promo-kit/config";
129
176
 
130
177
  ## Links
131
178
 
132
- - [Portable Core docs](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/portable-core.md) — full contract and field reference
133
- - [Presskit Handbook](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/presskit-handbook.md) — brand assets and verification walkthrough
134
- - [Trust Center](https://mcp-tool-shop.github.io/trust/) — live verification infrastructure
179
+ - [Portable Core docs](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/portable-core.md) — contract + field reference
180
+ - [Presskit Handbook](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/presskit-handbook.md) — assets + verification walkthrough
181
+ - [Trust Center](https://mcp-tool-shop.github.io/trust/) — live example of the verification UX
135
182
 
136
183
  ## License
137
184
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mcptoolshop/promo-kit",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Portable promotion engine for tool catalogs. Receipt-backed promotions, freeze modes, drift detection.",
5
5
  "type": "module",
6
6
  "main": "./index.mjs",