Merge pull request #2 from rainlanguage/2026-07-25-docs-accuracy-post-split

docs: correct the build commands, CI description and release model

Author: thedavidmeister

CLAUDE.md

@@ -16,42 +16,46 @@ SPDX headers.
 
 ## Build & Test Commands
 
-This project uses **Nix + Foundry (Forge)**. Enter the dev shell first:
+This project uses **Nix + Foundry (Forge)**. Everything runs in the rainix
+`sol-shell`, the same shell CI uses:
 
 ```bash
-nix develop
+nix develop .#sol-shell
 ```
 
-Then use rainix tasks:
+Soldeer dependencies are not committed (`dependencies/` is gitignored), so
+install them before the first build:
 
 ```bash
-# Run all tests
-nix develop -c rainix-sol-test
+nix develop .#sol-shell -c forge soldeer install
+```
 
-# Static analysis (Slither)
-nix develop -c rainix-sol-static
+Each command below has a matching CI job:
 
-# License/legal checks (REUSE compliance)
-nix develop -c rainix-sol-legal
+```bash
+# Build
+nix develop .#sol-shell -c forge build
 
-# Prelude (dependency setup, run before other tasks)
-nix develop -c rainix-sol-prelude
-```
+# Run all tests. The five LibCloneFactoryDeployProdTest fork tests read the
+# live chains and need ARBITRUM_RPC_URL, BASE_RPC_URL, BASE_SEPOLIA_RPC_URL,
+# FLARE_RPC_URL and POLYGON_RPC_URL; without them only those five fail.
+nix develop .#sol-shell -c forge test
 
-Direct Forge commands also work inside the nix shell:
+# Run a specific test, or a specific file
+nix develop .#sol-shell -c forge test --match-test testCloneDeterministic
+nix develop .#sol-shell -c forge test --match-path test/src/concrete/CloneFactoryCloneDeterministic.t.sol
 
-```bash
-# Run all tests
-forge test
+# Formatting (CI runs `forge fmt --check`)
+nix develop .#sol-shell -c forge fmt
 
-# Run a specific test
-forge test --match-test testCloneDeterministic
+# Static analysis
+nix develop .#sol-shell -c slither .
 
-# Run tests in a specific file
-forge test --match-path test/src/concrete/CloneFactoryCloneDeterministic.t.sol
+# License/legal checks (REUSE compliance)
+nix develop .#sol-shell -c reuse lint
 
-# Build
-forge build
+# Regenerate the deploy pins for the current [package].version
+nix develop .#sol-shell -c bash -c 'forge script ./script/BuildPointers.sol && forge fmt'
 ```
 
 ## Architecture
@@ -89,12 +93,45 @@ as the `rain-factory` Soldeer dependency, so they are read under
 
 ## Deployment
 
-Deployed via deterministic Zoltu deployer (from `rain.deploy`). The canonical
-deployment address and codehash are committed in `LibCloneFactoryDeploy.sol`.
-Deployment scripts are in `script/Deploy.sol` targeting Arbitrum, Base, Base
-Sepolia, Flare, and Polygon.
+Deployed via the deterministic Zoltu deployer (from `rain.deploy`), so the
+address is a pure function of the bytecode. The canonical address and codehash
+are committed in `LibCloneFactoryDeploy.sol`. `script/Deploy.sol` deploys the
+`clone-factory` suite to the five networks `LibRainDeploy.supportedNetworks()`
+returns: Arbitrum One, Base, Base Sepolia, Flare and Polygon.
+
+A deploy is a human-dispatched run of the `Manual sol artifacts` workflow
+(`workflow_dispatch` → `rainix-manual-sol-artifacts`), never a merge and never
+part of the release workflow.
+
+## Releases and versioning
+
+This is a **deploy repo**, not a library repo, so nothing publishes on merge:
+
+- `[package].version` in `foundry.toml` is the **last released** version (it
+  names the current `src/generated/<tag>/` snapshot), not a next-version slot. A
+  normal PR does not bump it; only a release moves it.
+- A human pushes a `sol-v<version>` tag, which runs `rainix-tag-release`: it
+  writes the version from the tag into `foundry.toml`, regenerates the snapshot
+  (`forge script ./script/BuildPointers.sol && forge fmt`), verifies the live
+  chains match the fresh pins with `forge test`, publishes `rain-factory-deploy`
+  to Soldeer, and commits the new snapshot back to `main`.
+- The on-chain deploy happens **before** tagging, via the manual dispatch above;
+  `rainix-tag-release` never broadcasts, it only attests.
+- Existing `src/generated/<tag>/` snapshots are frozen: a release adds a new tag
+  directory, it never edits or deletes an existing one. CI enforces this.
 
 ## CI
 
-GitHub Actions runs three parallel jobs on every push: `rainix-sol-test`,
-`rainix-sol-static`, `rainix-sol-legal`. Fork tests require RPC URL secrets.
+`.github/workflows/rainix-sol.yaml` calls the rainix `rainix-sol` reusable on
+every push, which runs three parallel jobs:
+
+- `test` — `forge test -vvv`. The `LibCloneFactoryDeployProdTest` fork tests
+  need the `RPC_URL_*_FORK` secrets.
+- `static` — `slither .`, `forge fmt --check`, `rainix-sol-single-contract` (one
+  contract per `.sol` file), plus the org-wide gates: no ignored tests, no git
+  submodules, no `@custom:` NatSpec, and append-only `src/generated/<tag>/`
+  snapshots.
+- `legal` — `reuse lint`.
+
+The other two workflows never run on push: `package-release.yaml` fires only on
+a `sol-v*` tag, and `manual-sol-artifacts.yaml` only on `workflow_dispatch`.

README.md

@@ -14,10 +14,15 @@ address/codehash pins depend on `rain-factory-deploy`.
 ## Releases
 
 This is a deploy repo: releases are **manual `sol-v*` tags**, not merges.
-Tagging runs `rainix-tag-release`, which deploys the `clone-factory` suite,
-regenerates and verifies the snapshot against the live chain, publishes
-`rain-factory-deploy` to Soldeer, and commits the frozen snapshot back to `main`.
-Nothing publishes on merge, so `[package].version` and the generated `DEPLOY_TAG`
-only ever move together.
+
+The on-chain deploy is a separate, human-dispatched step, run **before**
+tagging: the `Manual sol artifacts` workflow runs `script/Deploy.sol` for the
+`clone-factory` suite. Tagging then runs `rainix-tag-release`, which regenerates
+the snapshot for the tagged version, verifies the live chains match those fresh
+pins, publishes `rain-factory-deploy` to Soldeer, and commits the frozen
+snapshot back to `main`. It never broadcasts a deploy itself.
+
+Nothing publishes on merge, so `[package].version` and the frozen
+`src/generated/<tag>/` snapshot it names only ever move together.
 
 See rainlanguage/rain.factory#46 for the split rationale.