github/library plan step 3 - github pages

Author: devalbo

.github/workflows/pages.yml

@@ -0,0 +1,37 @@
+# Deploy demo app to GitHub Pages (https://<owner>.github.io/tb-solid-pod/)
+# Repo Settings → Pages: set "Deploy from a branch", branch gh-pages, folder / (root).
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write  # push to gh-pages branch
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        env:
+          BASE_PATH: "/tb-solid-pod/"
+        run: npm run build
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist

AGENTS.md

@@ -0,0 +1,62 @@
+# Agent instructions – tb-solid-pod
+
+Context for AI assistants working on this repo.
+
+## What this project is
+
+**tb-solid-pod** is a browser-based personal data pod inspired by the [Solid Project](https://solidproject.org/), built with [TinyBase](https://tinybase.org/) for reactive state and LocalStorage. It is **not** a real Solid server (no LDP, no WebID-TLS); it simulates Solid-style data (personas, contacts, groups, type indexes, file metadata) in a single-page app.
+
+- **Dual interface**: graphical UI (tabs, forms, lists) + CLI terminal.
+- **Data**: personas (WebID-style), contacts (including agents), groups (org/team/group), type indexes, virtual file system with metadata, settings/preferences.
+- **Stack**: React, TinyBase, Zod, Vite, TypeScript. Vocabularies: FOAF, vCard, Dublin Core, W3C Org, `@inrupt/vocab-*`.
+
+## Repo layout
+
+| Path | Purpose |
+|------|--------|
+| `src/main.tsx` | App entry (demo only). |
+| `src/App.tsx` | Root UI: tabs + CLI. |
+| `src/index.ts` | **Library entry** – re-exports schemas, utils, CLI, components for `import from 'tb-solid-pod'`. |
+| `src/schemas/` | Zod schemas + factory functions (persona, contact, group, file, typeIndex, preferences, base). |
+| `src/utils/` | settings, storeExport, typeIndex helpers, validation. |
+| `src/cli/` | CliTerminal, command registry, parse-args, types. |
+| `src/components/` | PersonaList/Form, ContactList/Form, GroupList/Form, MembershipManager, FileMetadataPanel. |
+| `docs/` | DESIGN.md, IMPLEMENTATION_PLAN.md, **GITHUB_AND_LIBRARY_PLAN.md** (authoritative for “three uses” plan). |
+
+## What’s done so far
+
+1. **GitHub-ready**  
+   Repo on GitHub (`devalbo/tb-solid-pod`), `main` pushed, LICENSE (AGPL-3.0-or-later). Repo is **private** for now.
+
+2. **Runnable on checkout**  
+   `npm install` and `npm run dev` work. README “Getting Started (Demo App)” is accurate. `.nvmrc` (Node 20) and README Node note (“Requires Node 18+” / `nvm use`) added.
+
+3. **Usable as a library (GitHub-only, no npm publish)**  
+   - **package.json**: `version` 0.1.0, `description`, `keywords`, `main`/`types`/`exports` → `./src/index.ts`, `files`: `["src", "README.md"]`, `private: true` kept.  
+   - **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.
+
+## 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.)  
+- **Optional**: Repo description/topics on GitHub; README “Library usage” expansion; npm publish later.
+
+## Plan and checklists
+
+- **docs/GITHUB_AND_LIBRARY_PLAN.md** is the source of truth for the “three uses” plan (runnable, library, GitHub Pages).  
+- Progress is tracked by **checklists** at the end of sections 1–4 (1.4, 2.6, 3.6, 4.5) and by the **Current state** table.  
+- When you complete a task, mark it `[x]` in the relevant checklist and refresh the Current state table so the plan stays accurate.
+
+## Conventions
+
+- **Library**: Consumers install from GitHub (`npm install github:user/tb-solid-pod`). We do not publish to npm for now; `private: true` is intentional.  
+- **Schemas**: Zod + JSON-LD; factory functions (e.g. `createPersona`, `createContact`) take a base URL for IRIs.  
+- **CLI**: Commands live in `src/cli/commands/`; registry in `src/cli/registry.tsx`.  
+- **Components**: React components expect a TinyBase `store` (and often `indexes`); they are default-exported and re-exported as named from `src/index.ts`.
+
+## Useful docs
+
+- **README.md** – Overview, limitations, Integration Guide (copy-paste vs install-from-GitHub), 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

@@ -2,6 +2,8 @@
 
 A browser-based personal data pod inspired by the [Solid Project](https://solidproject.org/), built with [TinyBase](https://tinybase.org/) for reactive state management and LocalStorage persistence.
 
+**[Live demo](https://devalbo.github.io/tb-solid-pod/)** · Run locally: `npm install` then `npm run dev` · [Use as a library](#use-as-a-library)
+
 ## What This Project Does
 
 This library provides a complete foundation for **user-owned social data** in web applications. It implements core Solid/Linked Data concepts in a lightweight, browser-first package:
@@ -392,7 +394,7 @@ export function createProject(input: { name: string }, baseUrl: string) {
 
 ## Getting Started (Demo App)
 
-Requires Node 18+ (or use `nvm use` if you use nvm).
+**[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).
 
 ```bash
 npm install

docs/GITHUB_AND_LIBRARY_PLAN.md

@@ -35,14 +35,14 @@ Summary of what exists in the repo today.
 | **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. |
 | **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** | Not done | No `base` in `vite.config.js`; no `.github/workflows/` (no `pages.yml` or `ci.yml`). |
+| **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 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):**  
 1) ~~Confirm repo on GitHub and push if needed.~~ Done (repo is private).  
 2) ~~Add `.nvmrc` and optional Node note in README.~~ Done.  
 3) ~~Add `src/index.ts`, update `package.json` for library use, add “Use as a library” in README.~~ Done.  
-4) Set Vite `base`, add Pages workflow, enable Pages, add “Live demo” link.
+4) ~~Set Vite `base`, add Pages workflow, add "Live demo" link.~~ Done. Enable Pages in repo Settings → Pages (Deploy from branch `gh-pages`).
 
 ---
 
@@ -177,10 +177,10 @@ Deploy the built Vite app so visitors can use it at `https://<username>.github.i
 
 GitHub Pages serves project sites from `/<repo>/`, so assets must use that base.
 
-- [ ] In **`vite.config.js`** (or `vite.config.ts`), set **`base`** to the repo name with leading and trailing slash:
-  - `base: '/tb-solid-pod/'` (replace with actual repo name if different).
-- [ ] Rebuild: `npm run build`. Check that `dist/index.html` references assets like `/tb-solid-pod/assets/...` (not `/assets/...`).
-- [ ] Optional: use an env variable so local dev keeps `base: '/'` and CI sets `base: '/repo-name/'` for the Pages build.
+- [x] In **`vite.config.js`** (or `vite.config.ts`), set **`base`** to the repo name with leading and trailing slash:
+  - `base: '/tb-solid-pod/'` (replace with actual repo name if different). Implemented as env-driven: `process.env.BASE_PATH ?? '/'`; CI sets `BASE_PATH: '/tb-solid-pod/'`.
+- [x] Rebuild: `npm run build`. Check that `dist/index.html` references assets like `/tb-solid-pod/assets/...` (not `/assets/...`).
+- [x] Optional: use an env variable so local dev keeps `base: '/'` and CI sets `base: '/repo-name/'` for the Pages build.
 
 ### 3.2 Build output
 
@@ -199,7 +199,7 @@ GitHub Pages serves project sites from `/<repo>/`, so assets must use that base.
 
 Add a workflow that builds and deploys to GitHub Pages. For example:
 
-- [ ] **Trigger**: push to `main` (or only when `dist/` or source changes, if you prefer).
+- [x] **Trigger**: push to `main` (or only when `dist/` or source changes, if you prefer).
 - **Steps**:
   1. Checkout repo.
   2. Setup Node (e.g. `actions/setup-node` with version from `.nvmrc` or fixed `20`).
@@ -211,16 +211,16 @@ Result: every push to `main` (or chosen branch) updates the live demo.
 
 ### 3.5 README and base path
 
-- [ ] In README, add a **“Try it”** or **“Live demo”** link at the top or in Getting Started: `https://<username>.github.io/<repo>/`.
+- [x] In README, add a **“Try it”** or **“Live demo”** link at the top or in Getting Started: `https://<username>.github.io/<repo>/`.
 - [ ] If repo is renamed, update `base` in Vite config and the README link.
 
 ### 3.6 Checklist (GitHub Pages)
 
-- [ ] `vite.config.js` has `base: '/<repo>/'` (or env-driven) so assets load on GitHub Pages.
-- [ ] `npm run build` produces a working `dist/` when base is set.
-- [ ] GitHub Actions workflow builds with correct base and deploys `dist/` to `gh-pages` (or chosen branch).
-- [ ] Repo Settings → Pages: source = branch (e.g. `gh-pages`), root.
-- [ ] README includes “Live demo” / “Try it” link to the Pages URL.
+- [x] `vite.config.js` has `base: '/<repo>/'` (or env-driven) so assets load on GitHub Pages.
+- [x] `npm run build` produces a working `dist/` when base is set.
+- [x] GitHub Actions workflow builds with correct base and deploys `dist/` to `gh-pages` (or chosen branch).
+- [ ] Repo Settings → Pages: source = branch (e.g. `gh-pages`), root. **(Do this in GitHub UI after first push.)**
+- [x] README includes “Live demo” / “Try it” link to the Pages URL.
 
 ---
 
@@ -259,8 +259,8 @@ Result: every push to `main` (or chosen branch) updates the live demo.
 - [x] Repo created on GitHub; default branch set (e.g. main).
 - [ ] Description and topics set.
 - [x] LICENSE file present; package.json “license” matches.
-- [ ] README explains runnable app + library use + “Live demo” link.
-- [ ] GitHub Actions Pages workflow added; deploys `dist/` to `gh-pages` on push to main.
+- [x] README explains runnable app + library use + “Live demo” link.
+- [x] GitHub Actions Pages workflow added; deploys `dist/` to `gh-pages` on push to main.
 - [ ] Settings → Pages: source = branch `gh-pages`, root.
 
 ---

vite.config.js

@@ -2,6 +2,10 @@ import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 
 // https://vite.dev/config/
+// BASE_PATH: set in CI (e.g. '/tb-solid-pod/') for GitHub Pages; local dev uses '/'
+const base = process.env.BASE_PATH ?? '/'
+
 export default defineConfig({
+  base,
   plugins: [react()],
 })