Skip to content

Added: Documentation for AI safety and namespace configuration - #8

Merged
dennisdornon merged 2 commits into
mainfrom
alpha-bug-fixes-cont
Dec 19, 2025
Merged

dennisdornon merged 2 commits into
mainfrom
alpha-bug-fixes-cont

Conversation

@dennisdornon

@dennisdornon dennisdornon commented Dec 19, 2025 •

Copy link
Copy Markdown
Member

Summary

Adds documentation for the MAINWP_ABILITY_NAMESPACE configuration option and expands security documentation to address AI client behavior limitations.

Key Improvements

  • MAINWP_ABILITY_NAMESPACE now documented in README and configuration guide
  • Installation guide includes AI safety notice recommending backups before first use
  • Security guide covers dry-run previews for destructive operations
  • New section documents AI client limitations when following confirmation flows
  • Protective configuration examples for untrusted AI clients

Technical Notes

MAINWP_ABILITY_NAMESPACE was already implemented but undocumented. The namespace filtering section explains use cases for custom extensions and multi-vendor setups.

The AI client limitations section documents observed behaviors where clients skip confirmation flows or assume operations are safe. This is advisory documentation - the server mechanisms remain unchanged.

Version bumped to 1.0.0-alpha.20.

Testing

Documentation changes only. Verified markdown renders correctly.

Summary by CodeRabbit

  • New Features

    • Added namespace filtering capability for abilities via MAINWP_ABILITY_NAMESPACE environment variable.
  • Documentation

    • Added comprehensive configuration guide for namespace filtering and custom extensions.
    • Added AI safety notices covering backups, Safe Mode, and dry-run previews.
    • Enhanced security documentation with AI client limitations and best practices.
  • Chores

    • Version bump to 1.0.0-alpha.20.

✏️ Tip: You can customize this high-level summary in your review settings.

Document the ability namespace configuration option that was already
implemented but missing from documentation:

- Add MAINWP_ABILITY_NAMESPACE to README environment variables table
- Add new "Namespace Filtering" section to configuration.md with:
  - Default behavior explanation
  - Use cases for custom extensions, multi-vendor, and multiple instances
  - Security warning for empty namespace
- Installation guide now includes AI safety notice warning about
  LLM non-determinism and recommending backups before first use
- Security guide expanded with dry-run preview documentation
  showing how to preview destructive operations safely
- New section documenting AI client limitations when following
  confirmation flows, with recommended protective configurations
- Version bump to 1.0.0-alpha.20
@coderabbitai

coderabbitai Bot commented Dec 19, 2025 •

Copy link
Copy Markdown

Walkthrough

The release introduces namespace filtering configuration for ability management via a new MAINWP_ABILITY_NAMESPACE environment variable, along with comprehensive documentation updates covering configuration guidance, AI safety practices, and dry-run preview usage. Version bumped to 1.0.0-alpha.20.

Changes

Cohort / File(s) Summary
Configuration & Environment Variables
README.md, docs/configuration.md
Added new MAINWP_ABILITY_NAMESPACE environment variable with default value mainwp for filtering abilities by namespace. Updated configuration documentation with Namespace Filtering section including use cases and practical examples for custom extensions and multi-vendor dashboards.
Safety & Security Documentation
docs/installation.md, docs/security.md
Added comprehensive AI Safety Notice section in installation guide covering backup recommendations, Safe Mode usage, and dry-run previews. Expanded security documentation with "Using Dry-Run Previews" and "AI Client Limitations" sections explaining dry-run semantics, supported tools, and safety configuration examples.
Version Updates
package.json, src/index.ts
Bumped package version from 1.0.0-alpha.19 to 1.0.0-alpha.20. Updated SERVER_VERSION constant to match.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

  • Majority of changes are documentation additions with consistent patterns (editorial, not logic-altering)
  • Version bumps are trivial metadata updates
  • New environment variable addition is straightforward configuration metadata
  • No complex logic, control flow changes, or multi-component interactions introduced

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main changes: documentation additions for AI safety practices and namespace configuration, matching the PR's primary focus across README, installation, security, and configuration guides.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch alpha-bug-fixes-cont

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/security.md (1)

1-634: Address Prettier formatting issues flagged by CI.

The GitHub Actions CI pipeline detected Prettier formatting issues in this file. Please run the formatter to resolve:

prettier --write docs/security.md
🧹 Nitpick comments (2)
docs/configuration.md (1)

82-142: Excellent documentation of namespace filtering with practical examples.

The new section clearly explains the abilityNamespace setting, its default behavior, and includes relevant use cases for custom extensions and multi-vendor setups. The warning about empty namespaces exposing all abilities is particularly important for safety.

The markdownlint hints indicate that lines 100, 112, and 124 use bold text instead of headings for subsections. While this doesn't affect functionality, using proper heading levels would improve document structure:

🔎 Optional markdown structure improvement
-**Custom Extension Development**
+### Custom Extension Development

-**Multi-Vendor Dashboard**
+### Multi-Vendor Dashboard

-**Multiple MCP Server Instances**
+### Multiple MCP Server Instances
docs/installation.md (1)

7-32: Excellent addition of AI safety notice with clear recommendations.

The safety notice is appropriately placed at the beginning of the installation guide and provides actionable recommendations for users. The Known AI Client Limitations section sets proper expectations about AI client behavior and correctly identifies these as client-side issues rather than server bugs.

Line 11 could be more concise per the LanguageTool suggestion:

🔎 Optional wording improvement
-Large Language Models (LLMs) and AI agents are non-deterministic systems that can make mistakes, misinterpret instructions, or perform unintended actions. When connected to your MainWP Dashboard, an AI assistant has the ability to modify or delete sites, plugins, themes, clients, and tags.
+Large Language Models (LLMs) and AI agents are non-deterministic systems that can make mistakes, misinterpret instructions, or perform unintended actions. When connected to your MainWP Dashboard, an AI assistant can modify or delete sites, plugins, themes, clients, and tags.
📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between caa6600 and 2ea2d5a.

📒 Files selected for processing (6)
  • README.md (1 hunks)
  • docs/configuration.md (1 hunks)
  • docs/installation.md (1 hunks)
  • docs/security.md (3 hunks)
  • package.json (1 hunks)
  • src/index.ts (1 hunks)
🧰 Additional context used
🪛 GitHub Actions: CI
docs/security.md

[warning] 1-1: Prettier formatting issues detected in docs/security.md. Run 'prettier --write docs/security.md' to fix.

🪛 LanguageTool
docs/installation.md

[style] ~11-~11: The phrase ‘has the ability to’ might be wordy. Consider using “can”.
Context: ... your MainWP Dashboard, an AI assistant has the ability to modify or delete sites, plugins, themes...

(HAS_THE_ABILITY_TO)

🪛 markdownlint-cli2 (0.18.1)
docs/configuration.md

100-100: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)


112-112: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)


124-124: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

docs/security.md

181-181: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (5)
package.json (1)

3-3: LGTM! Version bump is consistent across the project.

The version increment to 1.0.0-alpha.20 aligns with the SERVER_VERSION update in src/index.ts and the documentation changes in this PR.

src/index.ts (1)

50-50: LGTM! Server version is consistent with package.json.

The version bump to 1.0.0-alpha.20 correctly matches the package.json version update.

README.md (1)

406-406: LGTM! Clear documentation of the new namespace filtering option.

The MAINWP_ABILITY_NAMESPACE environment variable is well-documented with default value and description. This aligns with the detailed explanation in docs/configuration.md.

docs/security.md (2)

136-153: Good addition of first-time setup recommendations.

The expanded Safe Mode section now includes practical guidance for first-time users to start with Safe Mode enabled and build confidence before enabling destructive operations. This aligns well with the safety recommendations in the installation guide.


355-424: Important documentation of AI client limitations.

The AI Client Limitations section appropriately documents observed behaviors where AI clients may not properly follow the confirmation flow. The clarification that these are client-side issues (not mainwp-mcp bugs) is important, and the protective configuration recommendations are practical.

Comment thread docs/security.md
Comment on lines +173 to +213
## Using Dry-Run Previews

Before executing any destructive operation, you can preview exactly what will be affected using the `dry_run` parameter.

### How It Works

Many destructive tools support `dry_run: true`, which simulates the operation without making any changes:

```
You: Delete the staging plugins, but show me what will happen first

AI: [Calls delete_site_plugins_v1(site_id: 3, plugin_slugs: ["debug-bar"], dry_run: true)]
Server returns preview:
{
"dry_run": true,
"would_delete": ["debug-bar/debug-bar.php"],
"sites_affected": 1
}

AI: If I proceed, this will delete the "debug-bar" plugin from site 3.
Should I continue?
```

### Tools Supporting Dry-Run

The following destructive tools support `dry_run: true`:

- `delete_site_v1` - Preview site deletion
- `delete_client_v1` - Preview client deletion
- `delete_tag_v1` - Preview tag deletion
- `delete_site_plugins_v1` - Preview plugin removal
- `delete_site_themes_v1` - Preview theme removal

### When to Use Dry-Run

- **Always** before bulk operations affecting multiple items
- When you're unsure about the scope of a deletion
- When training or learning the system
- Before any operation you can't easily reverse

---

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clear documentation of dry-run preview functionality.

The dry-run previews section provides practical examples and lists all tools that support this feature. The guidance on when to use dry-run is particularly helpful.

Line 181 has a fenced code block without a language specification. While this doesn't affect the content, it should specify the language for proper syntax highlighting:

🔎 Proposed fix
-```
+```text
 You: Delete the staging plugins, but show me what will happen first
 
 AI: [Calls delete_site_plugins_v1(site_id: 3, plugin_slugs: ["debug-bar"], dry_run: true)]
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

181-181: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents
In docs/security.md around lines 173 to 213, the fenced code block starting at
line 181 lacks a language tag; update the opening triple-backtick to include an
appropriate language identifier (e.g., text or bash) to enable proper syntax
highlighting, ensuring the block remains unchanged otherwise.

@dennisdornon
dennisdornon merged commit 2ea2d5a into main Dec 19, 2025
3 of 6 checks passed
@dennisdornon
dennisdornon deleted the alpha-bug-fixes-cont branch October 6, 2026 21:54
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