Skip to content

Split the README into docs/, add a features list and CONTRIBUTING.md - #50

Merged
tommusrhodus merged 5 commits into
trunkfrom
docs/docs-folder-and-contributing
Nov 20, 2026
Merged

tommusrhodus merged 5 commits into
trunkfrom
docs/docs-folder-and-contributing

Conversation

@tommusrhodus

Copy link
Copy Markdown
Contributor

What

The README was one long page. Its sections now live in docs/, one page per subject, and the README says what Oatcake does, how to install it, and links to each page and its main sections.

  • docs/features.md (new): everything Oatcake does today, grouped, each item linking to where it's described.
  • CONTRIBUTING.md (new): setting up, trying a build safely, making a change, commits and pull requests, releases, licence.
  • docs/how-it-works.md: the five steps are headings now, with subsections (live transcript, calls noticed, the menu bar, saving without Who's who, reading and editing, regenerate and templates, to-dos, organising meetings, Rename Speakers) so they can be linked to.
  • docs/settings.md: rewritten pane by pane (General, Calendar, People, Transcription, Summaries, Storage, Updates), with every control in the app.
  • docs/install.md, importing.md, models.md (speech models, language model, accuracy), updates.md, security.md, moving-from-electron.md, whats-next.md, development.md (build, trying a build, layout) and releasing.md carry the rest of the old README.

Checked against the code

Not described before:

  • View › Bigger Text, Smaller Text and Actual Size (⌘+, ⌘-, ⌘0)
  • folders inside folders and the folder right-click menu
  • Your name and Meetings folder settings
  • the menu bar's menu (New Recording…, Open Oatcake, Quit Oatcake)
  • what closing the window does while work is going
  • an unreadable config.json
  • Cancel and Close on the live screen, Put back and Undo in Who's who, Ask's Stop and Hide
  • the installer's OATCAKE_INSTALL_DIR and OATCAKE_REINSTALL, and bundle.sh's signing variables

Corrected:

  • Running the installer again doesn't reinstall the version you have (it opens it); install.sh's own comment said the same, and is fixed too.
  • The voice models download when the call is processed, not at the first recording.
  • Prep notes are kept for up to 30 days.
  • The open to-dos come from the latest earlier meeting in the folder that has any.
  • The no-call-audio notification only comes while a calling app has the microphone.
  • A recorder that never starts is noticed after 15 seconds.
  • Ask sends the parts of a transcript nearest the question when the whole call is too long, and favours meetings in the same folder rather than earlier ones only.
  • Upcoming shows up to six events and leaves out all-day ones; clicking an event opens New recording rather than starting one.
  • An update waits for a summary being written or an import, not for "saving".
  • Button labels (Import…, Forget…, Restore Default…, Keep call audio after saving) and the version.sh example.
  • "A summary as soon as a call has been processed" is off What's next: Settings › General › After a call does it.
  • The Rename Speakers example read "John" → "John Allen", half of an old name; it's "John Smith".

No code changes apart from install.sh's comment. Every relative link and section anchor in the docs was checked to resolve.

🤖 Generated with Claude Code

tommusrhodus and others added 4 commits November 20, 2026 12:48
…IBUTING.md

The README now says what Oatcake does, how to install it, and links to a page for each
part: features, install, how it works, settings (pane by pane), importing, models, updates,
security, moving from Electron, what's next, development and releasing.

Checked against the code on the way:
- Features that weren't described: View's text size, folders inside folders, Your name,
  Meetings folder, the menu bar menu, closing the window while work is going, an unreadable
  config.json, the installer's OATCAKE_INSTALL_DIR and OATCAKE_REINSTALL, bundle.sh's
  signing variables.
- Corrections: running the installer again doesn't reinstall the same version; the voice
  models download when the call is processed; prep notes last 30 days; the open to-dos come
  from the latest meeting that has any; the no-call-audio notification needs a calling app on
  the mic; a recorder that never starts is noticed after 15 s; Ask trims a transcript too long
  to send; Upcoming shows up to six events and no all-day ones; clicking an event opens New
  recording; an update waits for summaries and imports; labels and the version example.
- "A summary before Who's who" is off What's next: After a call does it.
- "John Allen" in the Rename Speakers example is "John Smith".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@t51eng-poseidon

t51eng-poseidon Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

🔱 Poseidon started reviewing this PR — central run.

@t51eng-poseidon t51eng-poseidon 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.

🔱 Poseidon Review

Summary — Moves the README's sections into docs/, adds docs/features.md and CONTRIBUTING.md, and corrects install.sh's header comment. This is low risk: the only code-adjacent change is a comment, and it matches the script's OATCAKE_REINSTALL logic.

Walkthrough

  • ✨ New — docs/features.md and CONTRIBUTING.md
  • 📝 Docs — README split into per-subject pages under docs/, with corrections checked against the code
  • 🔧 Chore — install.sh header comment now says a rerun upgrades, and OATCAKE_REINSTALL=1 reinstalls

💡 Nitpicks (3)
  • install.sh:L30 — The comment still points to README › Releasing. That section now lives in docs/releasing.md.
  • .github/workflows/release.yml:L11 — # Secrets, in the release environment (README › Releasing): is stale for the same reason. Point it at docs/releasing.md.
  • Package.swift:L9 — see README › Speech models should now be docs/models.md › Speech models.

🤖 Prompt for AI agents — fix all findings
Verify each finding against the current code and only fix it if
needed.

Nitpicks:
In `install.sh`:
- Line 30: Update the comment above `CERTIFICATE=`, which reads
  `# The "Oatcake Release" certificate every release is signed with
  (README › Releasing)`. This PR moved the Releasing section out of
  README.md into docs/releasing.md, so the reference now points
  readers at a heading that no longer exists. Replace
  `README › Releasing` with `docs/releasing.md`. Keep the rest of
  the comment and the `CERTIFICATE` fingerprint value unchanged.

In `.github/workflows/release.yml`:
- Line 11: Update the comment `# Secrets, in the release environment
  (README › Releasing):`. The Releasing section, which lists those
  secrets, moved to docs/releasing.md in this PR, so the README
  reference is stale. Replace `README › Releasing` with
  `docs/releasing.md`. Change only the comment text; leave every
  workflow key and the secrets list below it as they are.

In `Package.swift`:
- Line 9: Update the comment ending `Pinned exactly; see README ›
  Speech models.`. The Speech models section moved from README.md
  to docs/models.md (`## Speech models`) in this PR, so the pointer
  no longer resolves. Replace it with `see docs/models.md › Speech
  models`. Keep the dependency declaration and its exact version
  pin unchanged.

ℹ️ Review info
  • Commit: 5d0498b
  • Files reviewed: CONTRIBUTING.md, README.md, docs/development.md, docs/features.md, docs/how-it-works.md, docs/importing.md, docs/install.md, docs/models.md, docs/moving-from-electron.md, docs/releasing.md, docs/security.md, docs/settings.md, docs/updates.md, docs/whats-next.md, install.sh
  • Files skipped: none
  • Model: claude-opus-5-5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@t51eng-poseidon t51eng-poseidon 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.

🔱 Poseidon Review

No issues found on this pass. The new commit updates the three stale README › pointers, and no README › references are left in the repo.


♻️ Previously flagged

Resolved

  • ✅ install.sh:L30 — comment now points to docs/releasing.md
  • ✅ .github/workflows/release.yml:L11 — secrets comment now points to docs/releasing.md
  • ✅ Package.swift:L9 — now see docs/models.md › Speech models, which resolves to ## Speech models

ℹ️ Review info
  • Commit: c27a2ec
  • Files reviewed: .github/workflows/release.yml, Package.swift, install.sh (delta since 5d0498b); CONTRIBUTING.md, README.md, docs/development.md, docs/features.md, docs/how-it-works.md, docs/importing.md, docs/install.md, docs/models.md, docs/moving-from-electron.md, docs/releasing.md, docs/security.md, docs/settings.md, docs/updates.md, docs/whats-next.md (unchanged since prior review)
  • Files skipped: none
  • Model: claude-opus-5-5

@tommusrhodus
tommusrhodus merged commit 0766143 into trunk Nov 20, 2026
3 checks passed
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