Skip to content

docs: rewrite README as a landing page and move deep guides to docs/ - #82

Merged
darkzOGx merged 1 commit into
masterfrom
docs/readme-rewrite
Oct 20, 2026
Merged

darkzOGx merged 1 commit into
masterfrom
docs/readme-rewrite

Conversation

@darkzOGx

Copy link
Copy Markdown
Owner

Summary

The README had grown to 628 lines. It opened with about 40 lines of release notes, so the pitch and Quick start were buried under about 15 long feature walkthroughs. This rewrites it as a landing page (313 lines) and moves the detail into docs/ without dropping any of it.

New README order: what it is → why it's different → Quick start → how it works → features (one line each, linking to the guide) → providers → configuration → automation → API → troubleshooting → project structure → extending → contributing / built by / license.

Accuracy fixes found while rewriting

  • Missing install step: npm install never downloads Playwright's Chromium, and the local slideshow needs it to render. Quick start and troubleshooting now include npx playwright install chromium.
  • YouTube setup: adds the OAuth test user step behind Error 403: access_denied (Discussion Denied at the YouTube stage #25), and enabling the YouTube Analytics API, which the analytics agent calls.
  • Media pipeline: the old diagram showed narration "fallbacks". In fact the first configured TTS provider (ElevenLabs, OpenAI, then Gemini) is used, and images fall back between OpenAI and Gemini.
  • Extending: the old example imported @anthropic-ai/sdk (not a dependency) from a file that doesn't exist, and the "custom content types" snippet pointed at a contentTypes object that isn't in the code. Both are replaced with the real extension points.
  • Debug logging: the tip used DEBUG_MODE, which nothing reads. It now uses LOG_LEVEL and NODE_ENV.
  • Project structure and schedule: now match the repo and schedules/daily-automation.js.
  • Troubleshooting: adds the issues raised in Discussions: OAuth 403, missing images, ElevenLabs 400, sharp on Termux.

Moved, not removed

  • docs/features.md: every feature walkthrough from the old README, lightly edited, plus the full automation schedule and the privacy notes.
  • docs/api.md: the curl examples, plus a reference table for all routes in index.js.
  • Release notes: all already in CHANGELOG.md.

The launch-gate comment (a real dashboard demo only) is kept, and the mascot image stays out, as decided in 0fca2df. The ConstructionBids.ai line moves from Acknowledgments to "More from darkzOGx".

Test plan

  • Every relative link and #anchor in README.md, docs/features.md and docs/api.md resolves (checked with a script)
  • Every documented route exists in index.js; experiment and automation actions match the handlers
  • Dashboard labels referenced (Run verified check, Activate & run now, Pipeline, and others) exist in the UI
  • npm run lint passes

🤖 Generated with Claude Code

- Lead with what the project does, why it is different, and a Quick
  start; release notes now live only in CHANGELOG.md.
- Add the missing `npx playwright install chromium` step (npm install
  does not download it, and the slideshow renderer needs it) and the
  OAuth test-user step behind 403 access_denied sign-ins.
- Correct the media fallback description, the extension examples
  (real provider presets instead of an uninstalled SDK and a nonexistent
  contentTypes object), the project structure, the schedule, and the
  troubleshooting table, which now covers the issues raised in
  Discussions.
- Move the feature walkthroughs to docs/features.md and the API
  examples plus a full route reference to docs/api.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@darkzOGx
darkzOGx merged commit 24f9cb5 into master Oct 20, 2026
1 check passed
@darkzOGx
darkzOGx deleted the docs/readme-rewrite branch October 20, 2026 05:28
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