From de17285582c82ce77edc9fbd7967162da085a22d Mon Sep 17 00:00:00 2001 From: Alex Adams <70454645+aadams149@users.noreply.github.com> Date: Sat, 28 Feb 2026 23:34:01 -0500 Subject: [PATCH 1/2] Fix Music section in Help & FAQ to reference Apple Music, not Spotify The Music tab detects song/artist mentions in journal text and looks them up via Apple Music / iTunes. Updated the guide to describe this correctly and include tips for better detection. Co-Authored-By: Claude Opus 4.6 --- plugins/help_guide.py | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/plugins/help_guide.py b/plugins/help_guide.py index c6df43e..7892d22 100644 --- a/plugins/help_guide.py +++ b/plugins/help_guide.py @@ -143,18 +143,21 @@ def render(ctx): st.markdown(""" **What the Music tab does** -If you have Spotify listening data, Reflecting Pool can show what you -were listening to around the time of each journal entry. This can -surface interesting connections between your mood and your music. +Reflecting Pool scans your journal entries for mentions of songs and +artists, then looks them up on Apple Music / iTunes to show album +artwork, track details, and preview links. It's a fun way to see +what music was on your mind while you were writing. -**How to add Spotify data** +**How to get the best results** -1. Request your data from Spotify (Account > Privacy > Download your data). -2. Place the exported JSON files in the expected location. -3. The **Music** tab will automatically pick them up. +The detection works best when you're specific in your journal: -If you don't use Spotify or haven't added the data yet, the Music tab -will simply let you know. +- **Use quotes** - *listened to "Everlong" by Foo Fighters* +- **Mention artists** - *been listening to a lot of Radiohead lately* +- **Use colons** - *Song: "Karma Police"* + +If the Music tab says no mentions were detected, try writing about +songs or artists in your entries and they'll appear next time. """) # ------------------------------------------------------------------ From 3c95aa090d276483d05e159b2d98195d7f7df429 Mon Sep 17 00:00:00 2001 From: Alex Adams <70454645+aadams149@users.noreply.github.com> Date: Sat, 28 Feb 2026 23:41:30 -0500 Subject: [PATCH 2/2] Restructure Help Guide with Usage Guide + FAQ, add GitHub links Split the Help & FAQ tab into two sections: - Usage Guide: the original 7 expandable topics - FAQ: 8 common questions including data privacy, bug reporting, language support, typed text, sentiment accuracy, backups, plugins, and offline usage Also adds GitHub repo and profile links (with icon) at the top of the tab, and fixes British English spellings to American English (colour -> color, analysable -> analyzable, sub-folders -> subfolders). Co-Authored-By: Claude Opus 4.6 --- plugins/help_guide.py | 172 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 147 insertions(+), 25 deletions(-) diff --git a/plugins/help_guide.py b/plugins/help_guide.py index 7892d22..48b90e5 100644 --- a/plugins/help_guide.py +++ b/plugins/help_guide.py @@ -1,29 +1,49 @@ """ Help & FAQ plugin for Reflecting Pool. -Provides a user-friendly guide for non-technical users. Designed to -be the first place new users look when they're unsure how things work. +Provides a user-friendly usage guide and FAQ for non-technical users. +Designed to be the first place new users look when they're unsure how +things work. """ from plugin_loader import register +GITHUB_REPO = "https://github.com/aadams149/Reflecting-Pool" +GITHUB_PROFILE = "https://github.com/aadams149" + @register( "Help & FAQ", order=200, needs_df=False, - description="Plain-language guide and frequently asked questions", + description="Plain-language usage guide and frequently asked questions", ) def render(ctx): import streamlit as st st.markdown( - "Welcome to **Reflecting Pool**! This guide answers the most " - "common questions about how the app works. Click any section " - "below to expand it." + "Welcome to **Reflecting Pool**! This guide covers how to use " + "the app and answers frequently asked questions. Pick a section " + "below to get started." + ) + + # GitHub links + st.markdown( + f'' + '' + "Reflecting Pool on GitHub" + "  |  " + f'@aadams149', + unsafe_allow_html=True, ) st.divider() + # ================================================================== + # USAGE GUIDE + # ================================================================== + st.subheader("Usage Guide") + # ------------------------------------------------------------------ # 1. Getting Started # ------------------------------------------------------------------ @@ -32,7 +52,7 @@ def render(ctx): **What is Reflecting Pool?** Reflecting Pool turns your handwritten journal into a searchable, -analysable digital archive. You take photos of your journal pages, +analyzable digital archive. You take photos of your journal pages, the app reads the handwriting (using OCR - optical character recognition), and then you can search, browse, and explore your entries right here in the dashboard. @@ -67,8 +87,8 @@ def render(ctx): | Method | How it works | |--------|-------------| -| **Batch processing** | Place all photos in a folder, then run the OCR command once. Best for a large backlog of photos. | -| **OCR Watcher** | Use the *OCR Watcher* section in the sidebar to watch a folder. Every time you add a new photo, it's processed automatically. | +| **Batch processing** | Place all photos in a folder, then run the OCR command once. Best for a large backlog of photos. | +| **OCR Watcher** | Use the *OCR Watcher* section in the sidebar to watch a folder. Every time you add a new photo, it's processed automatically. | After processing, each entry gets a date (extracted from the filename or the photo's creation date) and a plain-text file. @@ -82,16 +102,16 @@ def render(ctx): **How search works** Reflecting Pool uses *semantic search*, which means you can search by -meaning rather than exact words. For example, searching for +meaning rather than exact words. For example, searching for "feeling stressed about deadlines" will find entries that talk about work pressure even if those exact words don't appear. **Two ways to search** - **Sidebar search** - type a query in the *Search* box on the left - and click **Search**. Results appear right in the sidebar. + and click **Search**. Results appear right in the sidebar. - **Chat tab** - open the **Chat** tab and have a conversation about - your journal. The AI assistant can pull relevant entries into its + your journal. The AI assistant can pull relevant entries into its answers. **Tips for better results** @@ -118,8 +138,8 @@ def render(ctx): **Sentiment analysis** Each entry is given a *sentiment score* between -1 (very negative) and -+1 (very positive). This is calculated automatically using a tool -called VADER, which looks at the words you used. It's a rough guide ++1 (very positive). This is calculated automatically using a tool +called VADER, which looks at the words you used. It's a rough guide to the emotional tone - not a clinical assessment. - Scores above **+0.3** are considered positive. @@ -145,7 +165,7 @@ def render(ctx): Reflecting Pool scans your journal entries for mentions of songs and artists, then looks them up on Apple Music / iTunes to show album -artwork, track details, and preview links. It's a fun way to see +artwork, track details, and preview links. It's a fun way to see what music was on your mind while you were writing. **How to get the best results** @@ -165,14 +185,14 @@ def render(ctx): # ------------------------------------------------------------------ with st.expander("Customizing Appearance", expanded=False): st.markdown(""" -**Themes and colours** +**Themes and colors** -Open the **Appearance** tab to change the look of the dashboard. You +Open the **Appearance** tab to change the look of the dashboard. You can adjust: -- **Primary colour** - the accent colour used on buttons and highlights -- **Background colour** - the main background of the page -- **Text colour** - the default text colour +- **Primary color** - the accent color used on buttons and highlights +- **Background color** - the main background of the page +- **Text color** - the default text color - **Font family** and **font size** Changes are saved automatically and will persist the next time you open @@ -193,7 +213,7 @@ def render(ctx): - Make sure the *OCR Output Directory* in the sidebar points to the correct folder (it should contain `text/` and `metadata/` - sub-folders). + subfolders). - Confirm that you've run the OCR pipeline at least once so there are processed text files. @@ -213,13 +233,115 @@ def render(ctx): **The app feels slow** -- Large numbers of entries can take a moment to load. Try narrowing +- Large numbers of entries can take a moment to load. Try narrowing the date range in the sidebar. - The first search after starting the app may be slower while the database loads into memory. +""") + + # ================================================================== + # FAQ + # ================================================================== + st.divider() + st.subheader("Frequently Asked Questions") + + with st.expander("Does Reflecting Pool share my data with anyone?", expanded=False): + st.markdown(""" +**No.** Reflecting Pool runs entirely on your own computer. Your +journal text, photos, and search database all stay on your machine. +Nothing is uploaded to the cloud or shared with third parties. + +The only network calls the app makes are: + +- **Apple Music / iTunes lookups** when the Music tab searches for + song metadata (only the song or artist name is sent, not your + journal text). +- **Chat tab** requests, if you've configured an AI provider - only + the specific journal excerpts relevant to your question are sent. + +You can use the app completely offline if you skip the Music and Chat +features. +""") + + with st.expander("I think I've found a bug. How can I report it?", expanded=False): + st.markdown(f""" +The best way to report a bug is to open an issue on GitHub: + +1. Go to the [Reflecting Pool Issues page]({GITHUB_REPO}/issues). +2. Click **New Issue**. +3. Describe what happened, what you expected, and any error messages + you saw. + +If you're not comfortable with GitHub, you can also reach the +developer at their [GitHub profile]({GITHUB_PROFILE}). +""") + + with st.expander("What languages does Reflecting Pool support?", expanded=False): + st.markdown(""" +Currently, Reflecting Pool is optimized for **English** handwriting. +The OCR engine (Tesseract) supports many languages, but the sentiment +analysis and text processing features are English-focused. + +Support for additional languages is something we'd like to add in the +future. +""") + + with st.expander("Can I use typed/printed text instead of handwriting?", expanded=False): + st.markdown(""" +Yes! The OCR engine works with both handwritten and printed text. +In fact, printed text tends to be recognized more accurately. Just +take a photo of the page the same way you would for handwriting. +""") + + with st.expander("How accurate is the sentiment analysis?", expanded=False): + st.markdown(""" +Sentiment analysis provides a general sense of the emotional tone of +each entry, but it's not perfect. The tool (VADER) was designed for +social media text, so it works best with straightforward language. + +Things to keep in mind: + +- **Sarcasm and irony** are often misread. +- **Mixed entries** (good and bad things in one entry) may average out + to neutral. +- The scores are most useful as a **general trend** over time rather + than a precise measurement of any single entry. +""") + + with st.expander("Can I back up my data?", expanded=False): + st.markdown(""" +Yes. Your data lives in a few places on your computer: + +| What | Where | +|------|-------| +| Original photos | Wherever you saved them | +| OCR output (text + metadata) | The *OCR Output Directory* shown in the sidebar | +| Search database | The *RAG Database Path* shown in the sidebar | +| Theme settings | `theme.json` in the project folder | + +To back up, simply copy these folders to an external drive or cloud +storage. The search database can also be rebuilt at any time by +clicking *Ingest to RAG* in the sidebar. +""") + + with st.expander("Can I add plugins or extend the app?", expanded=False): + st.markdown(f""" +Yes! Reflecting Pool has a plugin system. You can add new tabs by +dropping a Python file into the `plugins/` folder. Each plugin is a +small script that uses the `@register` decorator to add itself to the +dashboard. + +For details on how to write a plugin, see the +[plugins README]({GITHUB_REPO}/tree/main/plugins) on GitHub. +""") + + with st.expander("Do I need an internet connection?", expanded=False): + st.markdown(""" +For most features, **no**. The OCR processing, analytics, search, and +appearance customization all work offline. -**Something else?** +You will need an internet connection for: -Check the project's GitHub page for open issues, or create a new -issue describing what you're experiencing. +- **Music tab** - looks up song info on Apple Music / iTunes. +- **Chat tab** - sends queries to an AI provider (if configured). """)