Make Chapter Reader contribution-ready for outside open-source contributors

[heyitschien]

Objective

Turn Chapter Reader from a public MIT-licensed repository into a welcoming, contribution-ready open-source project where outside contributors can understand the product direction, find appropriately scoped work, run the project, submit a pull request, and receive clear review expectations.

The repository is already public, MIT-licensed, and has a basic CONTRIBUTING.md. This issue should strengthen the contributor experience without changing the core product or opening uncontrolled access to main.

Product principles to preserve

All contribution infrastructure and proposed work must preserve:

• local-first operation;
• text remains on the user's machine;
• localhost binding to 127.0.0.1;
• offline TTS after required initial setup/downloads;
• no required cloud APIs, accounts, or API keys;
• simple Mac installation;
• calm, readable writing-review experience;
• focused, reviewable changes;
• maintainer approval before merge.

Open source means people may propose changes through forks and pull requests. It does not mean contributors receive direct write access or that every proposed feature must be accepted.

Inspect before editing

Read and validate the current:

• README.md
• CONTRIBUTING.md
• AGENTS.md
• LICENSE
• electron/README.md
• setup, install, verification, test, and CI commands
• branch-protection and current workflow configuration where accessible
• existing issue labels and issue/PR templates
• current open and closed issues to avoid duplication

Document the verified development and validation commands. Do not invent commands that do not work.

Required implementation

1. Add a visible contributions entry point

Add a concise Contributions welcome section or link near the useful upper portion of README.md.

It should explain in plain language:

• who may contribute;
• that contributors normally fork the repo and open a PR;
• where to find open contribution issues;
• where to read setup and contribution instructions;
• the core local-first/privacy boundaries;
• that focused bug fixes, accessibility, documentation, tests, and installation improvements are welcome.

Do not make the README substantially longer or distract from the user installation path.

Suggested direction:

Contributions are welcome. Start with a labeled issue, read CONTRIBUTING.md, work from a fork, and open a focused pull request. Chapter Reader stays local-first: no required cloud services, accounts, or API keys.

2. Expand CONTRIBUTING.md

Upgrade CONTRIBUTING.md into a complete but concise contributor guide containing:

• project purpose and contribution philosophy;
• contribution workflow: issue → fork → branch → change → validate → PR;
• supported development environments;
• exact setup commands;
• exact app/dev commands;
• exact test/verification/lint commands that actually exist;
• directory orientation;
• expected branch naming;
• commit guidance without enforcing unnecessary ceremony;
• PR size/scope expectations;
• what evidence to include in a PR;
• UI change screenshot expectations;
• bug reproduction expectations;
• macOS version, Apple Silicon/Intel, and TTS engine reporting;
• privacy/security boundaries;
• what is explicitly out of scope;
• how maintainers review, request revisions, accept, or decline changes;
• links to Code of Conduct, issue templates, PR template, AGENTS.md, and roadmap.

Keep instructions friendly to first-time contributors and usable by coding agents.

3. Add a Code of Conduct

Add CODE_OF_CONDUCT.md using a recognized concise standard such as Contributor Covenant, with appropriate maintainer/contact reporting information.

Do not invent a private security or moderation email. Use a verified public contact method or clearly indicate the appropriate GitHub reporting route.

4. Add GitHub issue templates

Create appropriate files under .github/ISSUE_TEMPLATE/, preferably YAML forms if supported cleanly:

• bug_report.yml
• feature_request.yml
• config.yml as needed

Bug reports should request:

• Chapter Reader version/commit;
• macOS version;
• Apple Silicon or Intel;
• Electron app or browser mode;
• TTS engine;
• reproducible steps;
• expected vs actual behavior;
• logs with sensitive text removed;
• screenshots where useful;
• privacy warning not to paste private manuscript contents.

Feature requests should request:

• user problem;
• proposed behavior;
• local-first/privacy implications;
• alternatives considered;
• willingness to contribute;
• clear scope.

Provide links to existing documentation and discussions/issues where appropriate.

5. Add a pull-request template

Create .github/pull_request_template.md with:

• summary;
• linked issue;
• user problem solved;
• change scope;
• validation performed;
• tested environment;
• screenshots for visual changes;
• privacy/local-only checklist;
• documentation changes;
• risks or limitations;
• confirmation that no secrets or private manuscript text were committed.

Keep it short enough that contributors will actually use it.

6. Add or validate community health files

Inspect whether these already exist and add only what is useful:

• SECURITY.md with a realistic vulnerability-reporting path;
• SUPPORT.md distinguishing usage help, bug reports, feature requests, and security concerns;
• .github/FUNDING.yml only if there is a real verified funding destination—otherwise do not create it.

Security guidance should explicitly warn contributors not to attach private manuscript contents, tokens, machine paths containing sensitive names, or unnecessary logs.

7. Create a concise public roadmap

Add a lightweight roadmap such as ROADMAP.md or docs/ROADMAP.md.

Organize it by themes rather than promises or dates:

• reliability and installation;
• accessibility and keyboard navigation;
• reading and playback experience;
• import/parsing quality;
• testing and contributor tooling;
• platform exploration.

Clearly distinguish:

• accepted direction;
• ideas under investigation;
• explicitly out of scope.

Do not promise Windows/Linux desktop support without validating architecture and maintenance cost. Platform expansion may be an investigation item.

8. Define contribution labels

Audit existing labels, then create or document a small coherent set:

• good first issue
• help wanted
• bug
• documentation
• accessibility
• testing
• macOS
• installation
• enhancement
• needs reproduction

Avoid creating a large label taxonomy. Record label meanings in CONTRIBUTING.md or the roadmap.

If repository tooling in this session cannot safely create labels, document the exact manual label setup in the PR description.

9. Prepare real starter issues

After validating the codebase, create 3–5 genuinely scoped contributor issues. Do not create placeholder issues or label large architectural work as beginner-friendly.

Candidate areas to validate:

• documentation or setup clarity improvement;
• test coverage for an isolated parser/helper;
• keyboard-navigation or screen-reader-label improvement;
• improved installation/error messaging;
• voice-preview or empty-state improvement;
• reproducible import handling edge case.

Each starter issue must include:

• user problem;
• verified current behavior;
• scope;
• likely files/areas;
• acceptance criteria;
• validation instructions;
• privacy constraints;
• difficulty/scope guidance;
• appropriate labels.

Use good first issue only when a new contributor can reasonably complete the work without understanding the entire architecture. Use help wanted for larger but bounded work.

Do not create these child issues until the repository has been inspected and the tasks are verified as real.

10. Validate CI and protected collaboration

Inspect the current CI and branch rules.

The desired collaboration model is:

Contributor fork
→ contributor branch
→ pull request
→ automated checks
→ maintainer review
→ merge only after approval

Verify or recommend:

• protected main;
• pull requests required before merge;
• relevant CI required;
• no direct contributor push access;
• focused reviewable changes;
• secrets unavailable to untrusted fork workflows unless explicitly safe.

Do not weaken existing branch protection. Do not add CI that exposes secrets to forked PRs.

If branch settings require manual GitHub configuration, document an exact manual checklist rather than pretending repository files changed the setting.

11. Fix contact-link consistency if encountered

The current Chapter Reader README may contain an older LinkedIn slug. If verified, update it to the canonical URL:

https://www.linkedin.com/in/chien-escalera-duong/

Do not make unrelated portfolio or branding changes.

Suggested initial contribution taxonomy

Use this as guidance, not as an instruction to create unverified issues:

Good first issue candidates

• documentation corrections;
• clearer error messages;
• small accessibility-label improvements;
• isolated tests;
• empty-state copy;
• verified import edge cases.

Help wanted candidates

• expanded keyboard navigation;
• playback-position persistence;
• additional engine abstraction;
• broader platform investigation;
• substantial UI workflow changes.

Never label a cross-platform rewrite, TTS engine replacement, or major architecture change as good first issue.

Scope boundaries

Do not:

• add cloud accounts, analytics, telemetry, or required APIs;
• upload user text;
• expose secrets;
• grant strangers direct write access;
• weaken branch protection;
• auto-merge outside contributions;
• promise response or release timelines;
• promise platform support that has not been validated;
• create a complicated governance bureaucracy;
• inflate the project into a commercial or enterprise claim;
• redesign the application as part of this issue;
• create starter issues that are not grounded in verified repository behavior.

Validation requirements

Before opening the implementation PR:

• README contribution entry point is visible and concise.
• CONTRIBUTING setup instructions work from a clean clone or are explicitly qualified.
• All documented commands exist and were validated where feasible.
• Issue templates render with valid GitHub syntax.
• PR template is concise and privacy-aware.
• Code of Conduct links and reporting path are valid.
• Roadmap distinguishes committed direction from exploration.
• Security/support guidance does not expose private data.
• All internal Markdown links resolve.
• No user manuscript contents, credentials, or machine-specific secrets are committed.
• Existing install and user documentation remain intact.
• Contribution flow remains compatible with forks.
• CI for untrusted forks does not receive secrets.
• Manual repository-settings steps are reported explicitly.
• Proposed starter issues are verified and correctly scoped.

Acceptance criteria

This parent issue is complete when:

1. A first-time contributor can understand the project and start locally without private guidance.
2. Contributors can choose the correct route for bugs, features, support, and security.
3. Pull requests arrive with enough environment and validation evidence for responsible review.
4. Product principles and out-of-scope changes are explicit.
5. The repository visibly welcomes contributions.
6. The maintainer retains review and merge control.
7. Three to five real, scoped contribution issues are available.
8. At least one issue is genuinely suitable for a first-time contributor.
9. CI and branch-protection expectations are documented and safe for forked PRs.
10. The work strengthens Chapter Reader as open-source portfolio evidence without overstating community adoption.

Next-session implementation sequence

1. Audit the current repository and community-health state.
2. Validate local development and test commands.
3. Propose the smallest coherent contribution-ready package.
4. Add/update community files and contributor documentation.
5. Validate Markdown, templates, commands, privacy, and links.
6. Open a focused PR referencing this issue.
7. After the infrastructure PR merges, create the verified starter issues with appropriate labels.
8. Report manual GitHub settings still required.
9. Do not claim community adoption until outside contributors actually participate.

PR handoff requirements

The implementation PR should summarize:

• files added or changed;
• contribution flow;
• commands validated;
• templates added;
• privacy/security safeguards;
• CI/branch-protection findings;
• labels created or requiring manual setup;
• starter issues created;
• deliberately deferred work.