docs: beginner onboarding + fix newcomer CLI footguns

GETTING-STARTED.md

@@ -0,0 +1,192 @@
+# Getting Started (for first-timers)
+
+Never built a blockchain or Node.js app before? Start here. This guide assumes
+no prior experience and explains every term the first time it appears. Once
+you've done this once, the [SDK README](sdk/README.md) and
+[main README](README.md) will make sense.
+
+## What this is, in plain words
+
+LightChain AI is a network where you send a text prompt to an AI model and get
+an answer back, like calling any hosted AI API, except:
+
+- It runs on a blockchain (a shared, decentralized ledger), so no single company
+  owns it.
+- Your prompt is encrypted end-to-end, so the network sees only scrambled bytes,
+  never your text.
+- You pay per request from your own wallet instead of a monthly bill.
+
+This repo (`lightnode`) is a community toolkit that makes that easy:
+`lightnode-sdk` (a code library plus a `lightnode` command) and
+`create-lightnode-app` (a project generator).
+
+## The words you need to know
+
+| Word | What it means here |
+|---|---|
+| Wallet | A secret number (your "private key") that signs and pays for requests. Its public "address" is where you receive funds. |
+| Private key | The secret half of the wallet. Looks like `0x` followed by 64 characters. Anyone who has it controls the wallet, so never share it. |
+| Gas | The small fee every blockchain action costs. On LightChain it's paid in LCAI. |
+| LCAI | LightChain's coin. Free on testnet, real money on mainnet. |
+| Testnet | A free practice copy of the network. Use this while learning. |
+| Mainnet | The real network. Costs real LCAI. Don't use it until you're confident. |
+
+While learning, always use testnet. It's free.
+
+## One-time setup (about 5 minutes)
+
+### 1. Install Node.js
+
+You need Node.js 18 or newer. Check what you have:
+
+```bash
+node --version
+```
+
+If that errors or shows a version below 18, install the latest LTS from
+<https://nodejs.org>. `npm` (the package manager) comes bundled with it.
+
+### 2. Make a wallet
+
+```bash
+npx lightnode wallet new
+```
+
+This prints two things:
+
+```
+PRIVATE_KEY=0x... (64 hex characters)        your secret
+# address: 0x...                             your public address
+```
+
+Copy both somewhere safe. This key is for testnet practice only. Never put real
+money on a key you generated and pasted into a terminal.
+
+### 3. Get free testnet funds
+
+Go to <https://lightfaucet.ai>, paste your address (the `0x...` from the
+`# address:` line, not the private key), and request LCAI. You get about 2 LCAI
+per day, which is plenty for many test calls.
+
+### 4. Check it arrived
+
+```bash
+PRIVATE_KEY=0x...your-key... npx lightnode wallet balance --net testnet
+```
+
+You should see a balance above 0 LCAI. Setup is done.
+
+## Your first AI call (no project needed)
+
+The fastest possible test is one command, straight from the terminal:
+
+```bash
+PRIVATE_KEY=0x...your-key... npx lightnode chat "Write a one-line fun fact about the ocean." --net testnet
+```
+
+It signs a request, runs it on testnet, and streams the answer back. If you see
+text appear, everything works.
+
+What just happened: the CLI created an on-chain session, submitted your prompt as
+a transaction, and decrypted the worker's reply locally. The fees came out of
+your free testnet LCAI.
+
+## Two ways to build (don't mix them up)
+
+This is the most common source of confusion for new users, so read it carefully.
+There are two separate tools, for two different situations. Pick one.
+
+### Tool A: `create-lightnode-app` (start a brand-new project)
+
+Use this when you have no project yet and want a complete one generated for you
+in a new folder.
+
+```bash
+npm create lightnode-app my-app
+# answer the prompts: choose a template, choose testnet
+```
+
+This creates a new folder called `my-app/` with everything inside it. You must
+go into it before running anything:
+
+```bash
+cd my-app                # the step that's easy to forget
+cp .env.example .env     # then paste your PRIVATE_KEY into .env, keep NETWORK=testnet
+npm install
+npm run dev              # (nextjs template) then open http://localhost:3000
+#   or: npm start "your prompt"   (node template)
+```
+
+If you see `npm error Missing script: "dev"`, you ran it in the wrong folder. The
+commands only work inside `my-app/`. Run `cd my-app` first.
+
+### Tool B: `lightnode add` (bolt onto a project you already have)
+
+Use this when you already have a folder or project and want to drop AI files into
+it. These commands write files into your current folder. They do not create a new
+one.
+
+```bash
+npx lightnode add inference                  # a basic prompt-to-answer file
+npx lightnode add nft-mint-with-inference     # generate NFT metadata with AI
+```
+
+After it runs, follow its printed steps (install, set up `.env`, then run with
+`npx tsx <file>.ts`).
+
+| | Tool A: `create-lightnode-app` | Tool B: `lightnode add` |
+|---|---|---|
+| When | Starting fresh | Adding to an existing folder |
+| Creates a new folder? | Yes (`my-app/`) | No (writes into current folder) |
+| You must `cd` after? | Yes | No |
+| Run with | `npm run dev` / `npm start` | `npx tsx <file>.ts` |
+
+Running both in the same folder (as the README's NFT example shows) is what
+creates a confusing mix of loose files and a sub-project. For learning, use just
+one.
+
+## The `.env` file (where your secret lives)
+
+Both tools expect a file named `.env` holding your key. It is git-ignored so it
+never gets committed. A typical `.env`:
+
+```
+PRIVATE_KEY=0x...your-testnet-key...
+NETWORK=testnet
+MODEL=llama3-8b
+```
+
+You create it by copying the template the tool generated:
+
+```bash
+cp .env.example .env
+```
+
+Then open `.env` in your editor and paste your real key over the placeholder.
+The placeholder `0x000...000` in `.env.example` is fake and will not work. You
+must replace it with your real funded key.
+
+## When something breaks
+
+| Message you see | What it means | Fix |
+|---|---|---|
+| `npm error Missing script: "dev"` | You're in the wrong folder | `cd` into the project folder first |
+| `command not found: tsx` | The script runner isn't available | Use `npx tsx <file>.ts` (the `npx` matters) |
+| `set PRIVATE_KEY in .env` / `set PRIVATE_KEY=0x...` | No real key configured | Put your key in `.env` (or pass `--key 0x...`) |
+| `under 0.05 LCAI - too low` | Wallet has no funds | Fund your address at <https://lightfaucet.ai> |
+| `workers stalled` / `worker stalled` | A network worker didn't answer | Run it again (fees are refunded) |
+| `auth ... failed` / `502` | Couldn't reach the network | Check your internet and retry |
+
+## Where to go next
+
+- [sdk/README.md](sdk/README.md): every SDK function and CLI command (the full
+  reference). Has a 5-line "hello world".
+- [create-lightnode-app/README.md](create-lightnode-app/README.md): all the
+  project templates.
+- Playground (no install, runs in your browser): <https://lightnode.app/playground>
+- Builder docs: <https://lightnode.app/build>
+- Runnable examples (open in your browser via StackBlitz):
+  <https://github.com/marinom2/lightnode-examples>
+
+Start with the first AI call above, then try Tool A to scaffold your first real
+project.

README.md

@@ -19,6 +19,15 @@ for running a worker. One project, two tracks.
 
 </div>
 
+## Never done this before? Start here
+
+If you're new to blockchain or Node.js development, read
+[GETTING-STARTED.md](GETTING-STARTED.md) first. It assumes no experience and
+covers, in about 5 minutes, making a wallet, getting free testnet funds, your first
+AI call, and the difference between the two ways to build (so you don't end up
+with a confusing mix of files). The rest of this README and the SDK docs assume
+you're already comfortable with a terminal and TypeScript.
+
 ## What you can do with this
 
 Two completely separate use cases live in this repo. Pick the one that matches

create-lightnode-app/README.md

@@ -9,6 +9,19 @@ npm create lightnode-app my-app
 
 Pick a template, set a private key, you're inference-enabled in ~2 minutes.
 
+First time? Read the [Getting Started guide](../GETTING-STARTED.md). It walks you
+through making a wallet, getting free testnet funds, and your first AI call with
+no prior experience.
+
+Note: this command creates a new folder (`my-app/`). You must `cd my-app` before
+running `npm install` or `npm run dev`. Running them in the parent folder fails
+with `npm error Missing script: "dev"`.
+
+Want to add inference to a folder you already have instead of making a new
+project? Use `npx lightnode add inference` (see
+[the SDK](https://www.npmjs.com/package/lightnode-sdk)). That writes files into
+your current folder and does not create a subfolder.
+
 ## Templates
 
 | Template | What you get | Run |

create-lightnode-app/src/index.ts

@@ -105,17 +105,24 @@ async function main() {
 
   console.log(`\n✅ scaffolded ${projectName} (${template}, ${network}) at ${dest}`);
   console.log("\nNext steps:");
-  console.log(`  cd ${projectName}`);
-  console.log(`  cp .env.example .env   # put a funded ${network} private key in PRIVATE_KEY`);
+  console.log(`  cd ${projectName}      # do this first. Every command below only works inside this folder.`);
+  console.log(`  cp .env.example .env   # then paste a funded ${network} private key into PRIVATE_KEY`);
   console.log(`  npm install`);
   if (template === "nextjs-api") {
-    console.log(`  npm run dev            # open http://localhost:3000\n`);
+    console.log(`  npm run dev            # open http://localhost:3000`);
   } else if (template === "hono") {
-    console.log(`  npm start              # server on http://localhost:3000/inference\n`);
+    console.log(`  npm start              # server on http://localhost:3000/inference`);
   } else {
-    console.log(`  npm start "your prompt"\n`);
+    console.log(`  npm start "your prompt"`);
+  }
+  console.log("");
+  console.log(`(If you see  npm error Missing script: "dev"  you ran it in the wrong folder. Run cd ${projectName} first.)`);
+  if (network === "testnet") {
+    console.log(`No wallet yet? Make one:  npx lightnode wallet new   then fund it free at https://lightfaucet.ai`);
+  } else {
+    console.log(`Heads up: mainnet spends real LCAI per call. To try it free, re-scaffold with --network testnet.`);
+    console.log(`Free testnet LCAI at https://lightfaucet.ai.`);
   }
-  console.log(`Free testnet LCAI at https://lightfaucet.ai.`);
   console.log(`Live in-browser playground at https://lightnode.app/playground.`);
 }
 

sdk/README.md

@@ -16,6 +16,12 @@ npm install lightnode-sdk viem
 LightChain's own docs list official SDKs as "soon"; this fills the gap. Not
 affiliated with LightChain.
 
+New to blockchain or Node.js? Read the
+[Getting Started guide](../GETTING-STARTED.md) first. It covers wallets, testnet
+vs mainnet, the `.env` file, and your first AI call in about 5 minutes. Then come
+back here for the full reference. The rest of this README assumes you're
+comfortable with TypeScript and a terminal.
+
 ## Five-line "hello world"
 
 ```ts

sdk/src/add.ts

@@ -359,7 +359,9 @@ function writeFile(abs: string, contents: string, force: boolean): WrittenFile {
 function depsNeeded(template: Template): string[] {
   if (template === "nextjs-api") return ["lightnode-sdk", "viem", "ws"];
   if (template === "hono") return ["lightnode-sdk", "viem", "ws"];
-  return ["lightnode-sdk", "viem", "ws"];
+  // The node/script template is run with `npx tsx <file>.ts`, so tsx must be
+  // installed too, otherwise `tsx ...` fails with "command not found".
+  return ["lightnode-sdk", "viem", "ws", "tsx"];
 }
 
 /**

sdk/src/cli.ts

@@ -353,20 +353,20 @@ async function main() {
       if (!anyWritten) {
         console.log("\nNothing to do - all target files already exist. Pass --force to overwrite.");
       } else {
-        console.log(`\nNext steps:`);
+        console.log(`\nNext steps (these files were added to your CURRENT folder, not a new project):`);
         console.log(`  1. ${result.install}`);
         if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat" || sub === "agent") {
           console.log(`  2. cp .env.example .env  (and put a funded ${result.network} PRIVATE_KEY in it)`);
           if (sub === "agent" && result.template === "nextjs-api") {
             console.log(`  3. Set CRON_SECRET in your Vercel env vars + edit AGENT_TASK in .env`);
             console.log(`  4. Deploy. Vercel Cron fires /api/agent on the schedule in vercel.json`);
           } else if (sub === "agent") {
-            console.log(`  3. AGENT_INTERVAL_MS=3600000 tsx agent.ts   # or run under pm2/systemd`);
+            console.log(`  3. AGENT_INTERVAL_MS=3600000 npx tsx agent.ts   # or run under pm2/systemd`);
           } else if (sub === "chat" && result.template === "nextjs-api") {
             console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
             console.log(`  4. npm run dev, open /chat`);
           } else if (sub === "chat") {
-            console.log(`  3. tsx chat-repl.ts  (interactive terminal chat)`);
+            console.log(`  3. npx tsx chat-repl.ts  (interactive terminal chat)`);
           } else if (sub === "nft-mint-with-inference" && result.template === "nextjs-api") {
             console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
             console.log(`  4. npm run dev, open /nft-mint`);
@@ -375,20 +375,24 @@ async function main() {
           } else if (result.template === "hono") {
             console.log(`  3. wire inferenceHandler into your Hono app, then start it`);
           } else if (sub === "nft-mint-with-inference") {
-            console.log(`  3. tsx nft-metadata.ts "My NFT" "concept goes here"`);
+            console.log(`  3. npx tsx nft-metadata.ts "My NFT" "concept goes here"`);
           } else {
-            console.log(`  3. tsx lightchain-inference.ts "your prompt"`);
+            console.log(`  3. npx tsx lightchain-inference.ts "your prompt"`);
           }
         } else {
           // analytics-dashboard - read-only, no private key needed.
           if (result.template === "nextjs-api") {
             console.log(`  2. npm run dev, open /lightnode-analytics`);
           } else {
-            console.log(`  2. tsx lightnode-analytics.ts`);
+            console.log(`  2. npx tsx lightnode-analytics.ts`);
           }
         }
+        if (result.network === "testnet") {
+          console.log(`\nNo wallet yet? Make one:  npx lightnode wallet new   then fund it free below.`);
+        }
         console.log(`\nFree testnet LCAI: https://lightfaucet.ai`);
         console.log(`Builder docs:     https://lightnode.app/build`);
+        console.log(`New to all this?  See GETTING-STARTED.md in the lightnode repo.`);
       }
       break;
     }