Feat/scaffold config v2 docs

CLAUDE.md

@@ -65,7 +65,8 @@ Clippy and warning flags are configured in `.cargo/config.toml` `rustflags` and
 `init` → `build` → `generate` → `watch`
 - `init` — scaffolds a new project; fetches the frontend template from `stellar-scaffold/ui` via degit
 - `upgrade` — converts an existing Soroban workspace into a full scaffold project
-- `build` — builds contracts and generates TypeScript clients based on `environments.toml`
+- `build` — builds contracts and generates TypeScript clients based on `scaffold.yml` (version 2: networks, accounts, contracts); version 1 projects still fall back to `environments.toml`
+- `config check` / `config show` — validate `scaffold.yml` and print the resolved config for one network
 - `generate contract` — adds a new contract to an existing project
 - `watch` — rebuilds on changes
 

README.md

@@ -105,21 +105,19 @@ After scaffolding a project, your folder structure will look like this:
 ```
 my-project/
 ├── contracts/            # Rust smart contracts (compiled to WASM)
-├── packages/             # Auto-generated TypeScript contract clients
-├── src/                  # React frontend code
-│   ├── components/       # Reusable UI pieces
-│   ├── contracts/        # Contract interaction logic
-│   ├── App.tsx           # Main app component
-│   └── main.tsx          # Entry point
-├── environments.toml     # Configuration per environment (dev/test/prod)
+├── app/                  # Your frontend
+│   └── src/              # Components, pages, hooks, entry point
+├── app-lib/              # Utility code, ready to use from your app
+│   └── clients/          # Generated contract clients — regenerated, don't edit
+├── scaffold.yml          # Networks, accounts, and contracts
 ├── .env                  # Local environment variables
-├── package.json          # Frontend packages
+├── package.json          # npm workspace root
 ├── target/               # Build outputs
 ```
 
 This template provides a ready-to-use frontend application with example smart contracts and their TypeScript clients. You can use these as reference while building your own contracts and UI. The frontend is set up with `Vite`, `React`, and includes basic components for interacting with the contracts.
 
-See the [CLI Documentation](https://scaffoldstellar.com/docs/cli) for detailed command information and the [Environments Guide](https://scaffoldstellar.com/docs/environments) for configuration details.
+See the [CLI Documentation](https://scaffoldstellar.com/docs/cli) for detailed command information and the [Configuration Guide](https://scaffoldstellar.com/docs/configuration) for configuration details.
 
 ---
 
@@ -150,15 +148,13 @@ Scaffold Stellar's build pipeline supports extensions by calling binaries on you
 
 The built-in **[Scaffold Reporter](./crates/stellar-scaffold-reporter/)** extension is included in every new project. It logs compile times, WASM sizes, deploy durations, and total build cycle time directly to your console.
 
-Register extensions in `environments.toml`:
+Register extensions in `scaffold.yml`:
 
-```toml
-[development]
-extensions = ["reporter"]
-
-# Optional per-extension config:
-[development.ext.reporter]
-warn_size_kb = 128
+```yaml
+extensions:
+  reporter:
+    # Optional per-extension config
+    warn_size_kb: 128
 ```
 
 See the [Extensions Guide](https://scaffoldstellar.com/docs/extensions) to learn how the hook system works and how to build your own extension.
@@ -207,7 +203,7 @@ After installation, you can interact with the contract using `stellar-cli`:
 stellar contract invoke --id my-contract-instance -- --help
 ```
 
-> You can deploy to testnet or mainnet depending on your `.env` and `environments.toml`.
+> You can deploy to testnet or mainnet depending on the network you select in `.env` (`STELLAR_NETWORK`) and `scaffold.yml`.
 
 ---
 ## Concept: What Is the Contract Registry?
@@ -239,8 +235,9 @@ Your repo contains the following key folders:
 
 ## Documentation
 * [CLI Commands](https://scaffoldstellar.com/docs/cli)
-* [Environment Setup](https://scaffoldstellar.com/docs/environments)
+* [Configuration](https://scaffoldstellar.com/docs/configuration)
 * [Registry Guide](https://scaffoldstellar.com/docs/registry)
+* [Agent skill](./skills/stellar-scaffold/SKILL.md): teaches AI coding agents to create and work in Scaffold projects. Point your agent at `https://raw.githubusercontent.com/stellar-scaffold/cli/main/skills/stellar-scaffold/SKILL.md`
 
 ---
 ## Additional Developer Resources

crates/stellar-scaffold-cli/README.md

@@ -4,17 +4,17 @@ CLI toolkit for Stellar smart contract development, providing project scaffoldin
 
 Stellar Scaffold CLI comes with four main commands:
 
-* `stellar scaffold init` - Creates a new Stellar smart contract project with best practices and configurations in place, including an `environments.toml` file for managing network settings, accounts, and contracts across different environments.
+* `stellar scaffold init` - Creates a new Stellar smart contract project with best practices and configurations in place, including a `scaffold.yml` file for managing networks, accounts, and contracts.
 
 * `stellar scaffold upgrade` - Transforms an existing Soroban workspace into a full scaffold project by adding frontend components, environment configurations, and project structure. Preserves existing contracts while adding the complete development toolkit.
 
 * `stellar scaffold build` - Manages two key build processes:
   * Build smart contracts with metadata and handle dependencies
   * Generate TypeScript client packages for frontend integration
 
-  The build process respects environment configurations from `environments.toml` and handles contract deployment states based on the current environment (controlled via `STELLAR_SCAFFOLD_ENV`).
+  The build process follows the configuration in `scaffold.yml` and handles contract deployment states for the selected network (chosen with `--network` or `STELLAR_NETWORK`).
 
-* `stellar scaffold watch` - Development mode that monitors contract source files and `environments.toml` for changes, automatically rebuilding as needed. Defaults to using the `development` environment.
+* `stellar scaffold watch` - Development mode that monitors contract source files and `scaffold.yml` for changes, automatically rebuilding as needed. Uses the same network selection as `build`, falling back to `local`.
 
 ## Getting Started
 
@@ -52,7 +52,7 @@ stellar scaffold upgrade
 
 This will:
 - Add the frontend application and development tools
-- Generate `environments.toml` with your existing contracts
+- Generate `environments.toml` (the legacy config format) with your existing contracts
 - Set up environment files and configurations
 - Preserve all your existing contract code and structure
 
@@ -66,40 +66,49 @@ cp .env.example .env
 stellar scaffold watch --build-clients
 ```
 
-## Environment Configuration
-
-Projects use `environments.toml` to define network settings, accounts, and contract configurations for different environments. Example:
-```toml
-[development]
-network = { 
-    name = "local",
-    run_locally = true
-}
-accounts = ["account1", "account2"]
-
-[staging]
-network = { 
-    name = "testnet"
-}
-
-[production]
-network = { 
-    name = "mainnet"
-}
+## Configuration
+
+Projects use `scaffold.yml` to define networks, accounts, and the contracts to deploy or connect to on each network. Example:
+```yaml
+version: 2
+
+networks:
+  local:
+    accounts: [me]
+  testnet:
+    accounts: [testnet-user]
+    allow-deploy: true
+
+contracts:
+  guess-the-number:
+    type: workspace
+    source: guess-the-number
+    args:
+      admin: ${account.me}
+    after-deploy: [reset]
+    networks:
+      local:
+      testnet:
+        args:
+          admin: ${account.testnet-user}
 ```
 
+Validate it with `stellar scaffold config check`, and print the resolved config for one network with `stellar scaffold config show --network <name>`. See the [Configuration Guide](https://scaffoldstellar.com/docs/configuration) for every option.
+
+Projects created before version 2 keep this configuration in `environments.toml`, selected with `STELLAR_SCAFFOLD_ENV`. `build` and `watch` still read it.
+
 ## Build Process Details
 
 `stellar scaffold build` and `stellar scaffold watch` manage:
 
-1. Smart contract compilation and deployment based on environment
+1. Smart contract compilation and deployment to the selected network
 2. TypeScript client package generation for frontend integration
 3. Network and account management (create/fund accounts in development)
-4. Contract initialization via constructor args and post-deploy scripts
+4. Contract initialization via constructor `args` and `after-deploy` calls
 
 The build process ensures:
 - Correct dependency resolution and build order
-- Environment-specific contract deployments
+- Network-specific contract deployments
 - TypeScript client generation for frontend integration
 - Contract state verification and updates
 
@@ -120,14 +129,12 @@ repository = "https://github.com/your-org/your-project"
 
 ## Environment Variables
 
-- `STELLAR_SCAFFOLD_ENV`: Sets current environment (development/staging/production)
-- `STELLAR_ACCOUNT`: Default account for transactions
-- `STELLAR_RPC_URL`: RPC endpoint URL
-- `STELLAR_NETWORK_PASSPHRASE`: Network passphrase
+- `STELLAR_NETWORK`: Network from `scaffold.yml` to build for, same as `--network`
+- `STELLAR_SCAFFOLD_ENV`: Environment to build for in projects still on `environments.toml` (development/testing/staging/production). Ignored with a version 2 `scaffold.yml`
 
 ## For More Information
 
 See the full documentation:
 - [CLI Commands Guide](https://scaffoldstellar.com/docs/cli)
-- [Environment Configuration](https://scaffoldstellar.com/docs/environments)
+- [Configuration](https://scaffoldstellar.com/docs/configuration)
 - [Deployment Guide](https://scaffoldstellar.com/docs/deploy)

crates/stellar-scaffold-ext-types/README.md

@@ -72,7 +72,7 @@ ProjectContext  ──  pre-dev, post-dev  (aggregates all contracts)
 
 #### `config` field
 
-Every context type carries the extension's own configuration from `environments.toml`. Where it lives depends on the hook:
+Every context type carries the extension's own configuration from the `extensions:` section of `scaffold.yml` (or from `environments.toml` in projects that still use it). Where it lives depends on the hook:
 
 | Hook group | Access path |
 |---|---|
@@ -81,7 +81,7 @@ Every context type carries the extension's own configuration from `environments.
 | pre/post-codegen | `ctx.deploy.compile.config` |
 | pre/post-dev | `ctx.config` |
 
-The field is typed `Option<serde_json::Value>`. When no config is provided it is `None` and is absent from the JSON entirely (`#[serde(skip_serializing_if = "Option::is_none")]`). Scaffold always injects the real value from `environments.toml` when config is present.
+The field is typed `Option<serde_json::Value>`. When no config is provided it is `None` and is absent from the JSON entirely (`#[serde(skip_serializing_if = "Option::is_none")]`). Scaffold always injects the real value from the project's config when it is present.
 
 ---
 

crates/stellar-scaffold-reporter/README.md

@@ -22,11 +22,11 @@ To add it to an existing project, install the binary with [Cargo](https://doc.ru
 cargo install stellar-scaffold-reporter
 ```
 
-Then register it in your `environments.toml`:
+Then register it in your `scaffold.yml`:
 
-```toml
-[development]
-extensions = ["reporter"]
+```yaml
+extensions:
+  reporter:
 ```
 
 ## 🏃 Running

docs/site/docs/agent-skills.md

@@ -0,0 +1,70 @@
+---
+sidebar_label: AI Agent Skills
+---
+
+# AI Agent Skills
+
+Stellar Scaffold publishes an [Agent Skill](https://agentskills.io): a folder of Markdown instructions that teaches AI coding agents (Claude Code, Codex, Cursor, and others) how to create and work in Scaffold projects. With it loaded, an agent knows the `stellar scaffold` commands, writes valid `scaffold.yml`, calls your contracts through the generated clients instead of hardcoding IDs, and avoids the common mistakes that come from outdated examples online.
+
+## What's in the skill
+
+The skill lives in the CLI repository at [`skills/stellar-scaffold/`](https://github.com/stellar-scaffold/cli/tree/main/skills/stellar-scaffold), versioned alongside the CLI it describes.
+
+| File | Covers |
+| --- | --- |
+| `SKILL.md` | Setup, `init` and `upgrade`, project layout, the dev loop, `scaffold.yml` essentials, calling contracts from your app, adding contracts, testnet and mainnet, diagnostics, and common pitfalls |
+| `references/cli.md` | Every `stellar scaffold` command and flag |
+| `references/config.md` | The full `scaffold.yml` schema, `.env`, contract metadata, and migrating from `environments.toml` |
+| `references/frontend.md` | Generated clients, `@stellar-scaffold/app-lib`, wallets, and keeping the app and CLI on the same network |
+
+Agents read `SKILL.md` first and open a reference file only when a task needs it, so the skill costs little context until it's used.
+
+## Using the skill
+
+### Point your agent at it
+
+Any agent that can fetch a URL can use the skill directly. Start your session with:
+
+```text
+Read https://raw.githubusercontent.com/stellar-scaffold/cli/main/skills/stellar-scaffold/SKILL.md
+and follow it while you work on this project.
+```
+
+The agent follows the relative links in `SKILL.md` to the reference files when it needs them. This always gets the latest version, and needs no setup.
+
+### Install it for Claude Code
+
+Claude Code loads skills automatically from `~/.claude/skills/` (all your projects) or `.claude/skills/` (one project), and decides when to use them from the skill's description. Copy the skill folder into one of those:
+
+```bash
+git clone --depth 1 https://github.com/stellar-scaffold/cli.git /tmp/stellar-scaffold-cli
+mkdir -p ~/.claude/skills
+cp -R /tmp/stellar-scaffold-cli/skills/stellar-scaffold ~/.claude/skills/
+```
+
+Then ask for Scaffold work in plain language, such as "create a Scaffold project with a Svelte frontend" or "add a token contract and call it from the app", and Claude Code loads the skill when it's relevant.
+
+### Other agents
+
+Agents that support the Agent Skills format load them from their own skills directory. Copy the same `skills/stellar-scaffold` folder there; check your agent's documentation for the location. For agents without skill support, use the URL prompt above, or add it to your project's `AGENTS.md` so every session starts with it:
+
+```markdown
+## Stellar Scaffold
+
+This project uses Stellar Scaffold. Before changing contracts, `scaffold.yml`, or contract calls in the app, read https://raw.githubusercontent.com/stellar-scaffold/cli/main/skills/stellar-scaffold/SKILL.md
+```
+
+### Keeping it current
+
+The skill tracks the CLI's `main` branch, which can be slightly ahead of the latest release. An installed copy doesn't update itself, so re-copy it when you upgrade `stellar-scaffold-cli`, or use the URL approach to always read the current version.
+
+## Related skills
+
+The Scaffold skill covers Scaffold itself and links out for neighboring tasks:
+
+- **Stellar Registry**: publishing and deploying contracts by name, and calling registry contracts from Rust. Skill: https://raw.githubusercontent.com/stellar-registry/cli/main/skills/stellar-registry/SKILL.md
+- **Stellar development in general**: [stellar/stellar-dev-skill](https://github.com/stellar/stellar-dev-skill) indexes skills for the wider Stellar ecosystem, including Soroban, the SDKs, and wallets.
+
+## Feedback
+
+If an agent gets something wrong while using the skill, [open an issue](https://github.com/stellar-scaffold/cli/issues) with the prompt and what it did. Fixes reach the URL as soon as they merge, and installed copies the next time you re-copy the folder.