From de7218d90b076f0420932bd1a33dad18844bccbd Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 10 Feb 2026 14:09:05 +0000
Subject: [PATCH] docs(ai): update quickstart and contributing (agent)

Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
---
 CONTRIBUTING.md |  1 +
 README.md       |  5 +++--
 docs/README.md  | 35 +++++++++++++++++++++++++++++++++++
 3 files changed, 39 insertions(+), 2 deletions(-)
 create mode 100644 docs/README.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7441c5a9..80b0a44f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -219,6 +219,7 @@ To use it:
 Before starting your work, please review these key documents:
 
 - **[AGENTS.md](./AGENTS.md)**: Architectural guidelines, mission statement, and troubleshooting tips.
+- **[Documentation Index](./docs/README.md)**: A complete list of system documentation, including architecture and feed logic.
 - **[Nostr Event Schemas](./docs/nostr-event-schemas.md)**: The source of truth for all Nostr events published by the application.
 - **[Playback Fallback](./docs/playback-fallback.md)**: Details on the URL-first playback strategy and WebTorrent fallback mechanism.
 
diff --git a/README.md b/README.md
index 782231bd..303a8d92 100644
--- a/README.md
+++ b/README.md
@@ -190,6 +190,8 @@ This project includes a `.devcontainer` configuration. If you use VS Code, you c
 
 See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full developer guide.
 
+For detailed architecture and system documentation, see the [Documentation Index](docs/README.md).
+
 **Verify your work:**
 
 - **Run unit tests**: `npm run test:unit` (Required before PRs). _Tip: Use `npm run test:unit:shard1`, `shard2`, or `shard3` for faster local feedback._
@@ -267,7 +269,7 @@ const event = buildVideoPostEvent({
 console.log("Event constructed:", event);
 
 // 2. Publish the event (requires browser/extension or active signer)
-/*
+// In an application context (e.g. browser console or module):
 import { nostrClient } from "./js/nostrClientFacade.js";
 
 // Ensure client is connected
@@ -278,7 +280,6 @@ await nostrClient.loginWithExtension();
 
 // Publish the built event
 await nostrClient.signAndPublishEvent(event);
-*/
 ```
 
 ### CSS build pipeline
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..30c50a0b
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,35 @@
+# Documentation Index
+
+Welcome to the bitvid documentation. This directory contains detailed architectural guides, API references, and system overviews.
+
+## Core Systems
+
+- **[Application Coordinators](./app-coordinators.md)**: Overview of the coordinator pattern used to manage app-wide state and services.
+- **[Authentication Architecture](./auth-architecture.md)**: How session management, login flows, and signer integration work.
+- **[Feed Engine](./feed-engine.md)**: The pipeline for fetching, filtering, scoring, and sorting video feeds.
+- **[Playback & Fallback](./playback-fallback.md)**: The URL-first playback strategy with WebTorrent fallback orchestration.
+- **[Watch History System](./watch-history-system.md)**: Encrypted watch history synchronization and storage.
+
+## Nostr Protocol
+
+- **[Nostr Event Schemas](./nostr-event-schemas.md)**: The definitive catalogue of all Nostr event kinds and data structures used by bitvid.
+- **[DM Privacy Model](./dm-privacy-model.md)**: How Direct Messages are handled, including NIP-17 relays and privacy controls.
+- **[NIP-46 Client Overview](./nip46-client-overview.md)**: Details on the NIP-46 remote signer implementation.
+
+## Moderation & Safety
+
+- **[Moderation Service](./moderation-service-overview.md)**: How content moderation, reporting, and admin lists function.
+- **[Logging Strategy](./logging.md)**: Guidelines for using `devLogger` vs `userLogger` and production logging policies.
+
+## Design & UI
+
+- **[Design System](./design-system.md)**: Guide to the token-based design system and CSS architecture.
+- **[Menus & Popovers](./menus.md)**: Documentation for the menu and popover system.
+
+## Operations
+
+- **[Instance Configuration](./instance-config.md)**: Guide to configuring a bitvid instance.
+- **[Deployment Notes](./deployment-notes.md)**: Notes and checklists for deploying bitvid.
+- **[Manual QA Checklist](./qa.md)**: The standard manual QA script for releases.
+
+For more details on contributing, please see [CONTRIBUTING.md](../CONTRIBUTING.md).