@jenga-ai/agent 1.0.0

package/skills/publish/adapters/npm-ci.md

@@ -0,0 +1,223 @@
+# `npm-ci` Adapter
+
+The `npm-ci` adapter drives the `/publish deploy` flow for npm package targets.
+It publishes to npmjs.com via **GitHub Actions OIDC Trusted Publishers** — no
+`NPM_TOKEN` is stored anywhere. The adapter generates a GitHub Actions workflow
+that runs `npm publish --provenance`, commits it to the repository, and triggers
+it via `gh workflow run`. The local machine never publishes directly to npm.
+
+## Purpose
+
+Publish an npm package from a GitHub repository to npmjs.com by:
+
+1. Generating a GitHub Actions workflow that authenticates to npm using a
+   short-lived OIDC token issued by GitHub's token service.
+2. Committing the workflow file to `<workflow_path>` (default:
+   `.github/workflows/npm-publish.yml`) in the repository.
+3. Triggering the workflow via `gh workflow run`.
+
+No `NPM_TOKEN` is created, stored, or referenced. All authorisation is handled
+through the npmjs.com Trusted Publisher link established between the package and
+the repository.
+
+## Trust Boundary
+
+`publish.json` holds **only** configuration values — no secrets of any kind.
+The trust chain is OIDC-based:
+
+```
+publish.json                GitHub Actions                npmjs.com
+──────────────              ──────────────────────────    ─────────────────────────────
+github_repo: "owner/name"  ← OIDC token issued per run  ← Trusted Publisher link
+npm.package_name: "pkg"       scoped to this package        (package ↔ repo + workflow)
+npm.access: "public"
+```
+
+GitHub's token service issues a short-lived OIDC token for each workflow run.
+The npmjs.com Trusted Publisher configuration — a one-time link between the
+package name and the repository + workflow file path — is the sole source of
+authorisation. Once that link is in place, any workflow run originating from
+the linked repository and workflow path may publish the package without a stored
+token.
+
+No secret values are committed to `publish.json` or the repository. Any
+`secrets` block present in the target config is ignored by this adapter.
+
+## Invocation Contract
+
+### Inputs from `publish.json`
+
+An `npm-ci` target must define:
+
+- `name`
+- `type: npm-ci`
+- `npm.package_name` — name of the npm package to publish
+- `npm.access` — `"public"` or `"restricted"`
+- `npm.registry` — registry URL (default: `https://registry.npmjs.org`)
+- `npm.dist_tag` — npm dist-tag (e.g. `latest`, `beta`)
+- `github_repo` — **required**; `owner/name` identifying the GitHub repository
+- `workflow_path` — **optional**; path to the workflow file to generate and
+  trigger; defaults to `.github/workflows/npm-publish.yml`
+- `secrets` — **not required**; any `secrets` block present is ignored by this
+  adapter
+
+The `npm.*` fields are read through the shared `npmSettings` schema, reused
+across all npm-targeting adapters.
+
+### Required environment and tools
+
+The adapter requires the following tools at invocation time:
+
+- `jq` — to read `publish.json` target config
+- `git` — to commit the generated workflow file
+- `gh` — GitHub CLI, authenticated via `gh auth login`, to trigger the workflow
+  via `gh workflow run`
+
+The `gh` CLI must be authenticated before running `/publish deploy` against an
+`npm-ci` target.
+
+### Pipeline entrypoint
+
+```bash
+bash skills/publish/scripts/npm_ci_pipeline.sh \
+  --target <name> \
+  --config <path-to-publish.json> \
+  [--dry-run]
+```
+
+## Execution Phases
+
+Run the adapter phases in this exact order:
+
+1. **`validate`** — verify that `gh` CLI is authenticated (`gh auth status`),
+   that `github_repo` resolves to an accessible repository, and that all
+   required `npm.*` fields (`package_name`, `access`, `registry`, `dist_tag`)
+   are present and non-empty. Abort with exit 4 on any failure.
+
+2. **`generate-workflow`** — render the GitHub Actions workflow YAML in memory.
+   The generated workflow sets:
+   ```yaml
+   permissions:
+     id-token: write
+     contents: read
+   ```
+   and runs `npm publish --provenance` to attach a build provenance attestation
+   to the published package. In `--dry-run` mode, print the rendered YAML to
+   stdout and exit 0 without writing any file.
+
+3. **`commit-workflow`** — write the generated YAML to `<workflow_path>`
+   (creating the `.github/workflows/` directory if needed) and commit it with:
+   ```
+   git add <workflow_path>
+   git commit -m "chore(publish): update npm CI workflow for target <name>"
+   ```
+   If the file already exists and the content is unchanged (`git diff --quiet`),
+   skip the commit — the operation is idempotent.
+
+4. **`trigger`** — invoke:
+   ```bash
+   gh workflow run <workflow_filename> --ref <branch>
+   ```
+   where `<workflow_filename>` is the basename of `<workflow_path>`. After
+   dispatching, retrieve the run URL via
+   `gh run list --workflow <workflow_filename> --limit 1 --json url`.
+
+5. **`triggered`** — print the workflow run URL to stdout. The caller
+   (`publish_deploy.sh`) writes the ledger entry with
+   `platform_state: "triggered"`.
+
+## State Machine
+
+```
+start
+  │
+  ▼
+validate ──── exit 4 (config/env invalid)
+  │
+  ▼
+generate-workflow ──── [--dry-run] → print YAML → exit 0
+  │
+  ▼
+commit-workflow
+  │
+  ▼
+trigger ──── exit 3 (gh workflow run failed)
+  │
+  ▼
+triggered → exit 0 (success)
+```
+
+Terminal states:
+
+- **success** — all five phases complete; workflow run URL printed; exit 0.
+- **dry-run exit** — adapter exits after `generate-workflow` without writing,
+  committing, or triggering; exit 0.
+- **failure** — adapter exits with a non-zero code at the failing phase (see
+  Exit Codes).
+
+## Dry-Run Behaviour
+
+When `--dry-run` is passed:
+
+- The `validate` phase runs normally; config and environment errors still
+  surface.
+- The `generate-workflow` phase runs normally; the rendered workflow YAML is
+  printed to stdout.
+- The `commit-workflow` phase is **skipped** — no file is written, no git
+  commit is made.
+- The `trigger` phase is **skipped** — `gh workflow run` is not called.
+- The adapter exits 0 after printing the YAML.
+- The ledger entry written by `publish_deploy.sh` will have
+  `platform_state: "dry-run"`.
+
+## Exit Codes
+
+| Code | Meaning                                                                     |
+|------|-----------------------------------------------------------------------------|
+| `0`  | Pipeline completed successfully, or `--dry-run` finished cleanly            |
+| `3`  | Workflow trigger failure (`gh workflow run` exited non-zero)                 |
+| `4`  | Config or environment invalid (missing required field, `gh` not authed,     |
+|      | `github_repo` not found, or required `npm.*` field absent)                  |
+
+## Output Artefacts
+
+A successful non-dry-run produces:
+
+- The workflow file written to `<workflow_path>` in the working tree (default:
+  `.github/workflows/npm-publish.yml`) and committed to the repository
+- A git commit: `chore(publish): update npm CI workflow for target <name>`
+- A workflow run URL printed to stdout
+- A history entry in `project/logs/publish-history.json` written by
+  `publish_deploy.sh` with `platform_state: "triggered"`
+
+## Post-Deploy Manual Steps
+
+After a successful deploy trigger, the adapter prints the workflow run URL.
+The operator should:
+
+1. Open the printed run URL to monitor the publish job in GitHub Actions.
+2. Verify the package appears on npmjs.com with the expected version and
+   provenance badge (the shield icon confirming `npm publish --provenance`).
+3. Confirm the dist-tag (`latest`, `beta`, or other) is correctly applied on
+   the npmjs.com package page.
+
+The adapter does not wait for the CI run to complete — monitoring is the
+operator's responsibility.
+
+## First-run prerequisite
+
+The npmjs.com Trusted Publisher link between the package and the repository must
+be established **before** the first `/publish deploy` invocation against an
+`npm-ci` target. This one-time setup step is out of scope for the adapter itself
+and is covered by the setup wizard (see S03).
+
+Minimum pre-requisites:
+
+- The package must already exist on npmjs.com (or be publishable under your
+  npm account).
+- A Trusted Publisher must be configured on npmjs.com linking the package to
+  `github_repo` + `workflow_path`.
+- The GitHub repository must have Actions enabled.
+
+Once the Trusted Publisher link is in place, the adapter can publish on every
+invocation without any stored token.

package/skills/publish/adapters/npm.md

@@ -0,0 +1,121 @@
+# `npm` Adapter
+
+The `npm` adapter drives the `/publish deploy` flow for npm registry targets.
+It is a prompt/template contract for the agent layer and delegates concrete execution to
+`skills/publish/scripts/npm_pipeline.sh`.
+
+## Invocation Contract
+
+### Inputs from `publish.json`
+
+An `npm` target must define:
+
+- `name`
+- `type: npm`
+- `platform: npm-registry`
+- `checks.pre[]` / `checks.post[]`
+- `secrets.NPM_TOKEN` (env-var reference; `NODE_AUTH_TOKEN` is also accepted)
+- `npm.package_name`
+- `npm.access` (`public` or `restricted`)
+- `npm.registry` (optional; defaults to `https://registry.npmjs.org`)
+- `npm.dist_tag` (optional; defaults to `latest`)
+
+### Required environment variables
+
+The adapter uses env-var references only and never stores secret values in repo files.
+The required env vars are:
+
+- `NPM_TOKEN` (or `NODE_AUTH_TOKEN` — either satisfies the auth requirement)
+
+Validate them before execution with:
+
+```bash
+bash skills/publish/scripts/validate_npm_env.sh <path-to-publish.json>
+```
+
+### Pipeline entrypoint
+
+```bash
+bash skills/publish/scripts/npm_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive]
+```
+
+## Execution Phases
+
+Run the adapter phases in this exact order:
+
+1. `validate`
+2. `gates`
+3. `pack`
+4. `publish`
+5. `tag`
+
+Quality gates run inside the `gates` phase and must include `npm test`. If the consumer `package.json` declares a `build` script, `npm run build` also runs as a gate. Once control enters the adapter, external publish-side commands are restricted to direct `npm` and `git` invocations.
+
+## State Machine
+
+The adapter records these transitions in `project/logs/publish-history.json`:
+
+```text
+idle → validating → gating → packing → publishing → tagging → published
+                                              └───────────────→ failed
+```
+
+### State meanings
+
+- `idle` — conceptual pre-start state before a history row is appended
+- `validating` — token presence and `publish.json` npm block are being verified
+- `gating` — `npm test` (and `npm run build` when present) are running
+- `packing` — `npm pack` is generating the tarball for inspection
+- `publishing` — `npm publish` is running against the configured `registry` with the resolved `access` and `dist_tag`
+- `tagging` — `git tag v<version>` is being created and (optionally) pushed
+- `published` — publish and tag both succeeded; package is visible on the registry
+- `failed` — any validation/gate/publish/tag failure; `completed_at` must be set
+
+## Dry-run Mode
+
+`--dry-run` is mandatory for safe CI validation without live npm credentials.
+
+Behavior:
+
+- The `publish` phase runs `npm publish --dry-run` instead of a live publish. No package is written to the registry; npm prints the tarball contents and would-be metadata.
+- All `git tag` / `git push` commands are printed with a `[DRY RUN]` prefix and are **not** executed.
+- State-machine writes still happen so reviewers can inspect the planned flow.
+- Token presence is still validated so dry-runs surface auth misconfiguration early.
+- The adapter exits `0` after simulating a successful publish.
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Pipeline completed successfully or dry-run finished successfully |
+| `2` | Missing `NPM_TOKEN` / `NODE_AUTH_TOKEN`, config validation failure, or quality-gate failure (`npm test` / `npm run build`) |
+| `3` | `npm publish` failure, `git tag` failure, or history-update failure |
+
+### Success condition
+
+`npm publish` exits `0` and the package is retrievable from the configured registry at the newly-published `version` and `dist_tag`.
+
+### Failure conditions
+
+- **Missing token** — `NPM_TOKEN` (and `NODE_AUTH_TOKEN`) unset → exit `2`
+- **Gate failure** — `npm test` or `npm run build` non-zero → exit `2`
+- **Publish error** — `npm publish` non-zero (network, 403, version conflict, etc.) → exit `3`
+
+## Output Artefacts
+
+A successful run produces:
+
+- A published package on the configured npm registry (npmjs.com by default), reachable at `https://www.npmjs.com/package/<package_name>/v/<version>`
+- A local (and optionally pushed) git tag `v<version>` matching the published `version`
+- A history row appended to `project/logs/publish-history.json`
+
+## Post-deploy manual steps
+
+After a successful publish, the deploy flow must print:
+
+✅ Publish complete. Next manual steps:
+1. Verify the package on the registry: https://www.npmjs.com/package/<package_name>/v/<version>
+2. Push the git tag if not already pushed: `git push origin v<version>`
+3. Draft release notes (GitHub Releases or your changelog of choice)
+
+Print the same block in `--non-interactive` mode so CI logs capture it.

package/skills/publish/assets/ExportOptions.plist.template

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>method</key>
+  <string>{{EXPORT_METHOD}}</string>
+  <key>teamID</key>
+  <string>{{TEAM_ID}}</string>
+  <key>signingStyle</key>
+  <string>manual</string>
+  <key>signingCertificate</key>
+  <string>{{SIGNING_IDENTITY}}</string>
+  <key>provisioningProfiles</key>
+  <dict>
+    <key>{{BUNDLE_ID}}</key>
+    <string>{{PROVISIONING_PROFILE_UUID}}</string>
+  </dict>
+</dict>
+</plist>

package/skills/publish/assets/ci-contract.md

@@ -0,0 +1,111 @@
+# `/publish` deploy contract
+
+This document defines the CI-safe execution contract for the scaffolded `/publish` workflow. Interactive flows added later must wrap this contract and must not weaken it.
+
+## Validation order
+
+Every `/publish` invocation must perform these steps before command-specific work:
+
+1. Resolve config path (`--config <path>` or default `project/configs/publish.json`)
+2. Run `bash skills/publish/scripts/validate_config.sh <resolved-path>`
+3. Abort immediately with exit code `4` if the file is missing, invalid JSON, or fails validation
+4. For the iOS adapter, run `bash skills/publish/scripts/validate_ios_env.sh <resolved-path>` before build/upload work begins
+
+## Inputs
+
+| Purpose | Flag | Environment Variable | Required in non-interactive mode? | Notes |
+|---|---|---|---|---|
+| Select deploy target | `--target <name>` | `PUBLISH_TARGET` | Yes | Flag takes precedence over env var |
+| Skip confirmation prompts | `--yes` | `PUBLISH_YES` | Yes | Env var truthy values: `1`, `true`, `yes`, `on` |
+| Override config path | `--config <path>` | — | No | Defaults to `project/configs/publish.json` |
+| Reuse prepared release notes | `--release-notes <path>` | — | No | Reserved for later release-note flow |
+| Dry-run execution | `--dry-run` | `PUBLISH_DRY_RUN` | No | Prints allowlisted `xcodebuild` / `xcrun` commands without executing them |
+
+## Required contract
+
+For a CI or agent-driven deploy, the caller must provide:
+
+- a valid target via `--target` or `PUBLISH_TARGET`
+- confirmation bypass via `--yes` or truthy `PUBLISH_YES`
+- a valid config file at the provided path or the default path
+- the required iOS credential environment variables when the `mobile-ios` adapter is used
+
+If any of these are missing in a non-interactive execution context, the command must fail fast rather than prompting.
+
+## Mandatory global pre-deploy gates
+
+`build` and `test` are mandatory global gates for `/publish deploy`.
+
+- They run first on every `pre` gate pass.
+- They cannot be disabled, removed, or overridden by target configuration.
+- If `publish.json` also lists `build` or `test` under target-specific pre-gates, the runner ignores those duplicates and keeps the mandatory global versions.
+- If either mandatory gate fails, the gate runner surfaces the full command output and exits with code `2` without continuing to later gates.
+
+## Configurable target gates
+
+Per-target gates may add optional checks such as:
+
+- `lint`
+- `type-check`
+- `custom-script`
+- `smoke-test`
+- `ping`
+
+These run only after the mandatory global gates succeed.
+
+## Optional contract
+
+These inputs remain optional in non-interactive mode:
+
+- `--config <path>` when the default config exists
+- `--release-notes <path>`
+- `--from-tag` and `--to-ref` on `/publish release-notes`
+
+## Exit codes
+
+| Code | Meaning | Current story coverage |
+|---|---|---|
+| `0` | Success | Config/env validation succeeds, dry-runs complete, and later deploy steps finish |
+| `1` | User abort | Reserved for interactive confirmation flow |
+| `2` | Quality gate failure | Implemented by the gate runner |
+| `3` | Deploy failure | Used by the iOS adapter pipeline for build/export/upload failures |
+| `4` | Config or environment invalid | Implemented by validation scripts |
+
+## Precedence rules
+
+1. Command-line flags win over environment variables.
+2. Environment variables are only fallbacks where explicitly supported.
+3. Missing/invalid config always stops execution before target resolution or deploy steps.
+4. Missing required iOS env vars stop execution before any `xcodebuild` or `xcrun` command runs.
+
+## Interactive vs non-interactive behavior
+
+- Interactive mode offers: `[r] Retry after fixing / [a] Abort deploy`
+- Retries are capped at 3 attempts per failed gate
+- `--non-interactive` disables prompts and aborts immediately on any gate failure
+- Every gate failure is appended to `project/logs/publish-history.json`
+- `--dry-run` still records adapter state transitions so the planned pipeline can be reviewed safely
+
+## Example CI invocations
+
+### Flag-driven
+
+```bash
+publish deploy --target staging-appstore --yes --dry-run
+```
+
+### Mixed flag + env var
+
+```bash
+PUBLISH_YES=true publish deploy --target staging-appstore --dry-run
+```
+
+### Fully env-driven target selection
+
+```bash
+PUBLISH_TARGET=staging-appstore PUBLISH_YES=1 publish deploy --dry-run
+```
+
+## Scope notes
+
+This story set does not perform live Apple API calls during verification. The iOS adapter is structured around allowlisted `xcodebuild` and `xcrun` commands and relies on caller-provided credentials and a local Apple toolchain.

package/skills/publish/assets/ownership-matrix.md

@@ -0,0 +1,17 @@
+# Publish Agent Ownership Matrix
+
+The `/publish` skill is initiated by the operator running the CLI, but each action has a defined workflow owner inside the multi-agent system.
+
+| Action | Developer | Tester | Scrum Master |
+|---|---|---|---|
+| `/publish setup` | Initiates and owns | May run to configure test targets | Never |
+| `/publish deploy --target staging` | Initiates | May run as part of test cycle | Never directly |
+| `/publish deploy --target production` | Initiates with explicit confirmation | Reviews ledger entry post-deploy | Reviews `/status` only |
+| `/publish history` | Reads for context | Reads for test baseline | Reads in `/status` review |
+| `/publish release-notes` | Generates and reviews draft | May read draft for test context | Reviews content for sprint summary |
+| Gate failure resolution | Owns rework | Validates rework | Escalates if blocked |
+| Ledger entry disputes | Never modifies | Never modifies | Flags as rapport; human resolves |
+
+## Trust boundary
+
+The `mobile-ios` adapter may only execute direct `xcodebuild` and `xcrun` commands. Arbitrary shell commands are not permitted inside the adapter pipeline.

package/skills/publish/assets/publish.example.json

@@ -0,0 +1,85 @@
+{
+  "version": 1,
+  "defaults": {
+    "history_file": "project/logs/publish-history.json",
+    "mandatory_checks": [
+      "build",
+      "test"
+    ],
+    "optional_checks": [
+      "lint",
+      "type-check",
+      "custom-script",
+      "smoke-test",
+      "ping"
+    ]
+  },
+  "targets": [
+    {
+      "name": "staging-appstore",
+      "type": "mobile-ios",
+      "platform": "ios-app-store",
+      "checks": {
+        "pre": [
+          "lint",
+          "type-check"
+        ],
+        "post": [
+          "smoke-test"
+        ]
+      },
+      "secrets": {
+        "app_store_connect_api_key_id": "$APP_STORE_CONNECT_API_KEY_ID",
+        "app_store_connect_issuer_id": "$APP_STORE_CONNECT_ISSUER_ID",
+        "app_store_connect_private_key_path": "$APP_STORE_CONNECT_PRIVATE_KEY_PATH",
+        "code_sign_identity": "$CODE_SIGN_IDENTITY",
+        "provisioning_profile_uuid": "$PROVISIONING_PROFILE_UUID"
+      },
+      "ios": {
+        "project_path": "ios/ExampleApp.xcodeproj",
+        "scheme": "ExampleApp",
+        "configuration": "Release",
+        "archive_path": "build/ios/staging/ExampleApp.xcarchive",
+        "export_path": "build/ios/staging/export",
+        "export_method": "ad-hoc",
+        "bundle_id": "com.example.myapp.staging",
+        "team_id": "ABCDE12345",
+        "app_store_app_id": "1234567890",
+        "provider_short_name": "exampleco"
+      },
+      "notes": "Scaffold example only. Replace paths and identifiers with your real iOS project values."
+    },
+    {
+      "name": "production-appstore",
+      "type": "mobile-ios",
+      "platform": "ios-app-store",
+      "checks": {
+        "pre": [
+          "lint",
+          "type-check"
+        ],
+        "post": []
+      },
+      "secrets": {
+        "app_store_connect_api_key_id": "$APP_STORE_CONNECT_API_KEY_ID",
+        "app_store_connect_issuer_id": "$APP_STORE_CONNECT_ISSUER_ID",
+        "app_store_connect_private_key_path": "$APP_STORE_CONNECT_PRIVATE_KEY_PATH",
+        "code_sign_identity": "$CODE_SIGN_IDENTITY",
+        "provisioning_profile_uuid": "$PROVISIONING_PROFILE_UUID"
+      },
+      "ios": {
+        "workspace_path": "ios/ExampleApp.xcworkspace",
+        "scheme": "ExampleApp",
+        "configuration": "Release",
+        "archive_path": "build/ios/production/ExampleApp.xcarchive",
+        "export_path": "build/ios/production/export",
+        "export_method": "app-store",
+        "bundle_id": "com.example.myapp",
+        "team_id": "ABCDE12345",
+        "app_store_app_id": "1234567890",
+        "provider_short_name": "exampleco"
+      },
+      "notes": "Production upload example using App Store export mode."
+    }
+  ]
+}

package/skills/publish/assets/publish.example.npm-ci.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "defaults": {
+    "history_file": "project/logs/publish-history.json",
+    "mandatory_checks": [
+      "build",
+      "test"
+    ],
+    "optional_checks": [
+      "lint",
+      "type-check",
+      "smoke-test"
+    ]
+  },
+  "targets": [
+    {
+      "name": "npm-ci-jenga-agent",
+      "type": "npm-ci",
+      "platform": "npm-ci-oidc",
+      "github_repo": "samwelmunga/jenga-npm",
+      "workflow_path": ".github/workflows/npm-publish.yml",
+      "checks": {
+        "pre": [
+          "lint",
+          "type-check"
+        ],
+        "post": [
+          "smoke-test"
+        ]
+      },
+      "npm": {
+        "package_name": "jenga-agent",
+        "access": "public",
+        "registry": "https://registry.npmjs.org",
+        "dist_tag": "latest"
+      },
+      "notes": "Scaffold example for a CI-only npm publish via GitHub Actions OIDC (Trusted Publishers). No NPM_TOKEN is required — npmjs.com authenticates the publish using a short-lived OIDC token issued by GitHub's token service. The one-time setup step is: on npmjs.com, go to the package Settings → Publishing → Trusted Publishers → Add publisher → GitHub Actions → enter github_repo and workflow_path → Save. Once configured, only the linked workflow can publish this package — local npm publish with a token will be rejected."
+    }
+  ]
+}

package/skills/publish/assets/publish.example.npm.json

@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "defaults": {
+    "history_file": "project/logs/publish-history.json",
+    "mandatory_checks": [
+      "build",
+      "test"
+    ],
+    "optional_checks": [
+      "lint",
+      "type-check",
+      "smoke-test"
+    ]
+  },
+  "targets": [
+    {
+      "name": "npm-public",
+      "type": "npm",
+      "platform": "npm-registry",
+      "checks": {
+        "pre": [
+          "lint",
+          "type-check"
+        ],
+        "post": [
+          "smoke-test"
+        ]
+      },
+      "secrets": {
+        "NPM_TOKEN": "$NPM_TOKEN"
+      },
+      "npm": {
+        "package_name": "jenga-agent",
+        "access": "public",
+        "registry": "https://registry.npmjs.org",
+        "dist_tag": "latest"
+      },
+      "notes": "Scaffold example for a public npm registry publish. Field guide: `package_name` = the name that will appear in the registry (supports @scope/name); `access` = \"public\" for openly-installable packages or \"restricted\" for private packages; `registry` = target registry URL (default https://registry.npmjs.org, override for private registries or GitHub Packages); `dist_tag` = npm dist-tag applied to this publish (default \"latest\", use \"next\" or \"beta\" for pre-releases). The `secrets.NPM_TOKEN` entry maps to the `NPM_TOKEN` env var loaded at publish time — never hard-code the token value here."
+    }
+  ]
+}