[zachfedor]

Restores Scaffold's local-first model: local is for experimenting freely, testnet is staging and a deliberate dry run, and mainnet is copied over when it's ready. build follows scaffold.yml instead of flags, and each checkout of a project keeps its own record of what it deployed, so projects and worktrees that share stellar-cli's global config no longer reuse each other's contracts.

Companion UI PR: stellar-scaffold/ui#282 (same branch, feat/config-driven-network). Both PRs carry the cross-repo label so each one's CI builds against the other.

Changes

Network selection

• Precedence is --network, then STELLAR_NETWORK, then stellar network use, then local.
• build now says when the network came from stellar network use, and config show resolves the network the same way build does.
• "Not deploying" messages name the network.

build with a version 2 scaffold.yml

• Always deploys and generates clients for networks that allow deploys. --build-clients is accepted but only prints a note.
• init without a frontend and upgrade only compile.

.scaffold/state.json (new state module)

• Records, for each network, the contract ID and saved alias of each deployed contract. The format version is independent of scaffold.yml's.
• Machine-local: .scaffold/ ignores itself with its own .gitignore. Writes are atomic.
• build decides between deploying, upgrading and reusing from this record, not from stellar-cli's global aliases.
• If a network name is redefined with a different passphrase, the entries recorded for it are dropped.

Aliases

• Scaffold saves aliases itself as <directory>-<contract> (e.g. my-app-guess_the_number) and no longer passes --alias to stellar contract deploy. Separate checkouts and worktrees get separate aliases.
• It only overwrites an alias that's free or already its own. Otherwise it warns and prints the stellar contract alias remove command.
• After the project directory is renamed, the next deploy removes the old alias.

clean

• Removes only the recorded aliases that still point at the recorded contracts, then deletes state.json.
• No longer removes keys, which may be shared with other projects.

Docs

• Configuration and CLI reference, the tutorial, and the agent skill are updated for all of the above.

Upgrading (release note)

Scaffold now records deployments in .scaffold/state.json and no longer finds them through contract-name aliases like guess_the_number. The first build after upgrading deploys every contract again, on every network you build for. Later builds upgrade them as usual. Old aliases are left in your stellar-cli config; remove them with stellar contract alias remove <name>. New aliases are prefixed with the project directory name (e.g. my-app-guess_the_number).

Known limitations

• Two checkouts with the same directory name share an alias prefix. The second one gets the "Not saving alias" warning, and its contracts are still tracked correctly in its own state.json.
• Spanish translations under docs/site/i18n/es still use the old paths and aliases.

Testing

• cargo fmt, cargo clippy --workspace --all-targets --all-features, and the unit tests (239) pass, including new tests for the state file, alias naming, alias ownership, and clean.
• Before rebasing onto 0.0.29, the full integration suite passed 269/269 against local quickstart (protocol 29). New test: checkouts_sharing_a_stellar_config_keep_their_own_contracts, which fails on main because the second checkout reports the first checkout's contract as up to date.
• Manual run against the UI branch with stellar scaffold build:
  • The first build deployed all three contracts and saved ui-* aliases.
  • The second build reported them up to date.
  • contract invoke --id <alias> worked.
  • clean removed the aliases and the state file and kept the keys.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QhmaWLv4yExX8LahP5UtUb

[chadoh]

Goooood shyt.

Only thing I noticed that might be worth changing before merge is the "don't make the json pretty" suggestion below