docs: refresh stale content in doc/ against the v7 codebase#591
Open
galbus wants to merge 4 commits into
Open
Conversation
An audit of every doc/*.md against the current code found content that no longer matches the plugin. Each finding was verified against the source before rewriting. Substantially stale: - wp-config.md documented BEYONDWORDS_AUTO_SYNC_SETTINGS, which no longer exists anywhere in the plugin (the settings-sync feature was removed in v7). Removed it, and documented the six URL-override constants from Core\Urls that do work, including the empty-string strlen() guard. - plugin-features.md predated the v7 rewrite: it listed the "Display player" control that Embed replaced, and omitted most of the v7 surface. Corrections: - async-rest-migration.md claimed failed reads are not cached; they are negative-cached for CACHE_TTL_ON_ERROR. It also named a Client method that does not exist and listed shipped work as deferred. - wordpress-vip.md described the uninstaller's transient cleanup as deleting known keys; it is a SQL prefix sweep of the options table. - running-tests.md pointed at .wp-env.override.json for the tests env (correct file is .wp-env.tests.override.json), and had no Jest section. - legacy-meta-migration.md's downgrade guarantee did not note that the migration deletes beyondwords_disabled, and described play-audio/ and select-voice/ as removed when both still exist. - settings-internals.md omitted the 5-minute credential-fingerprinted validation throttle. - Smaller accuracy fixes in preselect-generate-audio.md (mode is 'off', not 'none'; documents the DEFAULT_VALUE preselect), rest-meta-visibility.md and video-settings-payload.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
✅ WordPress Plugin Check Report
📊 ReportAll checks passed! No errors or warnings found. 🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check |
Second pass over the refreshed docs, correcting statements the first pass got wrong or overstated. Each correction was re-verified against the source. - plugin-features.md: no control is labelled "Generate audio" — the shipped toggle's caption reads "Generation enabled"/"Generation disabled". Model is a filter that is never submitted, not a saved override. Added the Content section (Source, Script template) and noted that Integration and Preferences stay hidden until the credentials validate. - settings-internals.md: the flag holds an ISO-8601 UTC string, not a timestamp, and gates the whole admin/editor bootstrap in Core\Plugin::init(), not just the settings tabs. - wp-config.md: BEYONDWORDS_BACKEND_URL has no callers in src/, so it is documented as legacy rather than a working override. - legacy-meta-migration.md: the migration only matches rows whose value is '1'; other values are left untouched. display-player was a checkbox row, not a preview component. - rest-meta-visibility.md: the Custom Fields panel is hidden by the is_protected_meta filter, not by register_meta(); the hidden-key list is illustrative, not exhaustive. - getting-started.md: added the host PHP/Composer prerequisite the rewrite depended on, and corrected the checks to run on commit, not push. - running-tests.md: BEYONDWORDS_MOCK_API applies to the wp-env site (Cypress); PHPUnit reads its own bootstrap constants. - code-quality-checks.md: grumphp.yml does not set max_body_width, so GrumPHP's default of 72 is enforced on every body line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
PR #567 reworked voice selection, adding 'Accent' and 'Native' alongside 'Model'. All three narrow the voice list without being saved — the post stores only beyondwords_language_code and beyondwords_body_voice_id. Re-checked the other docs that touch voice selection against #567: async-rest-migration.md's claims still hold (get_voices() still routes through cached_get() with VOICES_REQUEST_TIMEOUT, classic-metabox.js still fetches voices in hydrate() and /projects/{id} in applyProjectDefaultLanguage(), and all six cited REST routes exist). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
galbus
marked this pull request as ready for review
July 19, 2026 13:24
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.
Why
Audited every file in
doc/against the current v7 code. Several docs predate the v7 rewrite and now describe things that no longer exist. Each finding below was verified against the source before rewriting — no doc text was changed on a hunch.Substantially stale
wp-config.md— documentedBEYONDWORDS_AUTO_SYNC_SETTINGS, a constant that no longer exists anywhere in the plugin.grep -rn BEYONDWORDS_AUTO_SYNC_SETTINGS --include='*.php' src/ *.phpreturns nothing; the only occurrence in the repo is a leftover env var in.wp-env.tests.jsonthat nothing reads. The settings-sync feature it controlled was removed in v7. Anyone defining it inwp-config.phptoday gets silence.Removed that section, and documented the six URL-override constants that do work (
Core\Urls), with their real defaults and thestrlen()guard that makes an empty-string override a no-op. Also tightenedBEYONDWORDS_AUTOREGENERATE— the check sits inside the "already has a content ID" branch, so it suppresses regeneration only, not initial generation.plugin-features.md— written 2.5 years ago, predates v7 entirely. Listed the "Display player" control that v7 replaced with the Embed dropdown, and omitted most of the current surface (Integration method, Player UI, video output, voice selection, the Delete audio bulk action, per-block generation toggles, Site Health).Corrections
async-rest-migration.mdCACHE_TTL_ON_ERROR. NamedClient::get_summarization_settings(), which doesn't exist. Listed background delete as "deferred" after it shipped. Still written in unmerged-PR voice.wordpress-vip.mdLIKE '_transient_beyondwords_%'SQL prefix sweep. The VIP-relevant point is that object-cache hosts have no such rows, so the sweep matches nothing and entries expire by TTL.running-tests.md.wp-env.override.jsonfor the tests env; the correct file is.wp-env.tests.override.json. No Jest section despite Jest tests and a CI Jest job. Presented the full 20-minute Cypress suite as the normal workflow instead of the per-spec@covers/@groupflow in AGENTS.md.legacy-meta-migration.mdbeyondwords_disabled. Describedplay-audio/andselect-voice/as removed/replaced — both still exist and are wired up.settings-internals.mdCONNECTION_CHECK_TTLthrottle (keyed on a credential fingerprint), which is what actually governs when validation re-runs.getting-started.mdnpm run composer -- install) ran before step 6 (npm run env:start), but the composer script dispatches into a wp-env container that doesn't exist yet — unrunnable on a fresh clone.code-quality-checks.mdtest_phpunit/coverage_checkas commit-time checks when they aren't in that testsuite; omittedlint_plugins; overstated what CI runs under GrumPHP.preselect-generate-audio.md'off', not'none'. Didn't mentionDEFAULT_VALUEmakes a fresh install preselect for posts. Misdescribed what the classic metabox JS does.rest-meta-visibility.mdregister_rest_meta_visibility(); mislabelled a BeyondWords-era key as a SpeechKit one.video-settings-payload.mdNotes for review
wordpress-vip.md,settings-internals.md) were errors I introduced in docs: reduce inline comments to why-only; move rationale into doc/ #589 when extracting rationale out of code comments; they're fixed here.🤖 Generated with Claude Code