[ViewFromTheBox]

Description

Phase G6 of the cms-framework integration (plan 12). Closes out the integration work landed in G0–G5 with documentation, a manual smoke flow, and V1.0.0 release-notes draft.

Closes: #403

Type of Change

• Documentation update

Related Issue

Issue: #403

Motivation and Context

G0–G5 shipped the actual integration code (resource filter, site-meta bridge, REST adapters, block re-enablement, permissions seed). G6 is the documentation + release-readiness layer: users need a path from "I installed both packages" to "I'm editing a Post"; we need a manual regression flow that exercises the version pair before every release tag; the V1.0.0 release-notes need to call out the integration explicitly.

Changes Made

• Flip plan 12 §8 from "open questions to answer at phase kickoff" to "decisions made during phase implementation" with all seven questions resolved against what actually shipped in G0–G5.
• Add "Using with cms-framework" README section covering install, migrations (the dual content + block_content state), the merged ap.visual-editor.resources map, and the version-pair contract.
• Add docs/g6-smoke-flow.md — manual QA checklist (A–H steps + failure runbook) that exercises the full Phase G pipeline end-to-end. Mirrors docs/h8-smoke-flow.md for the site-editor side; G6 covers post / page editing, site-meta, query-loop blocks, and standalone-cms-framework boot.
• Draft V1.0.0 release-notes bullets in CHANGELOG.md [Unreleased] covering the Phase G integration, README section, and permissions seed. These flow into the V1.0.0 release PR when ship time comes.

Reciprocal "Using with the visual editor" section in the cms-framework README tracked separately in cms-framework#150 per the issue body's "file as small follow-up issue" option.

How Has This Been Tested?

Testing Environment:

• Operating System: macOS
• PHP Version: 8.4.3
• Project Version: release/1.0

Tests Performed:

Docs-only change — no PHP or JS code touched, so no test suite affected. CodeRabbit CLI run against release/1.0 returned 0 findings after addressing one math-correction in §8.

The smoke flow itself is the test surface for the integration — it will run against the v1.0.0 release candidate per its own "Logging" section.

Accessibility Tests Run

• N/A — docs-only change

Tests Added

• No tests needed — docs-only change. Smoke flow doc is itself a manual test plan.

Test details: N/A.

Documentation

• README updated
• Plan doc updated (§8 decisions)
• CHANGELOG updated
• New manual smoke-flow doc added

Documentation details: All changes are documentation. See "Changes Made" above.

Pre-Submission Checklist

• Followed contributing guidelines
• Checked for other open PRs for same update
• Code passes all tests (N/A — docs-only)
• Code has been linted (N/A — docs-only)
• Accessibility tests completed (N/A — docs-only)
• Code follows project style guide
• Self-review completed
• No new warnings generated

Summary by CodeRabbit

• Documentation
  • Added cms-framework integration docs (Phase G) with visual editor support details
  • Added "Using with cms-framework" guide covering paired installation, migrations, resource mapping, and version pairing
  • Added Phase G smoke-flow QA checklist for end-to-end validation, troubleshooting, and logging guidance
  • Documented decisions made during phase implementation
  • Noted RBAC permission seeding behavior and future delegation plan

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fb3f7bf5-3fa4-4aed-9f2c-065be9a0eed6

📥 Commits

Reviewing files that changed from the base of the PR and between 2ab4e1b and 4ce58b7.

📒 Files selected for processing (1)

• README.md

✅ Files skipped from review due to trivial changes (1)

• README.md

---

📝 Walkthrough

Walkthrough

Documentation-only changes completing Phase G: README “Using with cms-framework” guide, a G6 manual QA smoke-flow checklist, updates to the phase plan recording implementation decisions, and related changelog entries.

Changes

cms-framework Integration Documentation

Layer / File(s)	Summary
User integration guide README.md	New "Using with cms-framework" section documents paired installation, migration steps for block_content (dual-state with legacy content), the merged resource map under ap.visual-editor.resources, config precedence for Post/Page resources, and visual-editor v1.0.x ↔ cms-framework v1.x version compatibility with links to smoke-flow and contract docs.
QA smoke flow specification docs/g6-smoke-flow.md	Phase G6 manual regression checklist: install/migrate, create a Post and verify dual-state DB columns, open Post in visual editor and add/save site-context and query blocks, verify editor preview query resolution and saved block JSON, confirm front-end rendering with in-request query execution and setting-driven output, site-meta parity between editor canvas and front-end, standalone cms-framework boot validation, troubleshooting guidance, and release logging requirements.
Phase decisions and changelog docs/plans/12-cms-framework-integration.md, CHANGELOG.md	Plan doc section records resolved implementation decisions (e.g., block_content column name, HasBlockContent opt-in, site.url default, inspector sidebar scope, QueryRuntime contract, permission-seeding approach, front-end settings parity). Changelog entries announce Phase G integration, README coverage, and RBAC seeding notes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Add 'Using with the visual editor' README section (reciprocal of visual-editor #403) cms-framework#150: README "Using with cms-framework" content and notes about ap.visual-editor.resources, class_exists guard, migrations, and permission seeding align with the reciprocal documentation requested in that issue.

A rabbit hops through the docs with cheer,
Phase G is penned so testers steer,
Smoke flows ready, decisions logged,
Integration steps neatly catalogged,
🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title directly describes the documentation changes: adding G6 cms-framework integration docs and smoke flow, which matches the changeset.
Linked Issues check	✅ Passed	All coding requirements from issue #403 are met: plan doc §8 updated with decisions, README section added, smoke flow checklist created, and V1.0.0 release-notes drafted.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation updates directly supporting the cms-framework integration requirements; no extraneous modifications present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/403-cms-framework-integration-docs-smoke-flow

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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

[coderabbitai]

Caution

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

⚠️ Outside diff range comments (1)

README.md (1)

25-26: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Inconsistent smoke flow reference for V1.0.x.

This PR adds docs/g6-smoke-flow.md (Phase G cms-framework integration), but lines 25-26 reference docs/h8-smoke-flow.md (Phase H site-editor) as the smoke flow that "runs against this version pair before every release tag." For V1.0.x, the cms-framework integration validation should cite the G6 flow.

📝 Proposed fix

-Bumping the major on either package without bumping the partner is
-unsupported. The H8 smoke flow ([`docs/h8-smoke-flow.md`](docs/h8-smoke-flow.md))
-runs against this version pair before every release tag.
+Bumping the major on either package without bumping the partner is
+unsupported. The G6 smoke flow ([`docs/g6-smoke-flow.md`](docs/g6-smoke-flow.md))
+runs against this version pair before every V1.0.x release tag.

🤖 Prompt for 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.

In `@README.md` around lines 25 - 26, Update the README.md smoke flow reference to
point to the G6 smoke flow: replace the reference to docs/h8-smoke-flow.md with
docs/g6-smoke-flow.md so the sentence correctly states that the G6
(cms-framework integration) smoke flow runs against the V1.0.x version pair
before every release tag; search for the exact text fragment "runs against this
version pair before every release tag" or the current mention of
docs/h8-smoke-flow.md to locate the line to change.

🤖 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.

Outside diff comments:
In `@README.md`:
- Around line 25-26: Update the README.md smoke flow reference to point to the
G6 smoke flow: replace the reference to docs/h8-smoke-flow.md with
docs/g6-smoke-flow.md so the sentence correctly states that the G6
(cms-framework integration) smoke flow runs against the V1.0.x version pair
before every release tag; search for the exact text fragment "runs against this
version pair before every release tag" or the current mention of
docs/h8-smoke-flow.md to locate the line to change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1c48c495-1d28-42c1-b946-eaaf0b586444

📥 Commits

Reviewing files that changed from the base of the PR and between 52603b3 and 2ab4e1b.

📒 Files selected for processing (4)

• CHANGELOG.md
• README.md
• docs/g6-smoke-flow.md
• docs/plans/12-cms-framework-integration.md