Skip to content

docs: correct README to reflect actual implementation - #34

Open
Kilo59 wants to merge 3 commits into
mainfrom
docs/correct-readme
Open

Kilo59 wants to merge 3 commits into
mainfrom
docs/correct-readme

Conversation

@Kilo59

@Kilo59 Kilo59 commented Aug 22, 2026 •

Copy link
Copy Markdown
Owner

Summary

The README was written before much of the implementation was complete, leaving several inaccuracies based on aspirational features. This PR corrects it to reflect the app as it actually exists.

Changes

Removed (aspirational/inaccurate)

  • Documentation homepage — linked to kilo59.github.io/netflix-narc/ which is not a deployed GitHub Pages site; all doc links now point to local docs/ files
  • CSM as the primary provider — the opening paragraph no longer implies Common Sense Media is the main engine; OMDb is the real default
  • TMDB as a working provider — factory.py raises NotImplementedError for TMDB; it is now clearly labeled "Coming Soon"
  • Enter keybinding — not present in any BINDINGS in the codebase
  • "Steam-inspired" — marketing copy with no substance
  • "(OMDb, CSM, TMDB) as co-equal working providers" — only OMDb and CSM are actually wired up

Added (accurately reflects code)

  • API Providers table — clearly shows OMDb (✅ recommended, free key), CSM (⚠️ key is hard to obtain), TMDB (🚧 not implemented)
  • Evidence Locker feature bullet — the SQLite manual data DB is a real, prominent feature
  • F2 shortcut in Interrogation Room — opens commonsensemedia.org in browser; key workflow for manually sourcing category scores without a CSM API key
  • CSM workaround note — explains how to use the Interrogation Room manually even without a CSM API key
  • Keybindings as a table — cleaner and matches actual BINDINGS in main.py

Summary by Sourcery

Update the README to accurately describe the application's current capabilities and usage.

Enhancements:

  • Align the README with the implemented application by clarifying provider support, documenting the Evidence Locker and CSM manual-scoring workflow, and accurately listing features and keybindings.

Documentation:

  • Correct documentation links and update setup, storage, workflow, provider, feature, and keyboard-shortcut guidance to reflect the current implementation.

- Replace CSM-as-primary framing with accurate provider table;
  OMDb is the default and CSM API key is not publicly obtainable
- Mark TMDB as 'Coming Soon' (raises NotImplementedError in factory.py)
- Remove non-existent GitHub Pages documentation site links
- Drop Enter keybinding (not present in any BINDINGS)
- Remove 'Steam-inspired' marketing copy
- Add Evidence Locker as an explicit feature bullet
- Add F2 Interrogation Room shortcut and CSM manual-lookup workflow
- Convert keybindings to a table matching actual app BINDINGS
- Note clipboard image paste is macOS-only
@sourcery-ai

sourcery-ai Bot commented Aug 22, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Updates README.md to remove aspirational/incorrect documentation and align feature descriptions, keybindings, and provider details with the current implementation, including accurate API provider status, Evidence Locker behavior, CSM workflow, and storage/sync setup.

Sequence diagram for manual Common Sense Media scoring

sequenceDiagram
    actor User
    participant Room as Interrogation Room
    participant Browser
    participant CSM as commonsensemedia.org
    participant Locker as Evidence Locker

    User->>Room: Press F2
    Room->>Browser: Open title search
    Browser->>CSM: Search title
    User->>Room: Enter category scores
    Room->>Locker: Save manual dossier
Loading

File-Level Changes

Change Details Files
Aligns high-level product description and feature bullets with current capabilities and workflows.
  • Rephrases intro to describe generic content rating APIs rather than Common Sense Media as the primary engine.
  • Updates feature bullets for Onboarding Wizard, Lineup & Interrogation Room, and suitability scoring to match actual behavior and terminology.
  • Clarifies that content metadata comes from OMDb by default with optional Common Sense Media, including local caching behavior.
  • Documents Evidence Locker as a local SQLite database for manual dossiers and follow-up flags.
  • Adjusts storage & sync feature description to remove deep-link to external docs and describe supported backends inline.
README.md
Removes dead/aspirational documentation links and normalizes remaining doc references.
  • Deletes link to non-existent GitHub Pages documentation homepage.
  • Removes inline links to onboarding, TUI walkthrough, storage & sync, and other guides where they implied a full hosted docs site.
  • Keeps CSV export doc reference but converts it to a simple relative link without marketing framing.
  • Simplifies installation/prerequisite references to avoid pointing at incomplete installation docs.
README.md
Documents actual API provider matrix and Common Sense Media workflow.
  • Introduces an API Providers table summarizing OMDb as default, CSM as advanced/non-public, and TMDB as not yet implemented.
  • Explicitly marks TMDB as "Coming Soon" to match factory behavior raising NotImplementedError.
  • Adds a subsection explaining manual CSM category entry using the Interrogation Room and F2 browser search workflow.
  • Clarifies that manual Evidence Locker data takes priority over API metadata when cross-referencing titles.
README.md
Updates keyboard shortcuts section to match real keybindings and highlight the CSM lookup shortcut.
  • Replaces bullet-list of keybindings with a table listing the active shortcuts and their actions.
  • Removes the undocumented Enter keybinding that is not present in the BINDINGS configuration.
  • Documents F2 in the Interrogation Room as opening a Common Sense Media browser search for the current title.
  • Tweaks labels for Lineup, Interrogation Room, Preferences, Advanced Options, Help, and Quit to reflect actual UI naming and behavior.
README.md
Cleans up wording and references for onboarding and storage configuration flows.
  • Removes links to onboarding and TUI walkthrough guides and instead describes the Onboarding Wizard behavior inline.
  • Renames the storage setup section to "Setup via Preferences" and simplifies the step list to match current UI labels.
  • Clarifies env-based configuration under ~/.config/netflix-narc/.env without referencing an external guide.
  • Adjusts step-by-step usage flow to reference active provider selection and Evidence Locker priority instead of generic API metadata wording.
README.md

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 1 issue

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="README.md" line_range="186" />
<code_context>
+| `l` | Open **The Lineup** (sequential review queue) |
+| `i` | Open **Interrogation Room** (manual data entry for selected title) |
+| `Space` | Flag selected title for follow-up |
+| `s` | Open **Preferences** (settings, weights, API provider & BYOS sync) |
+| `a` | Open **Advanced Options** (load CSV, run evaluation) |
+| `h` / `?` | Open **Help** overlay |
</code_context>
<issue_to_address>
**issue:** The keybindings table presents `s` as opening Preferences and `q` as quitting the application in every context, but the Lineup screen overrides `s` to skip the current title and `q` to leave the Lineup. Users following this table while in the Lineup perform different actions than documented.

**Triggers:** When a user presses `s` or `q` from The Lineup.

**Suggested fix:** Document the context-specific Lineup bindings, or qualify the table as applying only to the main application screen.

```suggestion
### ⌨️ Keybindings

*(The following bindings apply only to the main application screen; in The Lineup, `s` skips the current title and `q` leaves The Lineup.)*
```
</issue_to_address>

Sourcery assessment

Approval pending. 1 finding to address first.

Blocking findings: README.md:186


Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

Comment thread README.md
@@ -181,22 +185,23 @@ You can also configure sync directly in your environment or `~/.config/netflix-n

### ⌨️ Keybindings

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: The keybindings table presents s as opening Preferences and q as quitting the application in every context, but the Lineup screen overrides s to skip the current title and q to leave the Lineup. Users following this table while in the Lineup perform different actions than documented.

Triggers: When a user presses s or q from The Lineup.

Suggested fix: Document the context-specific Lineup bindings, or qualify the table as applying only to the main application screen.

Suggested change
### ⌨️ Keybindings
### ⌨️ Keybindings
*(The following bindings apply only to the main application screen; in The Lineup, `s` skips the current title and `q` leaves The Lineup.)*

@codecov

codecov Bot commented Aug 22, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.27%. Comparing base (704fbd7) to head (9e71930).
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #34   +/-   ##
=======================================
  Coverage   87.27%   87.27%           
=======================================
  Files          25       25           
  Lines        2948     2948           
=======================================
  Hits         2573     2573           
  Misses        375      375           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant