docs: add comprehensive project docs (architecture, progress, configuration, troubleshooting)

2026-07-10 00:18:50 +08:00
parent 37cc8bfec6
commit 43977205b6
2 changed files with 235 additions and 1 deletions
@@ -63,4 +63,44 @@ t-youtube/
    *   **Key Takeaways (Bullet list)**
    *   **Actionable Verdict**
 3.  **Read/Skip State**: Mark videos as **Read** or **Skip** to clear them from your pending queue, allowing you to only keep track of what's unread.
-4.  **View Full Transcript**: Expand the accordion at the bottom of the digest to read the raw transcripts if needed.
+4. **View Full Transcript**: Expand the accordion at the bottom of the digest to read the raw transcripts if needed.
+5. **Agent Queue**: Save videos with notes to a queue for Hermes agents to process (create skills, open issues, etc.)
+
+---
+
+## 📚 Documentation
+
+Comprehensive documentation for this project is available in the `docs/` folder:
+
+- **[Architecture](docs/architecture.md)** - System overview, components, API endpoints, database schema
+- **[Progress](docs/progress.md)** - Session history, completed tasks, planned features, metrics
+- **[Configuration](docs/configuration.md)** - Environment variables, API tokens, database, Authelia, Caddy setup
+- **[Troubleshooting](docs/troubleshooting.md)** - Common issues, recovery procedures, monitoring
+
+---
+
+## 🚀 Setup Instructions
+
+### 1. Extract your YouTube browser cookies
+Since YouTube restricts subscription feeds to logged-in users, you need to export your logged-in cookies so `yt-dlp` can request the feed on your behalf:
+1. Install a browser extension like **Get cookies.txt LOCALLY** (Chrome/Edge) or **cookies.txt** (Firefox).
+2. Open YouTube in your browser and ensure you are logged in to your account.
+3. Click the extension icon and export the cookies for `youtube.com` as a Netscape-formatted text file.
+4. Create a folder named `config` in your project root, rename the exported file to `cookies.txt`, and save it inside:
+   ```text
+   t-youtube/config/cookies.txt
+   ```
+
+### 2. Configure Environment Variables
+Create a `.env` file in the root directory:
+```env
+# Optional: Override the fallback OpenAI / Anthropic key
+OPENAI_API_KEY=sk-Kq5...rOlx
+```
+
+### 3. Build & Deploy using Docker Compose
+Run the following command to build the multi-stage image (compiles frontend static assets using Node, then packages backend with Python) and start the container:
+```bash
+docker compose up -d --build
+```
+The server will boot up and listen on port `8000`.