docs: align user docs and repo docs with implementation#7
Merged
Conversation
Reviewed all user-facing docs (src/docs/) and repo-level docs against the actual code and fixed inaccuracies surfaced by the audit: - README.md: fix CI badge URL (deploy.yml → ci.yml); replace tag-based "Deployment" section with the actual push-to-main flow; list all 5 D1 tables instead of 2. - RELEASE.md: delete (described a tag-based release process that does not exist; push-to-main auto-deploys per ci.yml). - CLAUDE.md: add missing scripts (lint, validate, install:hooks); fix table count (4 → 5, add config_revisions); correct packages enrichment description; cross-link AGENTS.md + docs/HARNESS.md. - src/docs/api-reference.md: rewrite to match the actual handlers — every endpoint shape (request/response/status), correct rate limits (CONFIG_READ/WRITE/SEARCH all 30/min), remove fabricated X-RateLimit-* headers, split dashboard /api/configs/:slug from CLI /:username/:slug/config, fix install endpoint Content-Type. - src/docs/config-options.md: document validation limits — custom_script 10K, dotfiles_repo HTTPS + 500, alias 2-20 chars + reserved words, packages 500/200; fix base_preset default; document snapshot.macos_prefs[].host. - src/docs/personal.md: remove false "Dotfiles cloned and linked" line from the first install transcript (no dotfiles_repo configured yet). - src/docs/teams.md: correct visibility guidance — private is owner-only (403 for other users), teams should use unlisted. - src/docs/snapshot.md: "Before installing" → "Before applying" in the restore section. - src/docs/what-is-openboot.md: spaced em-dash for style consistency. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
6 tasks
fullstackjam
added a commit
that referenced
this pull request
May 17, 2026
Separates concerns so badges reflect reality: - ci.yml (name: CI) — runs on PR + push to main, plus repository_dispatch for contract updates. One job (check): type check, tests + coverage, build, contract schema validation. - deploy.yml (name: CD) — triggered via workflow_run after CI succeeds on main. Builds, applies D1 migrations, deploys via wrangler-action, runs the health check + smoke test + post-deploy contract round-trip. README now shows two badges (CI + CD); previously one ambiguous "CI / Deploy" workflow had a single badge that didn't tell the reader whether the issue was a failed test or a failed deploy. Also addresses post-merge review findings on #7: - api-reference.md List Configs example: drop user_id, custom_script, dotfiles_repo, forked_from, created_at — getUserConfigs does not SELECT them (see src/lib/server/db/configs.ts:80). - api-reference.md Get Current User: add avatar_url back — getCurrentUser selects it (src/lib/server/auth.ts:58,70). - api-reference.md install endpoint auth note: replace the vague "browser-friendly auth flow" mention with the actual behavior (404 on the page route for non-owners; no interactive prompt). HARNESS.md: point the post-deploy rows at deploy.yml; clarify the push-to-main → workflow_run → deploy chain in the "not in the harness" section. required-checks.txt is unchanged: `check` and `validate-commits` still exist as job names in ci.yml and conventional-commits.yml. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Audit of all docs (
src/docs/+ repo-level) against the actual code; fixed every inaccuracy found.deploy.yml→ci.yml); replace fictional tag-based "Deployment" section with the actual push-to-main flow; list all 5 D1 tables.ci.yml.lint,validate,install:hooks); fix table count (4 → 5, addconfig_revisions); correct packages-enrichment description; cross-link AGENTS.md + docs/HARNESS.md.CONFIG_READ/CONFIG_WRITE/SEARCHall 30/min); removed fabricatedX-RateLimit-*headers (onlyRetry-Afteris sent); split dashboard/api/configs/:slugfrom CLI/:username/:slug/config; fixed install endpointContent-Type.custom_script10K,dotfiles_repoHTTPS + 500,alias2–20 chars + reserved words,packages500/200); fixbase_presetdefault (developer, not "none"); documentsnapshot.macos_prefs[].host.dotfiles_repois configured at that point).privateis owner-only (403 for other users), so teams should useunlisted.Test plan
npm run check— 0 errors (pre-existing warnings only)npm run validateran inpre-pushhook on push/docs/api-reference,/docs/config-options,/docs/snapshotrender correctly on openboot.devOut of scope
Findings that live in the Go CLI repo (
openbootdotdev/openboot) and need to be verified there, not here:bash -s -- snapshotinvocation inquick-start.md/snapshot.md— depends on upstreamscripts/install.sh.OPENBOOT_*env vars listed inenv-vars.md.faq.md.dotfiles-shell.md.Also flagged but not fixed in this PR:
src/lib/server/validation.ts:30— comment claims a dotfiles host whitelist, but the regex doesn't enforce one. Code-side mismatch, separate fix.🤖 Generated with Claude Code