smartcontractkit
diff --git a/‎.agent/playbooks/RELEASE_PLAYBOOK.md‎
Lines changed: 46 additions & 0 deletions b/‎.agent/playbooks/RELEASE_PLAYBOOK.md‎
Lines changed: 46 additions & 0 deletions
diff --git a/‎.claude/skills/release.md‎
Lines changed: 6 additions & 0 deletions b/‎.claude/skills/release.md‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎.cursor/rules/general.mdc‎
Lines changed: 6 additions & 0 deletions b/‎.cursor/rules/general.mdc‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎.github/workflows/publish.yml‎
Lines changed: 43 additions & 20 deletions b/‎.github/workflows/publish.yml‎
Lines changed: 43 additions & 20 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 124 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 124 additions & 0 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 29 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 29 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 3 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎package-lock.json‎
Lines changed: 3 additions & 3 deletions b/‎package-lock.json‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎package.json‎
Lines changed: 4 additions & 2 deletions b/‎package.json‎
Lines changed: 4 additions & 2 deletions
@@ -0,0 +1,46 @@
+# Release Playbook
+
+Step-by-step guide for publishing beta and stable releases of `@chainlink/local`.
+
+## Release and Publish Rules
+- Publishing workflow: `.github/workflows/publish.yml`
+- Triggers:
+  - automatic on tag push `v*`
+  - manual fallback via `workflow_dispatch`
+- Before publishing any beta or stable release, `CHANGELOG.md` must be updated for that version using [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+- Version check:
+  - tag version must match `package.json` version
+- Branch policy:
+  - beta tag (`vX.Y.Z-beta`) must come from `develop`
+  - stable tag (`vX.Y.Z`) must come from `main`
+
+## Feature Development (beta track)
+1. Branch from `develop` (for example `feat/<name>`, or `devrel-123/<name>`).
+2. Open a draft PR targeting `develop`.
+3. Commit incrementally using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+4. Keep docs/tests updated (`npm run generate-docs` when docs sources changed).
+5. Mark PR ready, get review, merge into `develop`.
+
+## Publish Beta Release
+1. Ensure `package.json` version is beta-formatted (for example `0.3.1-beta`).
+2. Update `CHANGELOG.md` for the new release using [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) + [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+3. Draft GitHub release with:
+   - tag: `v<version>-beta`
+   - target: `develop`
+   - pre-release: enabled
+   - release title: `v<version>-beta`
+4. Publish the release (tag push triggers publish workflow automatically).
+5. If needed, use manual `workflow_dispatch` fallback from `develop` with `release_type=beta`.
+
+## Promote to Stable Release
+1. Open PR from `develop` to `main`.
+2. Update `package.json` version to stable (remove `-beta` suffix).
+3. Update `CHANGELOG.md` for the stable release using [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) + [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+4. Merge into `main` after review.
+5. Draft GitHub release with:
+   - tag: `v<version>`
+   - target: `main`
+   - pre-release: disabled
+   - release title: `v<version>`
+6. Publish release (tag push triggers stable publish automatically).
+7. If needed, run manual fallback from `main` with `release_type=stable`.
@@ -0,0 +1,6 @@
+---
+name: release
+description: Use when publishing a beta or stable release, creating release tags, or following the release workflow
+---
+
+Read `.agent/playbooks/RELEASE_PLAYBOOK.md` in the repository root and follow the instructions for the requested release type (beta or stable).
@@ -0,0 +1,6 @@
+---
+description: General project rules for Chainlink Local
+globs:
+---
+
+All project rules, conventions, and commands are in [AGENTS.md](../../AGENTS.md) at the repository root. Read it before starting any task.
@@ -27,6 +27,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Use Node.js
         uses: actions/setup-node@v4
@@ -76,11 +78,8 @@ jobs:
         id: release-type
         run: |
           if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" =~ ^refs/tags/v.* ]]; then
-            # Get the branch that was tagged (usually the default branch of the tag)
-            BRANCH_NAME="${{ github.ref_name }}"
-            
             # Check if tag contains 'beta' to determine release type
-            if [[ "${{ github.ref_name }}" == *"beta"* ]]; then
+            if [[ "${{ github.ref_name }}" == *"-beta"* ]]; then
               echo "type=beta" >> $GITHUB_OUTPUT
               echo "expected_branch=develop" >> $GITHUB_OUTPUT
             else
@@ -99,32 +98,56 @@ jobs:
 
       - name: Validate branch for release type
         run: |
-          CURRENT_BRANCH="${{ github.ref_name }}"
           EXPECTED_BRANCH="${{ steps.release-type.outputs.expected_branch }}"
           RELEASE_TYPE="${{ steps.release-type.outputs.type }}"
-          
-          echo "Current branch: $CURRENT_BRANCH"
-          echo "Expected branch for $RELEASE_TYPE release: $EXPECTED_BRANCH"
-          
-          # For manual dispatch, we can't validate branch, so skip
-          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-            echo "⚠️ Manual dispatch detected - skipping branch validation"
-            echo "Please ensure you're running from the correct branch:"
-            echo "- Beta releases should be from 'develop' branch"
-            echo "- Stable releases should be from 'main' branch"
+
+          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" =~ ^refs/tags/v.* ]]; then
+            TAG_NAME="${{ github.ref_name }}"
+            TAG_SHA="${{ github.sha }}"
+
+            echo "Tag: $TAG_NAME"
+            echo "Tag commit: $TAG_SHA"
+            echo "Expected branch for $RELEASE_TYPE release: $EXPECTED_BRANCH"
+
+            # Ensure expected branch ref exists locally.
+            if ! git fetch --no-tags --prune origin "${EXPECTED_BRANCH}"; then
+              echo "❌ Branch validation failed!"
+              echo "Could not fetch expected branch from origin: $EXPECTED_BRANCH"
+              exit 1
+            fi
+
+            if ! git show-ref --verify --quiet "refs/remotes/origin/${EXPECTED_BRANCH}"; then
+              echo "❌ Branch validation failed!"
+              echo "Could not fetch expected branch: $EXPECTED_BRANCH"
+              exit 1
+            fi
+
+            # Validate the tagged commit belongs to expected branch history.
+            if ! git merge-base --is-ancestor "$TAG_SHA" "origin/${EXPECTED_BRANCH}"; then
+              echo "❌ Branch validation failed!"
+              echo "Tag commit is not contained in branch: $EXPECTED_BRANCH"
+              echo "Please create the tag from the correct branch"
+              exit 1
+            fi
+
+            echo "✅ Tag ancestry validation passed"
             exit 0
           fi
-          
-          # For tag pushes, validate branch
+
+          # workflow_dispatch: validate selected branch directly.
+          CURRENT_BRANCH="${{ github.ref_name }}"
+          echo "Selected workflow branch: $CURRENT_BRANCH"
+          echo "Expected branch for $RELEASE_TYPE release: $EXPECTED_BRANCH"
+
           if [[ "$CURRENT_BRANCH" != "$EXPECTED_BRANCH" ]]; then
             echo "❌ Branch validation failed!"
             echo "Current branch: $CURRENT_BRANCH"
             echo "Expected branch for $RELEASE_TYPE release: $EXPECTED_BRANCH"
-            echo "Please create the tag from the correct branch"
+            echo "For manual runs, choose the correct branch in 'Use workflow from'."
             exit 1
           fi
-          
-          echo "✅ Branch validation passed"
+
+          echo "✅ Manual branch validation passed"
 
       - name: Publish stable release
         if: steps.release-type.outputs.type == 'stable'
 
@@ -0,0 +1,124 @@
+# Chainlink Local - Agents Guide
+
+Guide for AI coding agents working in `smartcontractkit/chainlink-local`.
+
+## What this library does
+
+Chainlink Local is a developer-focused testing package that simulates Chainlink services (especially CCIP) in local and forked environments.
+
+- Local mode (`CCIPLocalSimulator`, `DataStreamsLocalSimulator`) lets developers test app logic quickly without waiting for live offchain systems.
+- Fork mode (`CCIPLocalSimulatorFork`, `DataStreamsLocalSimulatorFork`) runs against forked networks so integrations behave closer to real testnet conditions.
+- The intent is parity of user app behavior between local/fork testing and testnet deployment (minus environment-specific addresses/config).
+- It is available for usage in Foundry, Hardhat 3, Hardhat 2 and Remix IDE environments.
+- Official documentation is available at: https://docs.chain.link/chainlink-local
+
+## Goal
+- Make minimal, correct changes that preserve simulator behavior and test ergonomics.
+- Prefer targeted edits and targeted tests over broad refactors.
+
+## Context Budget First
+Load files in this order and stop as soon as you have enough context:
+1. `package.json` (scripts, versions, docs/release commands)
+2. `foundry.toml` and `hardhat.config.ts` (tooling layout)
+3. Only the relevant `src/**` files and matching tests in `test/**`
+4. If docs task: `helper_doc/*.mjs` and `api_reference/**`
+5. If release/publish task: `.github/workflows/publish.yml`
+
+Avoid loading large/unnecessary trees unless explicitly required:
+- `lib/**`, `out/**`, `cache/**`, `artifacts/**`, `node_modules/**`
+
+## Directory layout
+- `src/`: production contracts by service (`ccip`, `data-feeds`, `data-streams`)
+- `src/test/`: helper/example contracts used by tests
+- `test/smoke/`: local-mode tests
+- `test/e2e/`: fork-mode tests
+- `test/unit/`: unit-level tests
+- `scripts/`: helpers for Hardhat users that write tests using JavaScript or TypeScript
+- `helper_doc/`: docs generation scripts (you shouldn't touch these)
+- `api_reference/`: generated docs output (read only; do not edit directly)
+
+## Hard Rules
+- Never edit `lib/**`. If user explicitly asks, use forge for dependency management.
+- Never edit `node_modules/**`. If user explicitly asks, use npm for dependency management.
+- Keep changes surgical; do not refactor unrelated code.
+- Preserve test placement conventions:
+  - local mode -> `test/smoke/**`
+  - fork mode -> `test/e2e/**`
+- Do not hand-edit generated docs in `api_reference/**`; regenerate via scripts.
+- If a command fails after deleting generated docs, restore state before continuing.
+
+## Common Commands
+- Compile:
+  - `npm run forge-compile`
+  - `npm run hardhat-compile`
+- Test:
+  - `npm run forge-test`
+  - `npm run hardhat-test`
+  - `forge test <path-to-test>`
+- Docs:
+  - `npm run generate-docs` (deterministic; does not fetch Register data)
+  - `npm run update-register` (networked; updates `src/ccip/Register.sol`)
+
+## Release and Publish
+For the full release workflow (beta, stable, branch policy, CHANGELOG requirements), see [`.agent/playbooks/RELEASE_PLAYBOOK.md`](.agent/playbooks/RELEASE_PLAYBOOK.md).
+
+## Dependency Policy
+- Keep `@chainlink/contracts` and `@chainlink/contracts-ccip` as direct `dependencies`.
+- Avoid introducing new tooling dependencies unless there is a clear maintenance win.
+- If bumping Chainlink packages, do not move them to `devDependencies` or `peerDependencies`.
+
+### Current core npm dependency versions
+| Package | Version |
+| --- | --- |
+| `@chainlink/contracts-ccip` | `1.6.2` |
+| `@chainlink/contracts` | `1.5.0` |
+
+## Dependency Update Playbook
+Use these commands unless a maintainer requests something different.
+
+### npm / Hardhat dependencies
+- Add runtime dependency:
+  - `npm install <package>@<version>`
+- Add dev dependency:
+  - `npm install --save-dev <package>@<version>`
+- Update existing dependency:
+  - `npm install <package>@<new-version>`
+- Verify:
+  - check `package.json` (`dependencies` vs `devDependencies` placement)
+  - run the smallest relevant compile/test command
+- Example (`@chainlink/contracts` -> `1.2.0`):
+  - `npm install @chainlink/contracts@1.2.0`
+
+### Foundry dependencies
+- Optional: pull latest submodule state first (all or specific):
+  - `forge update`
+  - `forge update lib/chainlink-evm lib/chainlink-ccip`
+- Install/update with pinned tag:
+  - `forge install <org>/<repo>@<tag>`
+- For direct dependencies:
+  - `@chainlink/contracts` equivalent:
+    - `forge install smartcontractkit/chainlink-evm@contracts-v<version>`
+  - `@chainlink/contracts-ccip` equivalent:
+    - `forge install smartcontractkit/chainlink-ccip@contracts-ccip-v<version>`
+- Historical note:
+  - older docs may reference `chainlink-brownie-contracts`; this repo uses `chainlink-evm`.
+- After install:
+  - verify `lib/` points to the expected tag/commit
+  - verify npm versions in `package.json`
+  - run `forge build` and relevant tests
+  - never edit vendored files manually inside `lib/**` or `node_modules/**`
+
+## Change Checklist
+Before finishing:
+1. Run the smallest relevant compile/test command(s).
+2. Regenerate docs if your change affects docs sources.
+3. Confirm no accidental edits in unrelated files.
+4. Summarize:
+   - what changed
+   - what was intentionally not touched
+   - any residual risk or follow-up
+
+## Known Good Defaults
+- Node.js `22.x` is the safe default for workflow parity.
+- Prefer `rg` for search.
+- Prefer explicit, boring solutions over abstraction-heavy changes.
@@ -6,6 +6,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.8] - 5 May 2026
+
+### Dependencies
+
+| Package                   | Version |
+| ------------------------- | ------- |
+| @chainlink/contracts-ccip | 1.6.2   |
+| @chainlink/contracts      | 1.5.0   |
+
+### Added
+
+- Data Streams Report versions V1, V5-V13
+- CCIP Network Details Update Script to fetch and update CCIP network details from Chainlink's API
+
+## [0.2.8-beta] - 14 January 2026
+
+### Dependencies
+
+| Package                   | Version |
+| ------------------------- | ------- |
+| @chainlink/contracts-ccip | 1.6.2   |
+| @chainlink/contracts      | 1.5.0   |
+
+### Added
+
+- CCIP Network Details Update Script to fetch and update CCIP network details from Chainlink's API
+
 ## [0.2.7] - 9 November 2025
 
 ### Dependencies
@@ -608,3 +635,5 @@ and this project adheres to
 [0.2.6]: https://github.com/smartcontractkit/chainlink-local/releases/tag/v0.2.6
 [0.2.7-beta.0]: https://github.com/smartcontractkit/chainlink-local/releases/tag/v0.2.7-beta.0
 [0.2.7]: https://github.com/smartcontractkit/chainlink-local/releases/tag/v0.2.7
+[0.2.8-beta]: https://github.com/smartcontractkit/chainlink-local/releases/tag/v0.2.8-beta
+[0.2.8]: https://github.com/smartcontractkit/chainlink-local/releases/tag/v0.2.8
@@ -0,0 +1,3 @@
+# Claude Code Instructions
+
+All project rules, conventions, and commands are in [`AGENTS.md`](AGENTS.md). Read it before starting any task.
@@ -2,7 +2,7 @@
   "name": "@chainlink/local",
   "description": "Chainlink Local Simulator",
   "license": "MIT",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "files": [
     "src/**/*.sol",
     "!src/test/**/*",
@@ -27,7 +27,9 @@
     "generate-solidity": "rimraf api_reference/solidity && npm run hardhat-compile && npm run forge-compile && npx hardhat docgen",
     "generate-jsdoc": "rimraf api_reference/javascript && npx ts-node helper_doc/generate-jsdoc.ts",
     "generate-index": "npx ts-node helper_doc/generate-index-files.ts",
-    "generate-docs": "npm run generate-solidity && npm run generate-jsdoc && npm run generate-index && npm run prettier"
+    "pregenerate-docs": "npm run update-register",
+    "generate-docs": "npm run generate-solidity && npm run generate-jsdoc && npm run generate-index && npm run prettier",
+    "update-register": "node scripts/ccip/updateRegisterContract.js"
   },
   "devDependencies": {
     "@nomicfoundation/hardhat-foundry": "^1.1.1",
-Original file line number
+Diff line change
@@ @@ -0,0 +1,6 @@ @@
 +---
 +description: General project rules for Chainlink Local
 +globs:
 +---
++
 +All project rules, conventions, and commands are in [AGENTS.md](../../AGENTS.md) at the repository root. Read it before starting any task.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Claude Code Instructions`
	`2`	`+`
	`3`	+All project rules, conventions, and commands are in [`AGENTS.md`](AGENTS.md). Read it before starting any task.