feat: explain how to read the topic map and the document map

[maehr]

Summary

Closes #49.

• The Overview tab gets a How to read the topic map accordion below the map.
• The Documents tab gets a How to read the document map accordion below the map.
• The texts say what a circle or a point is, how the app places it, how to read a distance, and that the axes carry no meaning.
• The document map text names the truncated SVD and the sample limit of 4,000 documents. The limit is now the constant DOCUMENT_SAMPLE_LIMIT, so the text stays true.
• Both charts get a description for assistive technology.

Test

• Unit tests check the axis note, the limit, and the descriptions.
• Browser test: the accordion opens and shows the text.

Stack

1. chore(deps): refresh the lockfile for marimo 0.25 #51 chore/deps → main
2. test: run the notebook with a fitted result #52 test/notebook-gate
3. feat: show the topic number on each bubble #53 feat/topic-numbers
4. feat: explain how to read the topic map and the document map #54 feat/map-explanations
5. feat: add the figures to project.zip #55 feat/zip-figures
6. chore: delete PLAN.md #56 chore/release-prep

Merge from the bottom up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EsEUVKgZPLky1kHXnU2aBW

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 26 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 2ca633a3-92ed-47a8-9d13-16ddd91c14ef

📥 Commits

Reviewing files that changed from the base of the PR and between 7cd3af4 and 8b6fac6.

📒 Files selected for processing (4)

• SPECS.md
• app.py
• simple_topic_modeling/plots.py
• tests/test_plots.py

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot review overview

🟡 Changes recommended

The topic-distance guidance is overstated, and the document-map accessibility description is inaccurate in long-text mode.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Correct assistive description for ordered-text results · New
• Clarify centroid distance as a projection tendency · New

What changed in this PR

Adds user-facing guidance and accessible descriptions for topic and document maps.

Changes:

• Adds explanatory accordions below both maps.
• Centralizes the 4,000-document sampling limit.
• Tests map guidance and chart descriptions.

File	Description
app.py	Adds map guidance accordions.
simple_topic_modeling/​plots.py	Adds guidance, descriptions, and sampling constant.
SPECS.md	Documents the new guidance.
tests/​test_plots.py	Tests guidance and descriptions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[maehr]

Fixed in 9c3fd02. The description now says "one document, or one segment of a long text".

[maehr]

Fixed in 9c3fd02. The guide now describes the distance as a tendency: a topic has most of its weight in one part of the document map, and one document can still hold two distant topics.

[maehr]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.