adding principles and goals doc; referring to it from other docs

Author: devalbo

AGENTS.md

@@ -7,6 +7,7 @@ Context for AI assistants working on this repo.
 **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. The CLI runs in the **browser** (Terminal tab) and in **Node** (`npm run cli`); same commands, environment-specific persistence (LocalStorage vs `~/.tb-solid-pod/data/store.json`).
+- **Unified CLI = Agent API**: The same CLI commands work as a programmatic API for AI coding agents. No custom SDK—agents issue CLI commands (`create-persona`, `list-contacts`, `export`) in browser or terminal. See [Principles and Goals](docs/PRINCIPLES_AND_GOALS.md) for the full vision.
 - **Data**: personas (WebID-style), contacts (including agents), groups (org/team/group) with membership of contacts and your personas, type indexes, virtual file system with metadata, settings/preferences.
 - **Stack**: React, TinyBase, Zod, Vite, TypeScript. Vocabularies: FOAF, vCard, Dublin Core, W3C Org, `@inrupt/vocab-*`.
 
@@ -68,22 +69,23 @@ When someone wants to use this in an app they’re working on, point them to the
 - **Pre-built data model** — Personas, contacts, groups, type indexes, file metadata already modeled (Zod + JSON-LD); consumer doesn’t have to design schemas.
 - **Pick what to use** — Schemas only, CLI, or React components; no need to take the full app.
 - **No new infra** — No API to host, no auth to set up; runs in the browser with React (+ TinyBase if needed).
-- **Types, Zod, and JSON Schema included** — TypeScript and Zod come with the package; JSON Schema (draft-2020-12) is exported for all schemas via Zod v4’s toJSONSchema; no extra typing or schema authoring.
+- **Types, Zod, and JSON Schema included** — TypeScript and Zod come with the package; JSON Schema (draft-2020-12) is exported for all schemas via Zod v4's toJSONSchema; no extra typing or schema authoring.
 - **Flexible integration** — Copy-paste or install as dependency; both are documented for low effort.
+- **Agent-friendly CLI** — The CLI doubles as an API for AI coding agents; same commands in browser and terminal, no custom integration needed. See [Principles and Goals](docs/PRINCIPLES_AND_GOALS.md#8-unified-cli-for-browser-and-terminal).
 
 ## Useful docs
 
-- **README.md** – Overview, limitations, Use as a library (Zod + JSON Schema), link to Integration Guide, Getting Started (Node note, Live demo + 404 troubleshooting), Running the CLI in the terminal (`npm run cli`, exit, single-command mode), Testing (unit, BDD, Storybook link), CLI command list.
-- **docs/INTEGRATION_GUIDE.md** – Step-by-step integration (install-from-GitHub vs copy-paste), store setup, Provider, components, CLI (browser + terminal), data tables, extending.
-- **docs/SDLC_PROCESS.md** – How changes are introduced, documented, and verified; links to Feature Checklist.
-- **docs/FEATURE_CHECKLIST.md** – Manual verification checklist ordered by dependency (foundational first); assume features are broken until verified.
-- **docs/CODING_GUIDELINES.md** – TypeScript (strict types, no sloppy types), short functions, simple React components, naming, file length.
-- **docs/DOCUMENTATION_GUIDELINES.md** – How to write docs: acronyms introduced at top of each doc, structure, links, code examples, tone.
+- **README.md** – Overview, limitations, Use as a library, Getting Started, CLI.
+- **docs/PRINCIPLES_AND_GOALS.md** – Core principles (local-first, data sovereignty, sync later, interoperability); why TinyBase and Solid; what we commit to. **Start here for the "why."**
+- **docs/INTEGRATION_GUIDE.md** – Step-by-step integration (install vs copy-paste), store setup, Provider, components, CLI.
+- **docs/USE_CASES.md** – How app authors access and manage users, groups, and documents.
+- **docs/SHORTCOMINGS.md** – What the library does *not* provide (no WAC, no "shared with me," no p2p transport, etc.).
+- **docs/DOCUMENT_SHARING_SCENARIOS.md** – Sharing scenarios (Solid or ad hoc p2p).
+- **docs/SOLID_SERVER_STRATEGIES.md** – Sync design, authority modes, implementation order.
+- **docs/SDLC_PROCESS.md** – How changes are documented and verified; Feature Checklist.
+- **docs/CODING_GUIDELINES.md** – TypeScript, functions, React components, naming.
+- **docs/DOCUMENTATION_GUIDELINES.md** – How to write docs.
 - **docs/IMPLEMENTATION_PLAN.md** – Feature phases and roadmap.
-- **docs/DOCUMENT_REVIEW.md** – Documentation review: planning strengths, objections/risks, and areas where more information is required.
-- **docs/USE_CASES.md** – How app authors use the library to access and manage users (personas), groups, and documents; Q&A and quick reference.
-- **docs/DOCUMENT_SHARING_SCENARIOS.md** – Scenarios for apps where users share document-oriented data (Solid or ad hoc p2p); what the library helps with and what the app adds.
-- **docs/SHORTCOMINGS.md** – Shortcomings for document sharing and collaboration (no WAC, no "shared with me," no p2p transport, etc.).
 - **docs/TEST_PLAN.md** – Test phases and verification.
-- **docs/testing/** – Unit (unit-tests.md), BDD/E2E (bdd-tests.md), Storybook (storybook.md); BDD does not start the dev server (start it manually).
+- **docs/testing/** – Unit, BDD/E2E, Storybook docs.
 - **DESIGN.md** – Design notes.

README.md

@@ -52,27 +52,16 @@ This library provides a complete foundation for **user-owned social data** in we
 
 ## Benefits for Social Applications
 
-### 1. User Data Ownership
-Users control their data in their browser's LocalStorage. No server-side database required for basic functionality. Data can be exported as JSON-LD for portability.
-
-### 2. Interoperable Schemas
-Built on established vocabularies (FOAF, vCard, Dublin Core, Schema.org, W3C Org), making data portable to other Solid-compatible systems or any RDF-aware application.
-
-### 3. Relationship Modeling
-The contact + group + persona architecture supports:
-- Friend/follower relationships
-- Team collaboration structures
-- Organization hierarchies
-- Agent/bot permissions (who can act on your behalf)
-
-### 4. Offline-First
-TinyBase with LocalStorage means the app works entirely offline. No network requests required for core functionality.
-
-### 5. Reactive UI
-TinyBase's reactive hooks (`useRow`, `useTable`, `useSliceRowIds`) keep UI in sync with data automatically. Changes in CLI reflect immediately in the graphical UI and vice versa.
-
-### 6. Extensible Foundation
-The schema system (Zod + JSON-LD) provides a pattern for adding new data types. The CLI command registry makes adding new commands straightforward.
+See [docs/PRINCIPLES_AND_GOALS.md](docs/PRINCIPLES_AND_GOALS.md) for the full rationale (why TinyBase, why Solid, what we commit to).
+
+| Benefit | Summary |
+|---------|---------|
+| **User Data Ownership** | Data in browser LocalStorage; export as JSON-LD anytime. |
+| **Interoperable Schemas** | FOAF, vCard, Dublin Core, Schema.org, W3C Org—portable to Solid/RDF systems. |
+| **Relationship Modeling** | Personas + contacts + groups support friend/follower, team, org, and agent patterns. |
+| **Offline-First** | TinyBase + LocalStorage; no network required for core features. |
+| **Reactive UI** | TinyBase hooks keep UI in sync; CLI and UI reflect changes immediately. |
+| **Extensible** | Zod + JSON-LD schemas and CLI command registry for adding new types. |
 
 ## Limitations & Where It Falls Short
 

docs/DOCUMENT_SHARING_SCENARIOS.md

@@ -1,27 +1,25 @@
 # Document-sharing scenarios
 
-This doc describes how **tb-solid-pod** can support applications where **users share document-oriented data** with one another—ideally following **Solid** principles (pod URLs, access control, federation) or, as a fallback, **ad hoc peer-to-peer** (export/import, link, or custom channel). It is written for app authors who are evaluating or integrating the library for sharing and collaboration features.
+This doc describes how **tb-solid-pod** supports applications where users share document-oriented data. It covers Solid-style sharing (pod URLs, WAC) and ad hoc peer-to-peer (export/import). For core principles (local-first, data sovereignty, interoperability), see [PRINCIPLES_AND_GOALS.md](PRINCIPLES_AND_GOALS.md). For what the library does *not* provide, see [SHORTCOMINGS.md](SHORTCOMINGS.md).
 
-**Terms used here:** **Solid** is the [Solid Project](https://solidproject.org/) vision: user-owned data in **pods** (personal online data stores) with **WebID** identity and **WAC** (Web Access Control) for sharing. **LDP** (Linked Data Platform) is the W3C standard for HTTP read/write of linked data; Solid pods expose LDP. **Document-oriented data** means files, folders, and metadata (title, author, description) that users create and want to share with contacts or groups. **P2P** (peer-to-peer) here means ad hoc sharing without a central server—e.g. export/import, QR, messenger, or WebRTC—as a worst-case or complement to Solid.
-
-For what the library *does not* provide today (no WAC, no “shared with me,” no built-in p2p transport), see [SHORTCOMINGS.md](SHORTCOMINGS.md).
+**Terms:** **Document-oriented data** = files, folders, and metadata (title, author, description). **P2P** = ad hoc sharing without a server (export/import, QR, messenger).
 
 ---
 
-## How this library helps document-sharing apps
+## What enables sharing
 
-The library gives you a **consistent data model** and **portable data** that work across scenarios:
+The library's data model supports sharing scenarios (see [PRINCIPLES_AND_GOALS.md](PRINCIPLES_AND_GOALS.md) for why):
 
-| What you get | Why it helps sharing |
-|--------------|----------------------|
-| **Personas** (identity) | “Who is the author?” and “Who is the current user?”—needed for attribution and for designating share targets. |
-| **Contacts** (address book) | “Who can I share with?” Contacts are natural share targets; you can later map them to WebIDs when syncing to a Solid pod. |
-| **Groups** (org/team/group + membership) | “Share with a team” or “share with this list.” Membership (contacts + your personas) defines the audience. |
-| **Resources** (files/folders + metadata) | Documents live in the `resources` table with title, author, description, MIME type. Author can be a persona `@id`; same shape works locally and (after transform) on an LDP server. |
-| **Export/import** | `exportStore()` / import produce portable JSON. Users can send a document (or full pod snapshot) to someone else; the recipient can import into their own store. |
-| **Vocabularies** (FOAF, vCard, Dublin Core, Schema.org) | Data is interoperable; when you sync to a Solid pod or send JSON, other Solid-aware apps can understand it. |
+| Data | Sharing role |
+|------|--------------|
+| **Personas** | Author attribution; designating share targets by identity. |
+| **Contacts** | Natural recipients; map to WebIDs when syncing to a pod. |
+| **Groups** | "Share with team"; membership defines the audience. |
+| **Resources** | Documents with metadata; same shape locally and on LDP. |
+| **Export/import** | Portable JSON for ad hoc sharing. |
+| **Vocabularies** | Interoperable data (FOAF, vCard, etc.). |
 
-What the library **does not** provide (see [SHORTCOMINGS.md](SHORTCOMINGS.md)): **WAC** (per-document “share with contact/group”), **“shared with me”** views, **resolvable document URLs** (until you sync to an LDP server), or a **p2p transport** (WebRTC, etc.). Your app can still use the data model and export/import to implement sharing flows that work today and align with Solid later.
+**Not provided:** WAC, "shared with me" views, resolvable URLs (until synced), p2p transport. See [SHORTCOMINGS.md](SHORTCOMINGS.md).
 
 ---
 
@@ -116,7 +114,7 @@ What the library **does not** provide (see [SHORTCOMINGS.md](SHORTCOMINGS.md)):
 
 ## Related docs
 
-- **[USE_CASES.md](USE_CASES.md)** – How to access and manage users, groups, and documents in your app (store, components, factory functions).
-- **[SHORTCOMINGS.md](SHORTCOMINGS.md)** – What the library does *not* provide for document sharing and collaboration (WAC, “shared with me,” p2p transport, etc.).
-- **[SOLID_SERVER_STRATEGIES.md](SOLID_SERVER_STRATEGIES.md)** – How to add a persistent Solid server as a sync target so documents get URLs and can be shared via Solid.
-- **[README – Limitations](../README.md#limitations--where-it-falls-short)** – High-level limitations (no LDP, single-user, no WAC, etc.).
+- **[PRINCIPLES_AND_GOALS.md](PRINCIPLES_AND_GOALS.md)** – Core principles: local-first, data sovereignty, interoperability.
+- **[USE_CASES.md](USE_CASES.md)** – How to access and manage users, groups, and documents.
+- **[SHORTCOMINGS.md](SHORTCOMINGS.md)** – What the library does *not* provide.
+- **[SOLID_SERVER_STRATEGIES.md](SOLID_SERVER_STRATEGIES.md)** – How to add a sync target for resolvable URLs.

docs/INTEGRATION_GUIDE.md

@@ -1,8 +1,8 @@
 # Integration Guide
 
-This guide explains how to integrate **tb-solid-pod** into an application you are building. It is for developers who want to add Solid-style personas, contacts, groups, type indexes, or file metadata to their app, either by installing the package from GitHub or by copying source files.
+This guide explains *how* to integrate **tb-solid-pod** into your app. For *why* (principles, local-first, data sovereignty), see [PRINCIPLES_AND_GOALS.md](PRINCIPLES_AND_GOALS.md). For practical "how do I…" questions, see [USE_CASES.md](USE_CASES.md).
 
-**Terms:** **TinyBase** is the reactive store and persistence library used by this project. **JSON-LD** (JavaScript Object Notation for Linked Data) is the data format used for personas, contacts, and groups. **CLI** (command-line interface) refers to the terminal provided by the library: in-app (browser Terminal tab) or Node (`npm run cli`).
+**Terms:** **TinyBase** = reactive store + persistence. **JSON-LD** = data format for personas, contacts, groups. **CLI** = terminal (browser or Node).
 
 ## Two ways to integrate