Update docs

Author: LC43

docs/MCP.md

@@ -109,11 +109,35 @@ Saltus reuses WordPress capability checks such as:
 | Settings updates | `manage_options` |
 | Term creation | taxonomy edit/manage capability |
 
-REST routes are also gated by model configuration. The master `show_in_rest` option acts as both the WordPress core registration gate and the Saltus REST gate. Each Saltus feature (meta, settings, duplicate, export, reorder) can be independently enabled or disabled using a `show_in_rest` flag in its own config section within the model's `config` key. The `models` and `health` capabilities are always enabled when `show_in_rest` is not false for that model (or always, for health).
+REST routes and MCP tools are gated by model configuration.
 
-Similarly, MCP tools are gated by the `mcp_tools` master option at the model level, and each feature can be independently gated with `show_in_mcp` in its config section. When `mcp_tools` is absent or false, no MCP tools are generated for that model. When `mcp_tools` is true, all features are enabled for MCP unless a feature's `show_in_mcp` is explicitly `false`.
+### Master Options (Model Level)
 
-Enable all Saltus REST-backed capabilities for a model:
+At the model level, two master options in the `options` array control access:
+- **`show_in_rest`**: Controls whether model-scoped REST routes (and consequently MCP tools) are registered. If explicitly set to `false`, all model-scoped REST and MCP capabilities for the model are disabled. Defaults to `true` (if omitted or not `false`).
+- **`mcp_tools`**: Must be set and truthy (e.g., `true`) in model options to enable any MCP tools for that model.
+
+The framework-scoped health capability (`health` ability / REST route) is independent of per-model opt-in and is always available. The `models` capability is always enabled for a model as long as its `show_in_rest` is not `false` (or always, for MCP, if `mcp_tools` is enabled).
+
+### Feature-Level Gating
+
+Each individual framework capability can be gated in the model's `config` array. They map to specific configuration sections:
+- **Meta (`meta`):** `'meta'` key (root level of `config`)
+- **Settings (`settings`):** `'settings'` key (root level of `config`)
+- **Duplicate (`duplicate`):** `'duplicate'` key (nested under `config.features.duplicate`)
+- **Export (`export`):** `'single_export'` key (nested under `config.features.single_export`)
+- **Reorder (`reorder`):** `'drag_and_drop'` key (nested under `config.features.drag_and_drop`)
+
+### Resolution Rules
+
+For each feature/capability configuration section:
+1. **Omitted (Null):** If a capability config section is omitted from the model configuration, the feature defaults to **enabled** for both REST and MCP.
+2. **Boolean Value:** If defined as a simple boolean (e.g., `'meta' => false` or `'features' => ['duplicate' => false]`), it acts as a joint gate. A value of `false` disables both REST and MCP for that capability; a value of `true` enables both.
+3. **Array Value:** If defined as an array, REST and MCP gating can be configured independently:
+   - **REST Route Gating:** Governed by the `show_in_rest` key in the section array. If the key is omitted, REST is **enabled** (`true`). If present, it resolves to its boolean value.
+   - **MCP Tool Gating:** Governed by the `show_in_mcp` key in the section array. If the key is omitted, MCP is **enabled** (`true`). If present, it resolves to its boolean value.
+
+Enable all Saltus REST-backed and MCP capabilities for a model:
 
 ```php
 return [
@@ -126,7 +150,7 @@ return [
 ];
 ```
 
-Enable REST for all features but block MCP for specific features:
+Example showing various feature-level configurations:
 
 ```php
 return [
@@ -137,37 +161,28 @@ return [
 		'mcp_tools'    => true,
 	],
 	'config'  => [
+		// 1. Array style: enabled for REST but disabled for MCP
 		'meta'     => [
 			'show_in_rest' => true,
 			'show_in_mcp'  => false,
 		],
-		'settings' => [
-			'show_in_rest' => true,
-		],
+		// 2. Boolean style: disabled for both REST and MCP
+		'settings' => false,
+
 		'features' => [
+			// 3. Array style: enabled for REST, and defaults to enabled for MCP
 			'duplicate'     => [
 				'show_in_rest' => true,
 			],
-			'single_export' => [
-				'show_in_rest' => true,
-			],
-			'drag_and_drop' => [
-				'show_in_rest' => true,
-			],
+			// 4. Omitted config for single_export and drag_and_drop:
+			// both default to enabled for REST and MCP
 		],
 	],
 ];
 ```
 
 If `show_in_rest` is explicitly `false`, Saltus does not expose model-scoped REST or MCP routes for that model. The health ability is framework-scoped and remains independent of per-model opt-in.
 
-Config section keys:
-- `meta` — top-level key in `config`
-- `settings` — top-level key in `config`
-- `duplicate` — nested under `config.features.duplicate`
-- `single_export` — nested under `config.features.single_export`
-- `drag_and_drop` — nested under `config.features.drag_and_drop`
-
 ## Available Abilities
 
 <!-- BEGIN AUTO-GENERATED MCP ABILITIES -->

docs/ROADMAP.md

@@ -9,7 +9,7 @@
 - PHPStan Level 7 clean across the configured analysis set as of 2026-07-02, including the asset loading helper path
 - MCP v1 refactoring complete: per-tool REST dispatch, RestBackedToolInterface, ToolContributor, @phpstan-type AbilityDefinition
 - MCP namespace/category/prefix now filterable via MCPConfig utility class (saltus/framework/mcp/namespace, saltus/framework/mcp/ability_category, saltus/framework/mcp/ability_prefix)
-- MCP/REST capability gating refactored: McpPolicy class with mcp_tools/show_in_mcp gating; ModelRestPolicy switched from saltus_rest array to per-feature config-section model (config.meta.show_in_rest)
+- MCP/REST capability gating refactored: McpPolicy class with mcp_tools/show_in_mcp gating; ModelRestPolicy switched from saltus_rest array to per-feature config-section model (using show_in_rest and show_in_mcp gates)
 - Legacy refactoring: inline REST controller logic extracted into shared service classes (SaltusSingleExport, MetaFieldProvider, ReorderPostsService, SettingsManager) wired into both REST controllers and MCP tools — resolved 2026-07-03
 - Conditional registration fix: `is_needed()` gate bypass for RestRouteProvider/ToolContributor registries via two-pass approach in `Core`, ensuring REST routes always appear in WP-REST index even before `REST_REQUEST` is defined — resolved 2026-07-06
 - 250 PHPUnit tests passing (669 assertions), PHPStan Level 7 clean across the configured analysis set
@@ -397,3 +397,128 @@ frontend:
 ## Tracking
 - Check GitHub Issues for active sprint items.
 - Active development on `feature/mcp-v1` branch.
+
+
+
+//// new
+• Current state: Saltus already has the “external agent connects to WordPress
+  and modifies content through governed abilities” piece partly implemented.
+  What it does not appear to have yet is a first-class “context control center”
+  model or a mandatory editorial approval queue for agent writes.
+
+────────────────────────────────────────────────────────────────────────────────
+
+• For Saltus, that translates less like “Drupal AI” and more like a WordPress-
+  native AI governance layer for CPT-driven plugins.
+
+  Saltus already has the foundation: model-defined CPTs, REST routes, MCP/
+  Abilities tools, capability checks, audit logging, rate limits, health checks,
+  and per-model mcp_tools / show_in_mcp gates. The missing higher-level product
+  layer would be this:
+
+  Context Control Center
+
+  A Saltus model/config area where a plugin defines:
+
+  - brand voice
+  - field-level writing rules
+  - audience profiles
+  - taxonomy/content standards
+  - allowed statuses
+  - forbidden actions
+  - required review rules
+  - per-CPT AI instructions
+
+  In Saltus terms, this could live as model config, for example:
+
+  'options' => [
+      'show_in_rest' => true,
+      'mcp_tools' => true,
+  ],
+  'config' => [
+      'ai_context' => [
+          'brand_voice' => 'Clear, practical, expert, no hype.',
+          'audiences' => ['developers', 'site editors'],
+          'rules' => [
+              'never_publish_directly' => true,
+              'require_human_review' => true,
+              'preserve_technical_accuracy' => true,
+          ],
+      ],
+  ]
+
+  Then MCP tools like create_post, update_post, update_settings, and
+  update_meta_fields would receive this context before executing or expose it
+  through a new tool like saltus/get-context.
+
+  Inside AI
+
+  This would mean AI operating from inside WordPress admin.
+
+  Examples:
+
+  - AI buttons beside metabox fields
+  - “Improve title”
+  - “Summarize this CPT entry”
+  - “Generate excerpt from meta”
+  - “Validate against brand rules”
+  - “Suggest taxonomy terms”
+  - “Prepare draft update”
+
+  The key point: inside AI would still use Saltus models and WordPress
+  permissions. It should not bypass CPT config, field schemas, validation, or
+  post status rules.
+
+  Outside AI
+
+  This maps directly to Saltus MCP/Abilities.
+
+  External agents such as Codex, Claude Desktop, Cursor, or custom automation
+  clients connect to WordPress and call:
+
+  - saltus/list-models
+  - saltus/get-model
+  - saltus/list-posts
+  - saltus/get-post
+  - saltus/create-post
+  - saltus/update-post
+  - saltus/update-settings
+  - saltus/get-meta-fields
+
+  Saltus already has this architectural direction. The next step would be adding
+  stronger editorial governance around mutating tools.
+
+  Editorial Review
+
+  Right now, agent writes can be permission-gated and audited. To match the idea
+  you quoted, Saltus would need an approval layer:
+
+  - agent proposes a change
+  - Saltus stores it as a draft, revision, or pending change record
+  - human editor reviews diff
+  - editor approves, rejects, or edits
+  - only approved changes are published
+  - audit log records the full chain
+
+  Practically, mutating MCP tools should default to:
+
+  AI write -> draft/pending/revision -> human approval -> publish
+
+  Not:
+
+  AI write -> publish
+
+  Best Saltus framing
+
+  I’d describe it as:
+
+  > Saltus can become the governance layer for AI-operated WordPress content
+  > models: models define the content structure, context rules define how AI
+  > should behave, MCP/Abilities expose controlled operations to external
+  > agents, and WordPress revisions, statuses, capabilities, and audit logs keep
+  > every change reviewable.
+
+  The big opportunity is that Saltus already owns the model definition. That
+  means it can give AI agents structured knowledge of each CPT, its fields,
+  allowed operations, and editorial policy without every plugin author
+  rebuilding that machinery.