stellar-agent 0.2.0 → 0.3.0

package/README.md

@@ -10,6 +10,22 @@ npx stellar-agent init
 
 This scaffolds a `_stellar/` directory in your project. From that point, invoke agents directly from your AI assistant (Claude Code, Cursor, Windsurf, etc.).
 
+### Pinning a version
+
+The CLI and the skill catalog ship as one versioned package. To pin a project to a specific version of the agent team:
+
+```bash
+npx stellar-agent@0.2.0 init     # always installs v0.2.0 skills
+```
+
+The chosen version is recorded in `_stellar/_config/manifest.yaml`. Check it any time with:
+
+```bash
+stellar-agent version
+```
+
+If the CLI you're running differs from the skills version recorded in your project, the command warns you and tells you how to re-pin.
+
 ---
 
 ## Agent Team
@@ -137,6 +153,7 @@ These work from any project with `_stellar/` initialized:
 | `stellar-help` | Browse the full skill catalog with next-step recommendations |
 | `stellar-brainstorming` | Facilitated brainstorming for project ideas, architecture, and tokenomics |
 | `stellar-party-mode` | Multi-agent roundtable — all agents in one discussion |
+| `stellar-lean` | Switch the active agent into terse, result-only output mode |
 
 ---
 
@@ -179,12 +196,33 @@ npm run validate:skills
 # Test CLI
 node tools/installer/stellar-cli.js --help
 
+# Run the MCP server locally
+npm run mcp
+
 # Link globally for testing in other projects
 npm link
 # then in another project:
 stellar-agent init
 ```
 
+## Releasing
+
+CI/CD is wired up via GitHub Actions:
+
+- **[`.github/workflows/validate.yml`](.github/workflows/validate.yml)** — runs on every push and PR to `main`: validates all skills, runs the test suite on Node 20.x and 22.x, builds the docs site, and smoke-tests the MCP server.
+- **[`.github/workflows/publish.yml`](.github/workflows/publish.yml)** — runs on tags matching `v*`: re-validates, verifies the tag matches `package.json` version, publishes to npm with provenance, and creates a GitHub release.
+
+**One-time setup**: add an `NPM_TOKEN` secret to the repo (Settings → Secrets and variables → Actions). Use a granular access token scoped to publish only the `stellar-agent` package.
+
+**Releasing a new version**:
+
+```bash
+npm version minor       # 0.2.0 → 0.3.0 (creates commit + git tag v0.3.0)
+git push --follow-tags  # triggers publish.yml
+```
+
+`prepublishOnly` runs `validate:skills && test` automatically on any `npm publish` — local or CI.
+
 ## Requirements
 
 - Node.js >= 20.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stellar-agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AI agent team for Stellar blockchain developers",
   "keywords": [
     "stellar",
@@ -16,13 +16,16 @@
   },
   "files": [
     "tools/installer/",
+    "tools/mcp-server/",
     "src/",
     "package.json",
     "README.md"
   ],
   "scripts": {
     "validate:skills": "node tools/validate-skills.js --strict",
-    "test": "node test/test-installation.js"
+    "test": "node test/test-installation.js",
+    "prepublishOnly": "npm run validate:skills && npm test",
+    "mcp": "node tools/mcp-server/server.js"
   },
   "dependencies": {
     "@clack/core": "1.3.1",

package/src/core-skills/module-help.csv

@@ -3,3 +3,5 @@ Core,_meta,,,,,,,,,false,https://github.com/tolgazorlu/stellar-agent#readme,
 Core,stellar-brainstorming,Brainstorming,BSP,Facilitate interactive brainstorming for Stellar project ideas architecture and tokenomics design.,,,anytime,,,false,{output_folder}/brainstorming,brainstorming session
 Core,stellar-party-mode,Party Mode,PM,Orchestrate multi-agent roundtable discussions with the full Stellar Agent team.,,,anytime,,,false,,
 Core,stellar-help,Stellar Help,SH,Navigate the Stellar Agent skill catalog and get next-step recommendations.,,,anytime,,,false,,
+Core,stellar-lean,Lean Mode,LN,Switch the active agent into terse result-only output — no preamble no summary no fluff.,,,anytime,,,false,,
+Core,stellar-project-context,Project Context,PX,Interview the user once and produce project-context.md that every agent loads as persistent facts.,,,anytime,,,false,{project-root},project-context.md

package/src/core-skills/stellar-lean/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: stellar-lean
+description: 'Switch the active agent into terse, result-only output mode. Suppresses preamble, summary, hedging, and conversational fluff — only the artifact. Use when the user types stellar-lean, /lean, --lean, "be terse", "less talk", "just the code", "result only", or asks for Karpathy-style minimal output.'
+---
+
+# Lean Mode
+
+Output the artifact. Skip everything else.
+
+## On Activation
+
+Acknowledge with one line: `Lean mode on.`
+
+Then, for the rest of the session, follow the rules below.
+
+## Output rules
+
+| Ask | Output |
+|---|---|
+| "Write X" | The code. No preamble. |
+| "Fix the bug" | The diff. No "I found that…". |
+| "Explain X" | ≤ 3 sentences. No headers. |
+| Yes/no | "Yes" or "No" + one clause. |
+| Command-style ask | The command. Copy-pasteable. One line. |
+| "Compare A vs B" | One table. No prose intro. |
+
+## Forbidden phrases
+
+- `Let me…` · `I'll start by…` · `Now let me…` · `First I'll…`
+- `Here's what I did:` · `I've completed…` · `To summarize…`
+- `Let me know if…` · `Hope this helps!` · `Happy to…`
+- `Great question!` · `Of course!` · `Certainly!`
+- Bullet-point recap of code you just wrote
+- Emojis (unless the user used them first)
+- Headers for ≤ 1-paragraph answers
+
+## Forbidden patterns
+
+- **Narrating tool calls.** Don't say "Now I'll read the file." Just read it.
+- **Trailing summaries.** Don't end with "Done. The function now does X." The diff is the summary.
+- **Hedge clauses.** No "It might be worth considering…" → say "Do X." or don't say it.
+- **Pre-emptive caveats.** Add caveats only when they change the answer.
+
+## Code output
+
+```
+<the code>
+```
+
+That's it. No paragraph above. No paragraph below.
+
+If the user wants explanation, they'll ask.
+
+## File edits
+
+Show the diff. Don't restate what changed in prose.
+
+## When the user is wrong
+
+Say so in one sentence. Then give the right answer. Don't apologize for correcting.
+
+## Exit
+
+Stay lean until the user says `stellar-verbose`, `verbose mode`, `explain more`, or `back to normal`. Then drop the constraints.
+
+## Why
+
+LLM output bloats by default. Every "Let me…", every recap, every "Happy to help!" costs tokens the user paid for and attention they can't reclaim. Lean mode trades politeness for signal. Use it when the user is in flow and wants the next artifact, not a conversation.
+
+Modeled on Karpathy's framing: skills should be opinionated execution, not narrated process.

package/src/core-skills/stellar-project-context/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: stellar-project-context
+description: 'Interview the user once and produce a project-context.md that every Stellar Agent loads as persistent_facts. Captures product intent, users, on-chain primitives, deployment targets, and constraints. Use when the user starts a new project, asks "what is project-context.md", any agent detects project-context.md is missing, or the user wants to refresh project context.'
+---
+
+# Project Context Generator
+
+## Purpose
+
+Every Stellar Agent loads `**/project-context.md` as a persistent fact on activation. When that file doesn't exist, agents respond with generic priors instead of project-specific knowledge. This skill produces the file once — durable across sessions, readable by all agents.
+
+## On Activation
+
+Resolve config from `{project-root}/_stellar/stellar/config.yaml` and `{project-root}/_stellar/core/config.yaml`. Capture: `{user_name}`, `{project_name}`, `{network_preference}`, `{primary_language}`.
+
+Check if `{project-root}/project-context.md` already exists.
+
+- If yes → ask: *"Project context exists. Refresh it, or just review what's there?"*
+- If no → start the interview.
+
+## Workflow
+
+### Step 1: The 7-Question Interview
+
+Ask the user 7 questions. Each one has a default — they can say `skip` to accept the default. Conduct as a single block, not one at a time.
+
+```
+1. **One-sentence elevator pitch.** What does this project do?
+   (Default: pulled from {project_name} if descriptive enough.)
+
+2. **Primary user.** Who uses this? Name a persona, not "everyone".
+   (Default: "Stellar developers" if it's a dev tool, else "skip".)
+
+3. **Primary on-chain action.** What's the one transaction the user signs that delivers the core value?
+   (Default: "skip" — but flag that downstream skills work better with this filled in.)
+
+4. **Stellar primitives used.** Pick all that apply: Soroban contracts · Classic payments · Custom assets · Trustlines · Anchors (SEP-24/SEP-31) · SEP-10 auth · AMM pools · Path payments.
+   (Default: infer from {primary_language} — Rust → Soroban; TS → Classic + Soroban via SDK.)
+
+5. **Deployment target(s).** Testnet · Mainnet · Both · Futurenet.
+   (Default: {network_preference}.)
+
+6. **Hard constraints.** Anything the build *cannot* do (regulatory, technical, time, team size)?
+   (Default: "skip" — but useful for agents to know.)
+
+7. **Success in 30 days.** What's the one metric or milestone you'd celebrate?
+   (Default: "skip" — but useful for prioritization.)
+```
+
+Record raw answers. Don't paraphrase yet.
+
+### Step 2: Write the File
+
+Render the answers to `{project-root}/project-context.md`:
+
+```markdown
+# Project Context — {project_name}
+
+> This file is read by every Stellar Agent on activation. Keep it ≤ 200 lines.
+> Last updated: <YYYY-MM-DD>
+
+## Elevator pitch
+
+<one sentence from Q1>
+
+## Primary user
+
+<from Q2>
+
+## Primary on-chain action
+
+<from Q3>
+
+## Stellar stack
+
+- **Primitives:** <comma-separated list from Q4>
+- **Network:** <from Q5>
+- **Primary language:** {primary_language}
+
+## Constraints
+
+<from Q6 — bullets if multiple>
+
+## Success criteria (30-day horizon)
+
+<from Q7>
+
+## Project state
+
+- Phase: <inferred — analysis | planning | architecture | implementation | mentorship>
+- Started: <YYYY-MM-DD>
+- Lead: {user_name}
+
+## Glossary
+
+<Optional. Domain-specific terms that recur in the codebase. Add as the project grows.>
+```
+
+### Step 3: Suggest Where It Goes
+
+By default, save at `{project-root}/project-context.md`. This is the path that matches the glob `**/project-context.md` every agent loads.
+
+If the user has multiple sub-projects in a monorepo, save under each: `{sub-project}/project-context.md`. The glob picks up all of them; agents load whichever is nearest.
+
+### Step 4: Confirm and Wire
+
+Show the rendered file to the user. Ask: *"Save this?"*
+
+If yes:
+- Write the file
+- Confirm path
+- Suggest the user `git add` and commit it (this is durable project state, should be in version control)
+
+### Step 5: Refresh Trigger
+
+`project-context.md` decays. When any of these happens, agents should suggest re-running this skill:
+
+- The hackathon brief locks in a different track or scope
+- The primary on-chain action changes
+- A contract gets deployed to mainnet (state change)
+- A new team member joins
+- The user explicitly says "we pivoted"
+
+Re-running this skill regenerates the file with a new `Last updated` date. Old content can be preserved in a `## History` section if the user wants.
+
+## Anti-patterns to flag
+
+- **Long, prose-heavy context files.** Keep it ≤ 200 lines. Agents read this every time — verbose = expensive.
+- **Capturing implementation details.** That's what `{implementation_artifacts}` is for. This file is intent, not implementation.
+- **Skipping Q3 (primary on-chain action).** This is the single most useful field for Sol, Nova, and Pera. Push back on `skip` here.
+- **Filling in defaults blindly.** If the user says `skip` to all 7, write a file with `[unknown]` placeholders and tell them to refresh later.
+
+## Why this matters
+
+Every agent's `persistent_facts` includes:
+```toml
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+```
+
+Without this file, agents fall back to generic Stellar priors — they don't know your network, your users, your scope. A 100-line context file shifts every subsequent agent response from generic to project-specific. Cheap to write once, compounds across every interaction.
+
+## Output
+
+`{project-root}/project-context.md` — single file, version-controlled, loaded by every agent.
+
+## Next Steps
+
+- `@stellar-agent-pm` (Kai) — turn the elevator pitch into a project brief (PB)
+- `@stellar-agent-architect` (Nova) — architecture from the primary on-chain action
+- `@stellar-agent-mentor` (Pera) — if there's a deadline, hackathon arc starts here

package/src/stellar-skills/1-analysis/stellar-agent-analyst/customize.toml

@@ -39,3 +39,8 @@ skill = "stellar-analytics"
 code = "DR"
 description = "Research Stellar domain — protocol specifics, regulatory landscape, use cases"
 skill = "stellar-domain-research"
+
+[[agent.menu]]
+code = "KA"
+description = "Known Assets Registry — canonical issuer addresses for USDC, EURC, AQUA, yXLM with verification commands"
+skill = "stellar-known-assets"

package/src/stellar-skills/1-analysis/stellar-known-assets/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: stellar-known-assets
+description: 'Look up canonical Stellar asset issuer addresses (USDC, EURC, AQUA, yXLM, etc.) with provenance and verification commands. Prevents LLM hallucination of issuer addresses. Use when the user references a Stellar asset by code (USDC, EURC, AQUA), needs to create a trustline, builds a path payment, or any task that requires a verified issuer address.'
+---
+
+# Known Assets Registry
+
+## Purpose
+
+Stop the LLM from inventing Stellar asset issuer addresses. Every well-known Stellar asset (USDC, EURC, AQUA, yXLM, etc.) has a specific 56-character issuer address — using the wrong one silently breaks trustlines and burns user funds.
+
+## Hard rule
+
+**Never write a Stellar issuer address from memory.** Always either:
+1. Look it up in the registry below.
+2. Verify with one of the verification commands.
+3. Refuse to fill it in and ask the user to provide it.
+
+If a value is not in this file and not provided by the user, output a placeholder like `<USDC_ISSUER>` and tell the user to fill it in — do not guess.
+
+## Mainnet (public network)
+
+> Last verified: 2025-06-01. Always verify against [stellar.expert/explorer/public/assets](https://stellar.expert/explorer/public/assets) before mainnet deployment.
+
+| Code | Issuer | Custodian | Notes |
+|---|---|---|---|
+| `USDC` | `GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN` | Circle | Native USDC on Stellar. Source: [circle.com/multi-chain-usdc/stellar](https://www.circle.com/multi-chain-usdc/stellar) |
+| `EURC` | `GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2` | Circle | Native EURC. Source: [circle.com/multi-chain-eurc/stellar](https://www.circle.com/multi-chain-eurc/stellar) |
+| `AQUA` | `GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA` | Aquarius | Governance token for Aquarius DEX. **Verify before use.** |
+| `yXLM` | `GARDNV3Q7YGT4AKSDF25LT32YSCCW4EV22Y2TV3I2PU2MMXJTEDL5T55` | Ultra Stellar | Yield-bearing XLM. **Verify before use.** |
+| `XLM` | *(native)* | Stellar protocol | Native asset — no issuer. Use `Asset.native()` in the SDK. |
+
+**For any asset not listed above**: tell the user "I don't have a verified issuer for `<CODE>`. Look it up at https://stellar.expert/explorer/public/assets and paste the issuer."
+
+## Testnet
+
+> Testnet issuers are different from mainnet. Never copy a mainnet issuer to testnet.
+
+| Code | Issuer | Notes |
+|---|---|---|
+| `USDC` | `GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH37Y2QJU2` | Circle testnet USDC. Source: [circle.com/multi-chain-usdc/stellar](https://www.circle.com/multi-chain-usdc/stellar) (toggle to testnet) |
+| `XLM` | *(native)* | Same on every network. Use `Asset.native()`. |
+
+For testnet custom assets, the user typically creates their own issuer with `stellar keys generate`. Look in `{implementation_artifacts}/asset-config.md` for project-specific issuers.
+
+## Futurenet
+
+Futurenet is reset periodically — there are no stable canonical issuers. Always create a fresh issuer or ask the user.
+
+## Verification commands
+
+Before using any address from this file in a transaction that moves real funds, run one of these:
+
+### Verify against stellar.expert
+
+```bash
+# Replace ISSUER with the address from the table
+curl -s "https://api.stellar.expert/explorer/public/asset/USDC-ISSUER" | jq '.code, .issuer, .domain'
+
+# Expected output for USDC mainnet:
+# "USDC"
+# "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
+# "centre.io"
+```
+
+### Verify via SEP-1 (`stellar.toml`)
+
+For any asset, the issuer's `stellar.toml` is the canonical source. Find the domain via `home_domain` on the issuer account:
+
+```bash
+stellar account inspect <ISSUER_ADDRESS> --network public | grep home_domain
+
+# Then fetch the toml:
+curl -s "https://${HOME_DOMAIN}/.well-known/stellar.toml" | grep -A 3 "CURRENCIES"
+```
+
+### Verify via Horizon
+
+```bash
+# Check the issuer account exists and is configured as an issuer
+curl -s "https://horizon.stellar.org/accounts/<ISSUER>" | jq '.flags, .home_domain'
+
+# auth_required = true means it's an issuer that gates trustlines
+# home_domain links to the stellar.toml
+```
+
+## When to refuse to answer
+
+If the user asks you to write code that includes a custom-asset issuer and:
+
+1. The asset is **not in this file**, AND
+2. The user has **not provided** the issuer in conversation or in `{implementation_artifacts}/asset-config.md`
+
+→ Refuse to fill in the issuer. Output a placeholder and request the address explicitly:
+
+```
+const USDC = new Asset(
+  'USDC',
+  '<FILL_IN_USDC_ISSUER>' // Verify at https://stellar.expert/explorer/public/assets
+);
+```
+
+Tell the user: *"I don't have a verified issuer for `<CODE>` on this network. Paste the issuer address from stellar.expert and I'll wire it in."*
+
+## How to extend this file
+
+When a maintainer wants to add a new asset:
+
+1. Verify the issuer via `stellar.expert` AND `stellar.toml` AND Horizon.
+2. Add a row to the table with the **source link** (not just the address).
+3. Bump the "Last verified" date at the top of the section.
+4. If the asset is well-known (top 20 by holders), no further review needed. If niche, also note who uses it.
+
+## Output
+
+This skill is reference-only — no artifacts written. It exists to be loaded into context when other skills need an issuer address.
+
+## Used by
+
+- `stellar-create-transaction` (Sol `TX`) — path payments, asset transfers
+- `stellar-create-asset` (Sol `CA`) — when comparing to existing issuers
+- `stellar-setup-trustline` (Sol `TL`) — never create a trustline to an unverified issuer
+- `stellar-liquidity-pool` (Sol `LP`) — both pool tokens must be verified
+- `stellar-market-research` (Aria `MR`) — market caps by asset
+- `stellar-tokenomics-analysis` (Aria `TA`) — comparable asset designs

package/src/stellar-skills/4-implementation/stellar-agent-devops/customize.toml

@@ -20,6 +20,11 @@ principles = [
   "stellar doctor before asking the community.",
 ]
 
+[[agent.menu]]
+code = "SD"
+description = "Stellar Doctor — diagnose toolchain, network, wallet, contract state, and project context"
+skill = "stellar-doctor"
+
 [[agent.menu]]
 code = "SE"
 description = "Set up local Stellar development environment with Docker quickstart bundle"

package/src/stellar-skills/4-implementation/stellar-doctor/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: stellar-doctor
+description: 'Diagnose the local Stellar development environment — toolchain, network reachability, wallet state, contract WASM target, Freighter, account funding. Use when the user reports "it does not work", before any deployment, when something is failing without a clear error, or as a sanity check after onboarding a new dev.'
+---
+
+# Stellar Doctor
+
+## Purpose
+
+One command runs every "is my environment broken?" check that costs hackathon teams hours of debugging. Same energy as `flutter doctor` or `rustup doctor`. Output is a pass/fail table with copy-paste fixes for each failure.
+
+## On Activation
+
+Load `{network_preference}` and `{primary_language}` from config. The checks adapt — Rust users get Rust toolchain checks, TypeScript users get Node/SDK checks, full-stack users get both.
+
+## Workflow
+
+Run the checks below in order. For each, output:
+
+```
+✓ <check name>          → <observed value>
+✗ <check name>          → <error> · fix: <one-line fix command>
+```
+
+Group results into sections. Show the section summary at the bottom.
+
+### Section A — Toolchain (always run)
+
+```bash
+# 1. Stellar CLI present
+stellar --version
+#  expected: stellar 22.0.0+ (or current — bump as the project moves)
+
+# 2. Node.js present and >= 20.12.0
+node --version
+
+# 3. Network reachability
+curl -s -o /dev/null -w "%{http_code}" https://horizon-testnet.stellar.org
+#  expected: 200
+```
+
+**Failures:**
+| Symptom | Fix |
+|---|---|
+| `stellar: command not found` | macOS: `brew install stellar-cli` · Linux/Win: see [Stellar CLI install](https://developers.stellar.org/docs/tools/developer-tools/cli/install-cli) |
+| Node version < 20 | `nvm install 22 && nvm use 22` |
+| Horizon unreachable (non-200) | Check firewall / VPN / corporate proxy |
+
+### Section B — Rust toolchain (run if `primary_language` is `rust` or `fullstack`)
+
+```bash
+# 1. cargo present
+cargo --version
+
+# 2. rustup default toolchain
+rustup show active-toolchain
+
+# 3. wasm32 target installed
+rustup target list --installed | grep wasm32-unknown-unknown
+
+# 4. soroban-sdk version compatible (read from any contract Cargo.toml)
+grep -r 'soroban-sdk' --include=Cargo.toml | head -3
+```
+
+**Failures:**
+| Symptom | Fix |
+|---|---|
+| `cargo: command not found` | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
+| `wasm32-unknown-unknown` missing | `rustup target add wasm32-unknown-unknown` |
+| `soroban-sdk` version < 22 | Bump in `Cargo.toml` and `cargo update` |
+
+### Section C — TypeScript / SDK (run if `primary_language` is `typescript` or `fullstack`)
+
+```bash
+# 1. Stellar SDK installed in project
+node -e "console.log(require('@stellar/stellar-sdk/package.json').version)" 2>/dev/null
+
+# 2. Network passphrase in code matches network_preference
+grep -r "Networks\." --include="*.ts" --include="*.tsx" --include="*.js" src/ 2>/dev/null | head -3
+```
+
+**Failures:**
+| Symptom | Fix |
+|---|---|
+| `@stellar/stellar-sdk` not found | `npm install @stellar/stellar-sdk` |
+| `Networks.PUBLIC` but `network_preference=testnet` | Switch code to `Networks.TESTNET` or update config |
+
+### Section D — Wallet & network state
+
+```bash
+# 1. Wallet keypair configured
+stellar keys ls
+#  expected: at least one key, ideally one matching project name
+
+# 2. Active wallet account exists on chosen network
+DEFAULT_KEY=$(stellar keys ls 2>/dev/null | head -1)
+ADDR=$(stellar keys address "$DEFAULT_KEY" 2>/dev/null)
+curl -s "https://horizon-testnet.stellar.org/accounts/$ADDR" | jq -r '.account_id // "not-funded"'
+
+# 3. Account funded — at least 5 XLM
+curl -s "https://horizon-testnet.stellar.org/accounts/$ADDR" | jq -r '.balances[] | select(.asset_type=="native") | .balance'
+```
+
+**Failures:**
+| Symptom | Fix |
+|---|---|
+| No keys configured | `stellar keys generate <name> --network testnet` |
+| `not-funded` on testnet | `stellar keys fund <name> --network testnet` |
+| Balance < 5 XLM | Same fix — friendbot will top up |
+| `not-funded` on mainnet | Real XLM required — transfer from exchange |
+
+### Section E — Freighter (only if frontend phase)
+
+Open the dev server, then run in browser console:
+
+```js
+// Freighter installed?
+window.freighter
+//   expected: object with isConnected, getAddress, signTransaction
+
+// Active network
+window.freighter.getNetworkDetails()
+//   expected: matches network_preference
+```
+
+**Failures:**
+| Symptom | Fix |
+|---|---|
+| `window.freighter` undefined | Install [Freighter extension](https://freighter.app) |
+| Network mismatch | Click Freighter icon → Settings → Network → switch |
+| `User declined access` | Disconnect site, retry connect flow |
+
+### Section F — Contract state (only if a contract is deployed)
+
+If `{implementation_artifacts}/deployed-contracts.md` exists, read each contract ID and verify:
+
+```bash
+# Contract reachable on network
+stellar contract invoke --id <CONTRACT_ID> --network testnet -- <view_function>
+
+# Storage TTL still valid
+stellar contract read --id <CONTRACT_ID> --network testnet --key <STORAGE_KEY>
+```
+
+**Failures:**
+| Symptom | Fix |
+|---|---|
+| `Contract not found` | Redeploy: `stellar contract deploy ...` |
+| `KeyExpired` / `EntryExpired` | `stellar contract extend --id <ID> --ledgers-to-extend 535679` |
+
+### Section G — Project context (sanity)
+
+```bash
+# project-context.md exists at any level
+find . -maxdepth 3 -name 'project-context.md' 2>/dev/null
+
+# _stellar/_config/manifest.yaml matches CLI version
+stellar-agent version
+```
+
+**Failures:**
+| Symptom | Fix |
+|---|---|
+| No `project-context.md` | Run `stellar-project-context` skill |
+| CLI version ≠ skills version | Run `npx stellar-agent init` (Update) or pin: `npx stellar-agent@<version> ...` |
+
+## Summary Output
+
+After all sections, output:
+
+```
+═══════════════════════════════════════════
+Stellar Doctor — <YYYY-MM-DD HH:MM>
+═══════════════════════════════════════════
+  Toolchain         <pass | N issues>
+  Rust              <pass | N issues | skipped>
+  TypeScript / SDK  <pass | N issues | skipped>
+  Wallet & network  <pass | N issues>
+  Freighter         <pass | N issues | skipped>
+  Contract state    <pass | N issues | skipped>
+  Project context   <pass | N issues>
+───────────────────────────────────────────
+  Critical: <N>     ← must fix before building
+  Warnings: <N>     ← will bite eventually
+═══════════════════════════════════════════
+```
+
+If `Critical: 0`, output:
+> "Environment is clean. You're clear to build."
+
+If `Critical > 0`, list the top 3 critical issues with their fix commands. Refuse to recommend any deployment skill (`DC`, `TX`, `TL`) until critical issues are resolved.
+
+## Anti-patterns to flag
+
+- **Skipping the doctor before a hackathon demo.** 80% of demo failures are environment problems doctor would have caught.
+- **Running doctor once, never again.** Run it after every machine reboot, network change, or `npm install`.
+- **Ignoring warnings.** Warnings become criticals at the worst possible time (mid-demo).
+
+## Output
+
+This skill is read-only — produces no artifacts. Output is the diagnostic report.
+
+## Next Steps
+
+- **All green** → start building. Sol's `IC` (Init Contract) or Lyra's `NS` (Next.js Setup) is the next step.
+- **Critical issues** → fix them, re-run doctor.
+- **Warnings only** → safe to proceed but schedule fixes before mainnet deployment.