Rewrite README benefit-first and add the docs guide set - #8
Merged
Conversation
Model the README on the MCP server repo: branded header, a why-a-CLI section, quick start with the Application Password walkthrough, and ability category tables. The deep content moves into six guides under docs/ (getting started, CLI reference, configuration, safety, chat, troubleshooting). Adds the 2026 logo lockup and two branded cards rendered with the social kit; card terminal content uses verified output strings only. Folds in the Codex documentation review fixes: - update-site-*, run-updates-*, and update-all-* are classified destructive by the name-based override, so the update examples now preview then confirm, with site_id_or_domain as the input key - preview wording no longer implies snapshot binding between dry-run and confirm (the documented TOCTOU limitation) - idempotent is defined as no additional effect, not a retry license - chat docs list everything the provider receives, including ability schemas sent as tool definitions - signal exits 130/143 documented; the Ctrl-C claim now matches what jobs watch actually reports; batch queueing is described as the Dashboard's decision with no client-side threshold - reference tables gain the previously missing flags and environment variables (login --name/--password, chat --api-key/--base-url, config show --verbose, jobs watch polling flags, MAINWP_LLM_API_KEY, XDG_CONFIG_HOME)
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
🚧 Files skipped from review as they are similar to previous changes (3)
WalkthroughThe README is reorganized around CLI onboarding and links to expanded documentation. New pages document command usage, configuration, getting started, chat mode, safety controls, and troubleshooting. ChangesCLI documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/cli-reference.md`:
- Line 32: Update the --url entry in the CLI reference to document both
supported HTTPS bypasses: MAINWP_ALLOW_HTTP=1 and the allowInsecureHttp
configuration setting. Keep the existing requirement and wording concise while
aligning with the contract documented in configuration.md.
In `@docs/getting-started.md`:
- Line 45: Update the long-term storage guidance near the OS keychain and `.env`
recommendation to state that mainwpcontrol does not load `.env` files
automatically; users must source the file or export MAINWP_APP_PASSWORD into
process.env before running the CLI.
In `@docs/safety.md`:
- Line 66: Update the interrupt behavior description in the job-watching
documentation so Ctrl-C and SIGTERM stop or cancel only the watch, while
explicitly stating that the Dashboard job continues running and remains
resumable by job ID; preserve the exit codes and job ID reporting.
- Line 74: Update the “Non-destructive writes run without confirmation” guidance
in docs/safety.md to explicitly exempt or qualify plugin updates according to
the ability-specific confirmation rules for run-updates-* and update-all-*.
Ensure the wording no longer contradicts the destructive-class guidance and
preserves confirmation requirements for abilities that require them.
In `@docs/troubleshooting.md`:
- Around line 72-74: Update the “Still stuck?” troubleshooting guidance to
explicitly instruct users to redact usernames, Dashboard URLs, site identifiers,
and tokens from command output and diagnostics before opening an issue, rather
than referring only to credentials. Preserve the existing request for the
command, debug stderr, and doctor output.
- Around line 15-19: Update the “Use environment variable auth instead” section
in docs/troubleshooting.md to remove the claim that this approach bypasses
keytar. Clarify that MAINWP_APP_PASSWORD supplies the credential while login
still stores it through the keychain, and distinguish this from the explicit
MAINWPCONTROL_NO_KEYTAR=1 bypass.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e826b302-be28-4ecf-9aaa-2804651f6cc0
⛔ Files ignored due to path filters (3)
docs/images/mainwp-control-fleet-from-the-terminal.pngis excluded by!**/*.pngdocs/images/mainwp-control-guard-rails.pngis excluded by!**/*.pngdocs/images/mainwp-control-logo-2026.pngis excluded by!**/*.png
📒 Files selected for processing (7)
README.mddocs/chat.mddocs/cli-reference.mddocs/configuration.mddocs/getting-started.mddocs/safety.mddocs/troubleshooting.md
All six verified against source before changing anything: - safety.md still said plugin updates run without confirmation in the guard-rails bullet; the name-based override classifies update-site-*, run-updates-*, and update-all-* destructive, so the bullet now lists only syncing and reconnecting - interrupt wording now says Ctrl-C/SIGTERM stop the watch while the Dashboard job keeps running - troubleshooting no longer claims env-var auth bypasses keytar; login still uses the keychain layer unless MAINWPCONTROL_NO_KEYTAR=1, so the recovery step sets both variables - issue-report guidance asks for usernames, Dashboard URLs, and site identifiers to be removed, not just credentials - getting-started notes the CLI does not read .env files itself - login --url documents both HTTP escape hatches (MAINWP_ALLOW_HTTP=1 and the allowInsecureHttp setting)
Local CodeRabbit run and an adversarial source-verification sweep over the full branch diff, both run before pushing: - the cron example alerts through a Slack webhook instead of an undefined notify command, matching the daily-health-check guide - the abilities table states it counts built-in mainwp/* abilities and explains why the Quick Start sample shows 87 on a Dashboard with extensions installed - shell completion examples use the real global install path via npm root -g - the preview guarantee wording drops the antithesis construction - profile delete is documented as interactive-only: no skip flag, and it cancels safely in non-interactive contexts
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.
Restyles the README on the pattern of the MCP server repo and splits the deep content into six guides under
docs/.What changed
getting-started,cli-reference,configuration,safety,chat,troubleshooting. Existingworkflows/andacceptance-testingare linked, untouched.Review fixes folded in
A Codex documentation review ran against the working tree; every accepted finding is in this diff:
update-site-*,run-updates-*,update-all-*) are classified destructive by the name-based override, so the examples preview then confirm, withsite_id_or_domainas the input key.jobs watchactually reports; batch queueing is described as the Dashboard's decision (no client-side threshold exists).Verification
npm pack --dry-run: 229 files, no strays;docs/stays out of the tarball, matching@mainwp/mcp. npmjs.com rewrites the README's relative links via therepositoryfield.Summary by CodeRabbit
mainwpcontrol chat), Configuration (profiles/credentials and environment variables), Safety (preview/confirm guardrails for destructive actions), and Troubleshooting (doctor-based diagnosis and common failure fixes).