bccsa · johan-bell · Jun 9, 2025 · Jun 9, 2025 · Jun 9, 2025 · Jun 9, 2025
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -11,7 +11,7 @@ Luminary is an offline-first content platform. The repo is a monorepo with no ro
 - `app/` — Offline-first Vue 3 PWA (Vite, port 4174). See `app/CLAUDE.md`.
 - `cms/` — Vue 3 CMS SPA (Vite, port 4175). See `cms/CLAUDE.md`.
 - `playwright-tests/` — Standalone E2E suite targeting **deployed** environments. Not wired into any package build. See `playwright-tests/README.md`.
-- `docs/` — ADRs (`docs/adr/`) and architecture diagrams.
+- `docs/` — ADRs (`docs/adr/`), guides, architecture, and feature docs. Index: `docs/README.md`.
 
 **Always read the relevant subpackage's `CLAUDE.md` before working there.** This file only covers cross-package concerns.
 

diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ lu·mi·nary - ˈlü-mə-ˌner-ē
 - `app`: Web and native frontend app
 - `cms`: Backend CMS for managing content
 - `shared`: Shared library used by the CMS and app
-- `docs`: Documentation, including ADRs
+- `docs`: Documentation — see [docs/README.md](./docs/README.md) (ADRs, guides, architecture, features)
 
 ## Architectural Decision Records
 
@@ -49,4 +49,4 @@ See the [Shared readme](./shared/README.md)
 
 ### Project automation
 
-See the [Project automation readme](./docs/project-addons/automation/project-automation.md)
+See the [Project automation guide](./docs/guides/project-automation.md)
diff --git a/api/src/db/schemaUpgrade/README.md b/api/src/db/schemaUpgrade/README.md
@@ -110,7 +110,7 @@ Schema upgrades can be safely removed when:
     curl http://admin:password@localhost:5984/database/_schemas
     ```
 2. **Archive old upgrades** (optional but recommended):
-    - Move old upgrade files to `docs/historical-upgrades/` for reference
+    - Move old upgrade files to `docs/archive/historical-upgrades/` for reference
     - Include git commit hash and date when they were removed
 3. **Remove from codebase**:
     - Delete old upgrade files

diff --git a/api/src/db/seedingDocs/lang-eng.json b/api/src/db/seedingDocs/lang-eng.json
@@ -49,14 +49,17 @@
         "settings.device_info.title": "Device info",
         "settings.device_info.description": "Provide these details when contacting support",
         "home.title": "Home",
-        "home.continue": "Continue Watching",
+        "home.continue": "Continue",
         "home.continueListening": "Continue Listening",
         "explore.title": "Explore",
         "explore.other": "Other",
         "watch.title": "Watch",
         "home.newest": "Newest",
         "content.related_title": "Related",
         "content.coming_soon": "Coming soon",
+        "content.continueReading.prompt": "Continue where you left off?",
+        "content.continueReading.action": "Continue where you left off",
+        "content.continueReading.dismiss": "Start from top",
         "notification.login.title": "You are missing out!",
         "notification.login.message": "Click here to create an account or log in",
         "notification.offline.title": "You are offline.",

diff --git a/api/src/db/seedingDocs/lang-fra.json b/api/src/db/seedingDocs/lang-fra.json
@@ -49,14 +49,17 @@
         "settings.device_info.title": "Informations sur l'appareil",
         "settings.device_info.description": "Fournissez ces détails lors de la prise de contact avec le support",
         "home.title": "Accueil",
-        "home.continue": "Continuer à regarder",
+        "home.continue": "Continuer",
         "home.continueListening": "Continuer à écouter",
         "explore.title": "Explore",
         "explore.other": "Autre",
         "watch.title": "Regarde",
         "home.newest": "Nouveaux",
         "content.related_title": "Contenus similaires",
         "content.coming_soon": "Bientôt disponible",
+        "content.continueReading.prompt": "Reprendre où vous vous êtes arrêté ?",
+        "content.continueReading.action": "Reprendre où vous vous êtes arrêté",
+        "content.continueReading.dismiss": "Recommencer depuis le début",
         "notification.login.title": "Vous manquez quelque chose!",
         "notification.login.message": "Cliquez ici pour créer un compte ou vous connecter.",
         "notification.offline.title": "Vous êtes hors ligne.",

diff --git a/api/src/permissions/permissions.service.ts b/api/src/permissions/permissions.service.ts
@@ -683,7 +683,7 @@ export class PermissionSystem extends EventEmitter {
     }
 
     /**
-     * Update upstream inherited permissions on the parent group's map for a given ACL entry (referring to (1) in permissionSystem.drawio.svg)
+     * Update upstream inherited permissions on the parent group's map for a given ACL entry (referring to (1) in docs/architecture/diagrams/permissionSystem.drawio.svg)
      * This function is an event handler for the AclEntryUpdatedEvent, and should only be called from within a group (PermissionSystem) object (i.e. do not call it on parent or child groups)
      */
     private upsertUpstreamInheritedMap(event: AclEntryUpdatedEvent) {
@@ -697,7 +697,7 @@ export class PermissionSystem extends EventEmitter {
     }
 
     /**
-     * Update downstream inherited group maps for a given DocType in the passed ACL group map (referring to (3) in permissionSystem.drawio.svg)
+     * Update downstream inherited group maps for a given DocType in the passed ACL group map (referring to (3) in docs/architecture/diagrams/permissionSystem.drawio.svg)
      */
     private upsertDownstreamInheritedMap(aclGroup: AclGroupMap, type: DocType) {
         const parentGroup = aclGroup.ref;
@@ -740,7 +740,7 @@ export class PermissionSystem extends EventEmitter {
     }
 
     /**
-     * Iteratively forward inherited group maps until the top level parent has been reached (referring to (3) in permissionSystem.drawio.svg)
+     * Iteratively forward inherited group maps until the top level parent has been reached (referring to (3) in docs/architecture/diagrams/permissionSystem.drawio.svg)
      */
     private forwardInheritedMap(
         target: Uuid,

diff --git a/app/CLAUDE.md b/app/CLAUDE.md
@@ -52,7 +52,9 @@ Uses `@auth0/auth0-vue` with multiple providers selected at runtime from `AuthPr
 
 ### i18n
 
-UI strings live in CouchDB Language documents, loaded at runtime (`src/i18n.ts`). English seed is `../api/src/db/seedingDocs/lang-eng.json`. See `../docs/translations.md` for the workflow.
+UI strings live in CouchDB Language documents, loaded at runtime (`src/i18n.ts`). English seed is `../api/src/db/seedingDocs/lang-eng.json`. See `../docs/guides/translations.md` for the workflow.
+
+Reading progress (segments, gates, homepage row): `../docs/features/reading-progress-tracker/README.md`.
 
 ### Plugins
 

diff --git a/app/README.md b/app/README.md
@@ -6,7 +6,7 @@ This is the frontend of the Luminary app. It's an offline-first Vue app that run
 
 Cross-cutting services follow a **contract + injection key + build-time virtual module** pattern: Vite resolves each `virtual:…` id to an entry under **`src/build-time/plugins/<name>/`**, and **`src/build-time/contracts/plugin-registry.ts`** registers those services on the app. Feature code uses **`inject`** with keys from **`token.ts`** under **`src/build-time/contracts/`**, not direct imports of adapter code.
 
-**Example in this repo:** the **demo banner** (`virtual:demo-banner`, `src/build-time/plugins/demo-banner/`). Full pattern and diagrams: **[docs/vue-plugin-architecture/README.md](../docs/vue-plugin-architecture/README.md)**. Step-by-step for a **second** plugin: **[Adding another build-swapped plugin](../docs/vue-plugin-architecture/README.md#adding-another-plugin)**.
+**Example in this repo:** the **demo banner** (`virtual:demo-banner`, `src/build-time/plugins/demo-banner/`). Full pattern and diagrams: **[docs/features/vue-plugin-architecture/README.md](../docs/features/vue-plugin-architecture/README.md)**. Step-by-step for a **second** plugin: **[Adding another build-swapped plugin](../docs/features/vue-plugin-architecture/README.md#adding-another-plugin)**.
 
 ## Project structure
 
@@ -67,16 +67,22 @@ app/
 
 UI strings are stored in CouchDB language documents and loaded at runtime via `src/i18n.ts` using [vue-i18n](https://vue-i18n.intlify.dev/). The default English strings are seeded from `api/src/db/seedingDocs/lang-eng.json`.
 
-See [docs/translations.md](../docs/translations.md) for details on:
+See [docs/guides/translations.md](../docs/guides/translations.md) for details on:
 
 - How to add or update translation strings
 - Strings that contain named interpolation placeholders (`{variable}`)
 - Strings that are shown only under specific UI conditions
 - Strings reserved for future use
 
+## Reading progress
+
+The app tracks how far a user has read through article text and surfaces in-progress posts on the homepage **Continue Reading** row. Segment-based gates (visibility, skim detection, dwell time) ensure progress reflects actual reading, including long paragraphs on small screens.
+
+Full design, diagrams, and constants: **[docs/features/reading-progress-tracker/README.md](../docs/features/reading-progress-tracker/README.md)**.
+
 ## Local setup
 
-Refer to the [setup guide](../docs/setup-vue-app.md).
+Refer to the [setup guide](../docs/guides/setup-vue-app.md).
 
 When running `npm run dev` the local reloading server of the app will start at http://localhost:4174.
 

diff --git a/app/src/build-time/plugins/Readme.md b/app/src/build-time/plugins/Readme.md
@@ -19,4 +19,4 @@ This folder holds **implementations** of app services that depend on the build t
 2. Implement the service (and optional UI shell) in `./<name>/`.
 3. Register `virtual:<name>` in `buildTargetVirtuals.ts` and call `install*` from `plugin-registry.ts`.
 
-Full diagrams and bootstrap details: **[docs/vue-plugin-architecture/README.md](../../../../docs/vue-plugin-architecture/README.md)**.
+Full diagrams and bootstrap details: **[docs/features/vue-plugin-architecture/README.md](../../../../docs/features/vue-plugin-architecture/README.md)**.