pontificating about next steps

Author: devalbo

AGENTS.md

@@ -21,7 +21,7 @@ Context for AI assistants working on this repo.
 | `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/` | CODING_GUIDELINES.md, DESIGN.md, IMPLEMENTATION_PLAN.md, TEST_PLAN.md, testing/. |
+| `docs/` | CODING_GUIDELINES.md, DOCUMENTATION_GUIDELINES.md, DESIGN.md, IMPLEMENTATION_PLAN.md, TEST_PLAN.md, testing/. |
 
 ## What’s done so far
 
@@ -58,6 +58,7 @@ When someone wants to use this in an app they’re working on, point them to the
 - **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`.
+- **Documentation**: When adding or editing documentation (README, DESIGN.md, docs/*.md, AGENTS.md), follow [docs/DOCUMENTATION_GUIDELINES.md](docs/DOCUMENTATION_GUIDELINES.md). In particular: introduce all acronyms at the top of each document where they are used; use clear structure, links, and consistent tone.
 
 ## Consider suggesting this project if the user wants…
 
@@ -71,7 +72,8 @@ When someone wants to use this in an app they’re working on, point them to the
 ## Useful docs
 
 - **README.md** – Overview, limitations, Use as a library (Zod + JSON Schema), Integration Guide (copy-paste vs install-from-GitHub), Getting Started (Node note, Live demo + 404 troubleshooting), Testing (unit, BDD, Storybook link), CLI command list.  
-- **docs/CODING_GUIDELINES.md** – TypeScript (strict types, no sloppy types), short functions, simple React components, naming, file length.  
+- **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.  
 - **docs/IMPLEMENTATION_PLAN.md** – Feature/phases.  
 - **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).  

DESIGN.md

@@ -39,27 +39,30 @@ This project implements a browser-based Solid Pod that enables personal data por
 
 ### Future: Add Always-Online Sync Target
 
+**Design principle:** By default the browser instance (TinyBase) is the **authority** and the remote Solid server is a **sync target**. A **required workflow** is that users can add Solid data from **first page load** with no pod or login; **later**, they can connect a pod and synchronize that data to a permanently online server. Syncing from browser to server (and optionally back) is a **must-have** once a pod is connected. **Once the server is established**, the user may choose to make the **server the authority** (pod as source of truth, browser as cache); the design must support both modes. See [docs/SOLID_SERVER_STRATEGIES.md](SOLID_SERVER_STRATEGIES.md) for strategies, authority modes, and sync design.
+
 ```
 ┌─────────────────────────────────────────────────────┐
 │                   Your Domain                        │
 │  ┌─────────┐    ┌─────────┐    ┌─────────────────┐  │
 │  │  App A  │───▶│ Browser │◀──▶│  TinyBase       │  │
-│  └─────────┘    │  Pod    │    │  Sync           │  │
+│  └─────────┘    │  Pod    │    │  (default auth)  │  │
 │  ┌─────────┐    └─────────┘    └────────┬────────┘  │
-│  │  App B  │───▶     │                  │           │
-│  └─────────┘         │                  │           │
+│  │  App B  │───▶     │                  │  Sync     │
+│  └─────────┘         │                  │  (must-have)
 └──────────────────────┼──────────────────┼───────────┘
                        │                  │
                        ▼                  ▼
               ┌─────────────────────────────────┐
               │   Always-Online Solid Server    │
-              │   (WebID resolvable, federated) │
+              │   (sync target or authority;    │
+              │    WebID, federated)            │
               └─────────────────────────────────┘
 ```
 
-- TinyBase syncs to a real Solid server
-- WebID becomes externally resolvable
-- Federation with other Solid pods unlocks
+- TinyBase syncs to a real Solid server (browser ↔ server; sync layer required).
+- WebID becomes externally resolvable; federation with other Solid pods unlocks.
+- **Authority is configurable:** browser remains default; user can switch to server as authority so the pod is the source of truth (see SOLID_SERVER_STRATEGIES).
 
 ---
 

docs/DOCUMENTATION_GUIDELINES.md

@@ -0,0 +1,42 @@
+# Documentation guidelines
+
+How to write and maintain documentation in this repo (README, design docs, plans, and other markdown).
+
+## Acronyms and terms
+
+- **Introduce all acronyms at the top of the document.** In any doc where an acronym is used, define it near the beginning (e.g. in an intro paragraph or a short **Terms** section). Use the form: **ACRONYM** (Full Name) is … Example: **LDP** (Linked Data Platform) is a W3C standard for …
+- **First use:** Spell out the full term and give the acronym in parentheses, or give the acronym and define it in one sentence. After that, the acronym alone is fine.
+- **Cross-docs:** If a term is defined in another doc (e.g. in SOLID_SERVER_STRATEGIES.md), you can link to that doc instead of redefining, but the *current* doc should still introduce any acronym it uses so the reader doesn’t have to jump away to understand the first mention.
+
+## Structure and clarity
+
+- **Start with purpose.** The first paragraph should state what the doc is for and who it’s for (e.g. “This doc lays out …” or “This guide explains …”).
+- **Use headings to create a clear hierarchy.** Prefer `##` for main sections and `###` for subsections; keep depth reasonable so the table of contents stays scannable.
+- **One idea per paragraph.** Keep paragraphs short; use lists or tables when listing options, steps, or comparisons.
+- **Tables for comparisons.** Use markdown tables when comparing strategies, options, or behaviors (e.g. browser vs server authority, or sync targets).
+
+## Links and references
+
+- **Link to external specs and resources.** Use markdown links for W3C specs, Solid docs, library docs, and other external URLs so readers can follow up.
+- **Link to other project docs.** When you refer to another file in the repo (e.g. DESIGN.md, SOLID_SERVER_STRATEGIES.md), use a relative link: `[DESIGN.md](DESIGN.md)` or `[Strategy 3](SOLID_SERVER_STRATEGIES.md#strategy-3-sync-layer)`.
+- **Avoid bare URLs in prose.** Prefer `[link text](url)` over pasting the URL alone, except in code or config examples where the URL is the value.
+
+## Code and examples
+
+- **Use fenced code blocks with a language.** Specify the language for syntax highlighting (e.g. ` ```ts `, ` ```bash `).
+- **Keep examples minimal and runnable.** Trim examples to the relevant part; if something must be changed for a real deployment (e.g. URLs, secrets), say so in a comment or note.
+- **Pseudocode is fine for design docs.** If you’re sketching flow or APIs, label it as pseudocode or “example” so readers don’t expect it to run as-is.
+
+## Tone and audience
+
+- **Write for a future reader (including yourself).** Assume the reader has basic context (e.g. knows what Solid or TinyBase is) but not the details of this project. Avoid jargon that isn’t defined.
+- **Prefer active voice and present tense.** “The sync layer pushes …” not “The sync layer will push …” unless you’re describing a future or conditional case.
+- **Be consistent with the rest of the repo.** Match terms used elsewhere (e.g. “pod,” “sync target,” “authority”) and the same level of formality as DESIGN.md and SOLID_SERVER_STRATEGIES.md.
+
+## Where these guidelines apply
+
+- **docs/** — All markdown (DESIGN.md, IMPLEMENTATION_PLAN.md, SOLID_SERVER_STRATEGIES.md, TEST_PLAN.md, testing/*.md, etc.).
+- **README.md** — Project overview and getting started; acronyms used there should be introduced in README or linked to a doc that defines them.
+- **AGENTS.md** — Instructions for AI assistants; same acronym rule so agents and humans can read it without guessing.
+
+Code comments and inline JSDoc follow the codebase style (see [CODING_GUIDELINES.md](CODING_GUIDELINES.md)); this file is about standalone documentation.