Skip to content

📝 Improve README onboarding and self-hosting guidance#256

Merged
baealex merged 2 commits into
mainfrom
baealex/audit-readme-quality
Jul 11, 2026
Merged

📝 Improve README onboarding and self-hosting guidance#256
baealex merged 2 commits into
mainfrom
baealex/audit-readme-quality

Conversation

@baealex

@baealex baealex commented Jul 11, 2026

Copy link
Copy Markdown
Owner

🎯 Goal

  • Make the README a trustworthy, project-specific entry point for evaluating and running Ocean Brain.
  • Align setup, storage, recovery, MCP, and development guidance with current behavior.

🛠️ Core Changes

  • Reframe the introduction around Ocean Brain's editor-first connected-note workflow and clarify the live demo's boundaries.
  • Add a high-resolution product capture with realistic workspace data, typed properties, inline references, and backlinks.
  • Replace the quick start with loopback-safe npx and password-protected Docker examples.
  • Document the shared-workspace model, runtime settings, data paths, backups, recovery retention, MCP setup, and development requirements.
  • Remove the stale source-production path and present repository commands as a development workflow.

🧠 Key Decisions

  • Keep the README focused on user workflows and operational boundaries instead of exhaustive feature or MCP tool inventories.
  • Use safe copy-paste defaults and clearly separate packaged self-hosting from source development.
  • Use the existing Ocean Brain icon, an authentic product screen, and concise project-specific language instead of badges or generic product claims.

🧪 Verification Guide

How to verify

  1. Render README.md and review its icon, product screenshot, internal navigation, tables, Bash examples, and MCP JSON example.
  2. Run pnpm check:encoding, pnpm lint, and pnpm test:ci.
  3. Run pnpm type-check, pnpm build, and git diff --check.

Expected result

  • The README presents safe local defaults, accurate storage and recovery details, and the current MCP setup flow.
  • The product screenshot stays legible at README width and shows the editor-first workflow without browser or development chrome.
  • Encoding, lint, all tests, type-check, build, and diff checks pass.
  • README Bash and JSON syntax checks pass, and all local and external links resolve.

✅ Checklist

  • Lint completed
  • Type-check completed
  • Tests completed
  • Documentation updated

@baealex baealex merged commit 4469ff6 into main Jul 11, 2026
4 checks passed
@baealex baealex deleted the baealex/audit-readme-quality branch July 11, 2026 06:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant