docs: draft plugin README, wp.org readme.txt, and community post

[jackgranatowski]

Summary

Parks three copy drafts in copy-wip/ for review before promotion:

• github-readme.md — repo README rewrite. Leads with what the plugin does (Design Settings, Bricks, Gutenberg) before build internals, keeps the vendored-admin-app/src warning prominent, and corrects factual claims from the live README. Adds a "name is the philosophy" section leading with Agnostic as the reason the plugin exists — the framework locks you into nothing, the plugin is just the WordPress-native wiring.
• wordpress-org-readme.txt — corrected wp.org description: four status colors (success/warning/danger/info), not five ("error" doesn't exist), and an honest note that the Components/Utilities/Full bundles currently style identically to Optimal because those framework layers are staged upstream. Same philosophy framing woven in.
• facebook-post-bricks-community.md — draft post for the Bricks Builder community group: leads with the "why another framework" question, names the acronym/philosophy, is upfront about the beta status and browser floor.

Context

Split out of #137, which bundled these drafts together with an unrelated GPL relicense (#[relicense PR]) and an admin-app build fix (already landed on main independently, needs no separate PR).

Test plan

• Review each draft for accuracy and tone
• On approval, promote github-readme.md → README.md and wordpress-org-readme.txt → SLASHED-for-WP/readme.txt's description section; post the FB draft manually

🤖 Generated with Claude Code

---

Generated by Claude Code

[coderabbitai]

Warning

Review limit reached

@jackgranatowski, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 47 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8dfefbef-b1db-4e2a-bd9e-3351ee67c843

📥 Commits

Reviewing files that changed from the base of the PR and between b9631c2 and a8831a0.

📒 Files selected for processing (3)

• copy-wip/facebook-post-bricks-community.md
• copy-wip/github-readme.md
• copy-wip/wordpress-org-readme.txt

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/marketing-copy-review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[qodo-code-review]

PR Summary by Qodo

Docs: add draft README, wp.org readme, and Bricks community post

📝 Documentation 🕐 20-40 Minutes

AI Description

• Add three copy drafts under copy-wip/ for accuracy/tone review before promotion.
• Rewrite GitHub README to lead with user value and correct prior factual claims.
• Draft WordPress.org readme.txt and a Bricks community announcement with clear caveats.

Diagram

graph TD
  A(["Author"]) --> B["copy-wip/ drafts"] --> C{"Approved?"}
  C -->|"Yes"| D["Promote: README.md"]
  C -->|"Yes"| E["Promote: wp.org readme"]
  C -->|"Yes"| F["Post: Bricks FB"]
  C -->|"No"| B
  subgraph Legend
    direction LR
    _actor(["Person"]) ~~~ _file["File"] ~~~ _dec{"Decision"}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Edit canonical docs directly in this PR

• ➕ One-step merge immediately updates user-facing docs
• ➕ Avoids duplication between drafts and canonical files
• ➖ Harder to review copy changes without implying they are ready to publish
• ➖ Risk of publishing incorrect/unfinished marketing claims

2. Keep drafts outside the repo (Google Doc/issue discussion)

• ➕ Easier collaborative commenting for non-technical reviewers
• ➕ No risk of accumulating draft files in the codebase
• ➖ Less traceability and review history in git
• ➖ Extra manual steps to port finalized copy into the repo

Recommendation: The current approach (staging drafts under copy-wip/) is appropriate for copy that needs factual/tone validation before publication. To prevent drift, follow up with a promotion PR that (1) moves copy-wip/github-readme.md to README.md, (2) updates the wp.org readme description in-place, and (3) either removes copy-wip/ or clearly documents it as a temporary staging area with an owner and cleanup expectation.

Files changed (3) +359 / -0

Documentation (3) +359 / -0

facebook-post-bricks-community.mdAdd Bricks community group announcement draft +17/-0

Add Bricks community group announcement draft

• Introduces a draft Facebook post explaining the framework/plugin motivation, key Bricks features, licensing, and browser support/beta caveats. Includes links to the framework, plugin repo, and hosted configurator.

copy-wip/facebook-post-bricks-community.md

github-readme.mdDraft new GitHub README focused on plugin value and philosophy +88/-0

Draft new GitHub README focused on plugin value and philosophy

• Adds a rewritten repo README draft describing Design Settings, Bricks integration, and Gutenberg integration ahead of build internals. Calls out the vendored 'admin-app/src' workflow and documents install/dev commands plus licensing details.

copy-wip/github-readme.md

wordpress-org-readme.txtDraft WordPress.org readme.txt with corrected feature claims +254/-0

Draft WordPress.org readme.txt with corrected feature claims

• Adds a complete wp.org-style 'readme.txt' draft covering features, bundles, browser support, external services disclosure, install steps, FAQ, and changelog. Corrects status colors to four (success/warning/danger/info) and notes bundle styling equivalence for staged layers.

copy-wip/wordpress-org-readme.txt

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 5 rules

1. Draft metadata stale 🐞 Bug ≡ Correctness

Description

copy-wip/wordpress-org-readme.txt declares Stable tag 0.4.20 and GPL-3.0-or-later, but the plugin
headers and current SLASHED-for-WP/readme.txt are 0.4.21 and GPL-2.0-or-later. If this draft is
promoted to wp.org readme.txt as-is, it will publish incorrect version/license metadata.

Code

copy-wip/wordpress-org-readme.txt[R6-9]

+Stable tag: 0.4.20
+Requires PHP: 7.4
+License: GPL-3.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-3.0.html

Relevance

⭐⭐⭐ High

They update wp.org readme Stable tag/metadata to match releases; accuracy prioritized (PR#66,#46).

PR-#66
PR-#46

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The draft’s stable tag/license conflict with the authoritative plugin header and the current wp.org
readme in the plugin directory.

copy-wip/wordpress-org-readme.txt[6-9]
SLASHED-for-WP/slashed.php[3-12]
SLASHED-for-WP/readme.txt[5-9]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`copy-wip/wordpress-org-readme.txt` has a stale `Stable tag` and incorrect license fields (GPLv3), which conflict with the plugin’s declared version/license.

### Issue Context
- The plugin version is declared in `SLASHED-for-WP/slashed.php` and should match wp.org `Stable tag`.
- The plugin license is declared as GPL-2.0-or-later in both the plugin header and `SLASHED-for-WP/readme.txt`.

### Fix Focus Areas
- copy-wip/wordpress-org-readme.txt[6-9]
- SLASHED-for-WP/slashed.php[3-12]
- SLASHED-for-WP/readme.txt[5-9]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Wrong license link ✗ Dismissed 🐞 Bug ⚙ Maintainability

Description

copy-wip/github-readme.md claims the plugin is GPL-3.0-or-later and links to the repo-root LICENSE,
but the repo-root LICENSE is MIT and the plugin’s GPL text lives under SLASHED-for-WP/license.txt
with GPL-2.0-or-later in the plugin header. Promoting this README would misrepresent licensing and
point readers at the wrong file.

Code

copy-wip/github-readme.md[R86-88]

+## License
+
+The plugin is licensed under [GPL-3.0-or-later](LICENSE). The bundled [SLASHED framework](https://github.com/codeslash-dev/SLASHED) is [MIT](https://github.com/codeslash-dev/SLASHED/blob/main/LICENSE)-licensed (GPL-compatible) — see the third-party notice at the end of [LICENSE](LICENSE).

Relevance

⭐⭐⭐ High

Prior PRs carefully aligned plugin GPL vs root MIT LICENSE; likely fix README license claim/link
(PR#46,#47).

PR-#46
PR-#47

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The draft points GPL licensing claims at LICENSE, but that file is MIT; the plugin itself declares
GPL-2.0-or-later and ships GPL text in a different file.

copy-wip/github-readme.md[86-88]
LICENSE[1-5]
SLASHED-for-WP/slashed.php[6-10]
SLASHED-for-WP/license.txt[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The draft GitHub README’s license section misstates the plugin license (GPLv3) and links to the wrong license file.

### Issue Context
- Repo root `LICENSE` is MIT.
- Plugin header declares GPL-2.0-or-later.
- Plugin’s GPL license text is in `SLASHED-for-WP/license.txt`.

### Fix Focus Areas
- copy-wip/github-readme.md[86-88]
- LICENSE[1-5]
- SLASHED-for-WP/slashed.php[6-10]
- SLASHED-for-WP/license.txt[1-5]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Status “error” unclear ✗ Dismissed 🐞 Bug ⚙ Maintainability

Description

The drafts describe a four-color status palette, but the codebase still contains legacy/alias
“error” concepts (e.g., is-error as an alias for is-danger, and defaults still listing an error
status). Without a clarifying note, readers may be confused when they encounter is-error or legacy
tokens in generated data.

Code

copy-wip/wordpress-org-readme.txt[R25-26]

+Set six brand colors (primary, secondary, tertiary, action, neutral, base), each with an optional separate dark value, and the framework recolors itself: hover and active states, tints, shades, tonal steps, and the four status colors (success, warning, danger, info) are all derived for you. Each status color can be overridden individually too.
+

Relevance

⭐⭐ Medium

Docs accuracy is valued (readme rewrites PR#84), but no history on documenting legacy is-error
alias.

PR-#84

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The docs claim a four-color status palette; the bundled CSS supports exactly four resolved status
color tokens, but the repo still exposes is-error as an alias and retains legacy error entries
in defaults/registries.

copy-wip/wordpress-org-readme.txt[25-26]
SLASHED-for-WP/dist/slashed.optimal.css[412-416]
SLASHED-for-WP/admin-app/src/data/classes.generated.json[127-136]
SLASHED-for-WP/admin-app/src/data/token-registry.generated.json[585-613]
SLASHED-for-WP/includes/class-token-defaults.php[82-95]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Docs describe four status colors but don’t explain the presence of `is-error` (alias) and legacy `error` defaults/registry entries.

### Issue Context
- Framework resolved status color tokens in the bundled CSS are `success`, `warning`, `info`, `danger`.
- `is-error` exists as an alias for `is-danger`.
- Token registry marks `--sf-color-error*` as removed, yet defaults still include `error`.

### Fix Focus Areas
- copy-wip/wordpress-org-readme.txt[25-26]
- SLASHED-for-WP/dist/slashed.optimal.css[412-416]
- SLASHED-for-WP/admin-app/src/data/classes.generated.json[127-136]
- SLASHED-for-WP/admin-app/src/data/token-registry.generated.json[585-613]
- SLASHED-for-WP/includes/class-token-defaults.php[82-95]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Draft metadata stale 🐞 Bug ≡ Correctness

copy-wip/wordpress-org-readme.txt declares Stable tag 0.4.20 and GPL-3.0-or-later, but the plugin
headers and current SLASHED-for-WP/readme.txt are 0.4.21 and GPL-2.0-or-later. If this draft is
promoted to wp.org readme.txt as-is, it will publish incorrect version/license metadata.

Agent Prompt

### Issue description
`copy-wip/wordpress-org-readme.txt` has a stale `Stable tag` and incorrect license fields (GPLv3), which conflict with the plugin’s declared version/license.

### Issue Context
- The plugin version is declared in `SLASHED-for-WP/slashed.php` and should match wp.org `Stable tag`.
- The plugin license is declared as GPL-2.0-or-later in both the plugin header and `SLASHED-for-WP/readme.txt`.

### Fix Focus Areas
- copy-wip/wordpress-org-readme.txt[6-9]
- SLASHED-for-WP/slashed.php[3-12]
- SLASHED-for-WP/readme.txt[5-9]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[jackgranatowski]

Split into two parts:

• Stable tag / changelog were genuinely stale (0.4.20 vs the plugin's actual 0.4.21) — real drift, not intentional. Fixed in a8831a0: bumped Stable tag to 0.4.21 and added the missing 0.4.21 changelog entry (copied verbatim from SLASHED-for-WP/readme.txt on main).
• The GPL-3.0-or-later license fields are intentionally forward-looking — this draft assumes #149 (the GPL-3 relicense PR) has landed first. Until then main is still GPL-2.0-or-later, and this copy PR is staged in copy-wip/ specifically so it isn't promoted before that's true. No change needed there.

---

Generated by Claude Code