doc updates

Author: devalbo

AGENTS.md

@@ -36,9 +36,12 @@ Context for AI assistants working on this repo.
    - **src/index.ts**: Re-exports schemas, utils, CLI, and components.  
    - **README**: “Use as a library” section with `npm install github:devalbo/tb-solid-pod` and example imports.
 
+4. **GitHub Pages (code)**  
+   Vite `base` is env-driven (`BASE_PATH` in CI). `.github/workflows/pages.yml` runs on every push to `main`, builds with `BASE_PATH=/tb-solid-pod/`, and deploys `dist/` to the `gh-pages` branch. README has Live demo link and a "Live demo 404?" note (private repo = no Pages on free plan).
+
 ## What’s not done
 
-- **GitHub Pages (manual)**: In repo **Settings → Pages**, set "Deploy from a branch", branch `gh-pages`, folder root. (Code is done: Vite `base` env-driven, `.github/workflows/pages.yml` deploys `dist/` to `gh-pages`; README has Live demo link.)  
+- **GitHub Pages (manual)**: In repo **Settings → Pages**, set "Deploy from a branch", branch `gh-pages`, folder root. (Code is done: Vite `base` env-driven, `.github/workflows/pages.yml` deploys `dist/` to `gh-pages`; README has Live demo link.) The live site returns **404 if the repo is private** on a free account—make the repo public or use GitHub Pro.  
 - **Optional**: Repo description/topics on GitHub; README “Library usage” expansion; npm publish later.
 
 ## Plan and checklists
@@ -56,7 +59,7 @@ Context for AI assistants working on this repo.
 
 ## Useful docs
 
-- **README.md** – Overview, limitations, Integration Guide (copy-paste vs install-from-GitHub), CLI command list.  
+- **README.md** – Overview, limitations, Use as a library, Integration Guide (copy-paste vs install-from-GitHub), Getting Started (Node note, Live demo + 404 troubleshooting), CLI command list.  
 - **docs/GITHUB_AND_LIBRARY_PLAN.md** – Goals, current state, section checklists, File Summary, Success Criteria.  
 - **docs/IMPLEMENTATION_PLAN.md** – Feature/phases.  
 - **DESIGN.md** – Design notes.

README.md

@@ -396,6 +396,8 @@ export function createProject(input: { name: string }, baseUrl: string) {
 
 **[Try the live demo](https://devalbo.github.io/tb-solid-pod/)** or run locally. Requires Node 18+ (or use `nvm use` if you use nvm).
 
+**Live demo 404?** GitHub Pages does not work with private repos on a free account. Make the repo public (Settings → General → Danger zone → Change visibility) or use GitHub Pro. Then set **Settings → Pages** → Deploy from branch **gh-pages**, folder **/ (root)**. The workflow deploys on every push to `main`.
+
 ```bash
 npm install
 npm run dev

docs/GITHUB_AND_LIBRARY_PLAN.md

@@ -32,10 +32,10 @@ Summary of what exists in the repo today.
 | **App entry** | Done | `index.html` + `src/main.tsx`; scripts `dev`, `build`, `preview`, `lint` present. |
 | **Source layout** | Done | `src/schemas/`, `src/utils/`, `src/cli/`, `src/components/` with expected files. |
 | **LICENSE** | Done | AGPL-3.0-or-later in repo; `package.json` has `"license": "AGPL-3.0-or-later"`. |
-| **README** | Partial | Has “Getting Started (Demo App)” with `npm install` / `npm run dev`. No Node version note, no “Use as a library” install-from-GitHub section, no “Live demo” link. Integration Guide documents copy-paste and schema-only use. |
-| **Runnable on checkout** | Partial | Commands work; no `.nvmrc`; README matches commands. |
+| **README** | Done | Has “Getting Started (Demo App)” with `npm install` / `npm run dev`. Node 18+ / `nvm use`; "Use as a library" with install-from-GitHub; Live demo link; 404 note. Integration Guide for copy-paste and schema-only use. |
+| **Runnable on checkout** | Done | Commands work; `.nvmrc` (20); README matches. |
 | **Library packaging** | Done | `package.json`: version 0.1.0, description, keywords, main, types, exports, files; `src/index.ts` re-exports schemas, utils, CLI, components; README “Use as a library” section. |
-| **GitHub Pages** | Done (code) | `vite.config.js` base env-driven; `.github/workflows/pages.yml` builds with `BASE_PATH=/tb-solid-pod/` and deploys to `gh-pages`; README has Live demo link. **You must set Settings → Pages: Deploy from branch `gh-pages`.** |
+| **GitHub Pages** | Done (code) | `vite.config.js` base env-driven; `.github/workflows/pages.yml` deploys to `gh-pages` on every push to `main`; README has Live demo link + 404 note. **Manual:** Settings → Pages: Deploy from branch `gh-pages`. **Private repo = 404 on free plan;** make repo public or use GitHub Pro for the live site. |
 | **GitHub repo** | Done | Repo on GitHub (`devalbo/tb-solid-pod`), main pushed, LICENSE in repo. **Repo is private for now**; make public when you want install-from-GitHub or a public Live demo. |
 
 **Next steps (in order):**