docs: pre-release audit and documentation improvements

- Simplify CONTRIBUTING.md for open source contributors - Update version to 0.1.0 (Open Source) in overview - Clarify BYO-key requirement in UI docs - Expand open source explanation in docs/9 - Add comprehensive pre-public release audit notes
2025-12-24 09:43:51 +11:00
parent 79895100c0
commit 52602a06c4
5 changed files with 237 additions and 160 deletions
@@ -23,6 +23,6 @@ For more information, visit [ra-h.app](https://ra-h.app)

 ## Current Status

- **Version:** Beta (private distribution)
- **Platform:** Web-based (Next.js server)
- **Roadmap:** Native Mac application with user data migration
+- **Version:** 0.1.0 (Open Source)
+- **Platform:** Web-based (Next.js server, local-only)
+- **License:** MIT
@@ -76,7 +76,7 @@ RA-H uses a fixed 3-panel desktop layout optimized for knowledge work.
 3. **Workflows** - Available workflows (integrate)
 4. **Logs** - Activity feed (last 100 entries)
 5. **Analytics** - Token usage and cost breakdown
-6. **API Keys** - Configure Anthropic/OpenAI/Tavily keys (beta ships with embedded keys)
+6. **API Keys** - Configure your Anthropic/OpenAI/Tavily keys (required for operation)

 **Logs view:**
 - Table/action filtering
@@ -1,9 +1,30 @@
-# RA-H BYO-Key Plan (Future Work)
+# RA-H Open Source

-The production repo remains private and powers the packaged Mac app. A separate, minimal open-source project will be created later for users who want to run RA-H with their own API keys. That future repo will include:
+This is the open source, BYO-key (bring your own API keys) version of RA-H.

-1. Basic three-panel UI
-2. Local SQLite storage
-3. Simple Settings → API Keys experience (no Supabase/subscription backend)
+## What's Included

-No active work is happening in this repo toward that goal right now. Track progress in `docs/development/prd-private-repo-reset.md`.
+- Full three-panel UI (Nodes | Focus | Helpers)
+- Local SQLite storage with vector search
+- Complete agent system (ra-h, mini-rah, wise-rah)
+- All tools and workflows
+- Settings panel with API key management
+
+## What's Not Included
+
+- Mac app packaging (Tauri)
+- Supabase authentication
+- Subscription/payment system
+- Auto-updates
+
+## Relationship to Private Repo
+
+This repo is a **mirror** of the private `ra-h` repository. Features are developed privately and synced here periodically.
+
+- **Contributions welcome** - See [CONTRIBUTING.md](../CONTRIBUTING.md)
+- **Bug reports** - Open an issue on GitHub
+- **Feature requests** - Open an issue; major features are typically built in the private repo first
+
+## Setup
+
+See the main [README.md](../README.md) for installation instructions.
@@ -1,5 +1,167 @@
 # RA-H Open Source Porting Notes (2025-12-09)

+---
+
+## Pre-Public Release Audit & Recommendations (2025-12-15)
+
+This section documents the security audit findings and open-source best practice recommendations compiled before making the repository public.
+
+### Audit Summary
+
+| Category | Status |
+|----------|--------|
+| Credentials/API Keys | ✅ Clean - none found |
+| Private repo references | ⚠️ 1 issue to fix |
+| Supabase remnants | ✅ Clean - properly removed |
+| Sensitive business data | ✅ Clean |
+| Documentation completeness | ⚠️ Gaps to address |
+
+---
+
+### 🚨 BLOCKING ISSUES (Must Fix Before Public)
+
+#### 1. Stale Reference in `docs/9_open-source.md`
+**Line 9** references a non-existent internal doc:
+```
+Track progress in `docs/development/prd-private-repo-reset.md`.
+```
+**Fix:** Remove this line or replace with a public tracking mechanism (GitHub Issues).
+
+#### 2. Stale Version in `docs/0_overview.md`
+**Line 26** states: `**Version:** Beta (private distribution)`
+**Fix:** Update to `**Version:** 0.1.0 (Open Source)`
+
+#### 3. Outdated Key Reference in `docs/6_ui.md`
+**Line 79** mentions: `beta ships with embedded keys`
+**Fix:** Clarify this refers to the original private beta, not the BYO-key open source version.
+
+---
+
+### 📋 MISSING FILES (Industry Standard for Open Source)
+
+Based on [GitHub's Open Source Guides](https://opensource.guide/starting-a-project/) and [10up Best Practices](https://10up.github.io/Open-Source-Best-Practices/community/), these files are expected:
+
+| File | Purpose | Priority |
+|------|---------|----------|
+| `CONTRIBUTING.md` | How to contribute, PR process, code style | **High** |
+| `CODE_OF_CONDUCT.md` | Community behavior standards ([Contributor Covenant](https://www.contributor-covenant.org/)) | **High** |
+| `SECURITY.md` | How to report vulnerabilities privately | **High** |
+| `.github/ISSUE_TEMPLATE/` | Bug report & feature request templates | Medium |
+| `.github/PULL_REQUEST_TEMPLATE.md` | PR checklist and format | Medium |
+| `CHANGELOG.md` | Version history and changes | Medium |
+| `docs/TROUBLESHOOTING.md` | Common issues and solutions | Low |
+
+---
+
+### 🔐 SECURITY CHECKLIST
+
+Per [binbash pre-launch checklist](https://medium.com/binbash-inc/open-source-github-repository-pre-launch-checklist-4a52dbbe4af1) and [OpenSSF guidelines](https://github.com/ossf/wg-best-practices-os-developers):
+
+- [ ] **Run secret scanner** - Use [Gitleaks](https://github.com/gitleaks/gitleaks), [TruffleHog](https://github.com/trufflesecurity/trufflehog), or GitHub's built-in secret scanning
+- [ ] **Check git history** - Ensure no credentials in commit history (fresh repo helps)
+- [ ] **Enable branch protection** - Require PR reviews for `main` branch
+- [ ] **Add SECURITY.md** - Define vulnerability reporting process (e.g., security@yourdomain.com or GitHub Security Advisories)
+- [ ] **Review dependencies** - Run `npm audit` and document known vulnerabilities
+- [ ] **Add .gitignore review** - Ensure `.env*`, credentials, and local configs are excluded
+
+---
+
+### 📚 DOCUMENTATION GAPS
+
+Current docs are technically solid but missing contributor-facing content:
+
+| Gap | Recommendation |
+|-----|----------------|
+| No contribution guide | Create `CONTRIBUTING.md` with: setup instructions, code style, PR process, testing requirements |
+| No API reference | Consider auto-generating from code or adding `docs/api.md` |
+| No troubleshooting | Add common issues (SQLite rebuild, key validation errors) |
+| No architecture decision records | Optional but helpful for major decisions |
+| Numbered doc files unclear | Add `docs/README.md` explaining what each numbered file covers |
+
+---
+
+### 🏗️ RECOMMENDED FILE STRUCTURE
+
+```
+ra-h_os/
+├── README.md              ✅ exists
+├── LICENSE                ✅ exists (MIT)
+├── CONTRIBUTING.md        ❌ create
+├── CODE_OF_CONDUCT.md     ❌ create
+├── SECURITY.md            ❌ create
+├── CHANGELOG.md           ❌ create
+├── .github/
+│   ├── ISSUE_TEMPLATE/
+│   │   ├── bug_report.md
+│   │   └── feature_request.md
+│   └── PULL_REQUEST_TEMPLATE.md
+├── docs/
+│   ├── README.md          ❌ create (index of docs)
+│   └── ...existing docs...
+└── ...
+```
+
+---
+
+### 🔄 PRIVATE-TO-PUBLIC SYNC BEST PRACTICES
+
+Based on [Microsoft ISE's approach](https://devblogs.microsoft.com/ise/synchronizing-multiple-remote-git-repositories/) and [GitLab mirroring docs](https://docs.gitlab.com/user/project/repository/mirror/):
+
+**Current approach (manual sync) is correct for security.** Recommendations:
+
+1. **Document the sync process publicly** - The current reference to private repo workflow docs won't help public contributors understand when features land
+2. **Consider a ROADMAP.md** - Let the community know what's coming from the private repo
+3. **Tag releases** - Use semantic versioning (v0.1.0, v0.2.0) so users know when syncs happen
+4. **Divergence handling** - Document what happens if someone contributes to OS version (does it get merged upstream? Is OS version append-only from private?)
+
+---
+
+### 👥 GOVERNANCE MODEL
+
+For a project of this size with a private upstream, a **BDFL (Benevolent Dictator for Life)** model is appropriate per [Red Hat's governance guide](https://www.redhat.com/en/blog/understanding-open-source-governance-models):
+
+- You maintain final decision authority
+- Contributions are welcome but reviewed against private repo direction
+- Clear in CONTRIBUTING.md that this is a mirror, not a community-driven fork
+
+---
+
+### 🎯 PRIORITY ACTION ITEMS
+
+**Before going public (blocking):**
+1. Fix the 3 stale references listed above
+2. Run a secret scanner on the repo
+3. Create `SECURITY.md` with vulnerability reporting instructions
+4. Create basic `CONTRIBUTING.md`
+5. Add `CODE_OF_CONDUCT.md` (use Contributor Covenant template)
+
+**First week after public:**
+6. Enable GitHub branch protection on `main`
+7. Add issue templates
+8. Create `CHANGELOG.md` starting from v0.1.0
+9. Add `docs/README.md` explaining the docs structure
+
+**Ongoing:**
+10. Document sync cadence with private repo
+11. Consider adding CI (linting, type-check) via GitHub Actions
+12. Monitor for community contributions and establish response SLA
+
+---
+
+### 📖 REFERENCE SOURCES
+
+- [Starting an Open Source Project - GitHub Guides](https://opensource.guide/starting-a-project/)
+- [Open Source Pre-Launch Checklist - binbash](https://medium.com/binbash-inc/open-source-github-repository-pre-launch-checklist-4a52dbbe4af1)
+- [README Best Practices - jehna](https://github.com/jehna/readme-best-practices)
+- [Building Welcoming Communities - GitHub Guides](https://opensource.guide/building-community/)
+- [Leadership and Governance - GitHub Guides](https://opensource.guide/leadership-and-governance/)
+- [Understanding Open Source Governance - Red Hat](https://www.redhat.com/en/blog/understanding-open-source-governance-models)
+- [Synchronizing Multiple Git Repositories - Microsoft ISE](https://devblogs.microsoft.com/ise/synchronizing-multiple-remote-git-repositories/)
+- [OSS Security Checklist - Onboardbase](https://onboardbase.com/blog/oss-security/)
+- [CFPB Open Source Template](https://github.com/cfpb/open-source-project-template)
+
+---
+
 ## Agent Handover

 **What is this repo?** This is `ra-h_os`, the open source mirror of the private `ra-h` application. It's a BYO-key (bring your own API keys) version without Mac packaging, Supabase auth, or subscription features.