← Back to Home

WordPress 7.1 Team Collaboration and Permissions: From Notes Inline Comments to a WP-CLI Capability Audit

wordpress collaborationnotes annotationsuser rolesAmazon Basics

I actually run a WordPress site for a six-person content team: three writers, two editors and one ops person who owns the publishing calendar. For a year our review workflow looked like this — drafts changed in the editor, feedback lived in a separate doc, disagreements were screenshotted into a group chat, and somebody reconciled by hand which comment landed on which paragraph. Once WordPress 7.1 finished turning Notes into a real editorial tool, we moved the whole review loop back into the editor.

The first week still fell apart. Every feature worked, the process did not. The blocker was never Notes — it was permissions. What a low-privilege role can and cannot do is computed per object by WordPress's roles-and-capabilities system, and most teams have never audited that table.

One disclosure up front: the section further down called "The review desk" contains affiliate links. If you buy through them, this site may earn a commission. It does not change the technical conclusions above it, and that section is deliberately kept separate so you can skip it.

⏳ TL;DR

🥇 The one-line conclusion: Notes answers "where does the feedback go", not "who is allowed to change this". Spend ten minutes on a capability audit before you move your process, or you will spend the first week explaining error messages.

🔧 Two things you can do today:

1. Check your version: wp core version. If you are still on 7.1.0, both the Notes authorization fixes (7.1.1) and the template resolution fix (7.1.2) are missing.

2. Audit the low-privilege role: wp cap list contributor | sort, then look for edit_published_posts and upload_files.

💻 The review desk (affiliate links, unrelated to the conclusions above):

👉 https://www.amazon.com/dp/B09TRW57WB?tag=techpassive-20

👉 https://www.amazon.com/dp/B0DK59YKRS?tag=techpassive-20

Why this is only worth doing now

Two version facts decide whether the migration is worth it.

Notes arrived in WordPress 6.9 and could only attach to a block — block-level comments in practice. WordPress 7.1 is what made it a collaboration tool: inline notes attached to a selected phrase, with the highlight staying anchored to that text (editing elsewhere in the same block does not move it), multiple independent threads on one block, rich text including bold, italic, code and links, @mentions that trigger an email, long notes collapsed by default, and a centered "Resolved" divider that pushes finished conversations below the active list.

Two boundaries matter just as much, because they decide whether you can actually use it:

Start with a WP-CLI capability audit (15 minutes)

Environment: WordPress 7.1.2 (current on the 7.1 branch, released 2026-09-22), PHP 8.2+, WP-CLI 2.12.0 (current stable). The commands below are read-only, so they are safe on production:

# 1. Version and update status
wp core version
wp core check-update

# 2. Which roles actually exist (custom roles are often created by a plugin)
wp role list --fields=role,name --format=table

# 3. What the low-privilege role can really do — the two lines that matter
wp cap list contributor | sort | grep -E 'edit_published_posts|upload_files'
wp cap list author | sort | grep -E 'edit_published_posts|upload_files'

# 4. Whether a user's capability comes from a role or a per-user grant
wp user list-caps  --origin=role
wp user list-caps  --origin=user

# 5. Who holds which role (name them before you migrate anything)
wp user list --role=contributor --fields=ID,user_login,user_email

Step 3 is the line that broke us. The contributor role holds edit_posts but has **neither** edit_published_posts **nor** upload_files. Those two gaps map directly onto errors one and two below.

If you want a dedicated reviewer role (can annotate and revise, cannot reach plugin settings), clone an existing role rather than assembling one from scratch:

wp role create reviewer "Reviewer" --clone=author
wp cap list reviewer | sort

One operational detail worth remembering: **capabilities added from a theme's functions.php disappear when the theme changes**. For something durable, put capability changes in an mu-plugin — or at minimum keep the defaults in mind so wp role reset --all can roll you back.

Five team conventions you can copy

Process, not features, is what keeps this running. These five are what we actually enforce, and they measurably cut rework:

1. Annotate the sentence, not the block. If an inline note works, never leave a block-level comment. "Rewrite this" and "change 'significantly faster' in sentence three to a number" cost wildly different amounts of rework.

2. One thread per issue. Use "Add Note" to start a new thread on the same block instead of replying, so discussions do not merge into one long scroll.

3. Reserve @mentions for handoffs. A mention means "this is yours now", not "heads up". Our rule: the mentioned person replies or resolves the same day.

4. Resolve on completion. Resolve the note as soon as it is handled so it drops below the divider. Keeping the active list under one screen is what makes review feel fast.

5. Sweep the "All notes" view before publishing. Notes attached to a block you deleted become orphaned notes and stay in the list — possibly pointing at a paragraph that no longer exists.

Troubleshooting: five real errors and their fixes

Error 1: Sorry, you are not allowed to edit this post.

Scenario: A writer submits a draft as a contributor. An editor publishes it directly. The writer comes back to add a sentence and the editor throws that message — the edit button in the admin is gone too.

**Why**: The user was not demoted. WordPress resolves **meta capabilities per object**. edit_post does not exist on any role; map_meta_cap() translates it at runtime into primitive capabilities — editing your own published post maps to edit_published_posts, your own draft maps to edit_posts, someone else's post maps to edit_others_posts. A contributor holds edit_posts only, so draft access works, and the moment the post becomes publish, the same user on the same post fails. The post changed status; the mapping is computed from the post.

Two details most people never run into until they do:

Fix:

# Option A: grant it to one user (smallest change, good for firefighting)
wp user add-cap  edit_published_posts

# Option B: move the role up to author — writers normally need to revise their own published posts
wp user set-role  author

If you truly need contributors to keep editing after publication, gate it through a map_meta_cap filter with a condition rather than granting the capability to the whole role; the latter widens access for every contributor on the site.

Error 2: Sorry, you are not allowed to upload files.

Scenario: The same writers click "Add Media" on an illustrated post. The uploader never opens.

**Why**: Contributor and Subscriber do **not** include upload_files; Administrator, Editor and Author do. Dashboard access is not media access — they are separate capabilities.

**Fix**: Decide deliberately first. Granting upload_files also exposes the **entire media library**, including other people's assets, which matters on multi-brand or multi-client sites. Pick by team size:

# Small teams: just grant it (accepting a shared library)
wp cap add contributor upload_files

# Better default: switch the user to author (uploads included, own published posts editable)
wp user set-role  author

# Larger teams: a dedicated role, with per-user media isolation handled by a plugin
wp role create contributor_plus "Contributor+" --clone=contributor
wp cap add contributor_plus upload_files

We moved all writers to author and left Contributor only for interns — their posts are always published by an editor, so they never needed post-publish access.

Error 3: Notes are missing on custom post types

Scenario: Besides posts and pages, the site has custom post types (product briefs, case studies). Notes work on posts; on those types the toolbar has no entry point at all.

**Why**: Notes ship enabled for post and page. A custom post type has to opt in explicitly.

Fix:

// When registering the type
register_post_type( 'brief', [
    'label'        => 'Briefs',
    'public'       => true,
    'show_in_rest' => true,
    'supports'     => [ 'title', 'author', 'editor' => [ 'notes' => true ] ],
] );

// Existing type: merge notes into the current editor supports, do not overwrite them
add_action( 'init', function () {
    foreach ( [ 'brief', 'case_study' ] as $type ) {
        $supports = get_all_post_type_supports( $type );
        $editor   = [ 'notes' => true ];
        if ( isset( $supports['editor'][0] ) && is_array( $supports['editor'][0] ) ) {
            $editor = array_merge( $editor, $supports['editor'][0] );
        }
        add_post_type_support( $type, 'editor', $editor );
    }
} );

Going the other way, if Notes are pure noise on some types, unset supports['editor']['notes'] through the register_post_type_args filter. There is no global off switch in core.

Error 4: @mentions are inserted, but the person never gets an email

Scenario: An editor mentions a writer in a note; the mention chip renders correctly; the writer has no idea it happened.

**Why**: Note emails depend on two things. First, the notification toggle under **Settings → Discussion** ("Email me whenever someone posts a note") has to be on. Second, note emails go through WordPress's mail path — wp_mail(). And **wp_mail() returning true only means the message was handed to the mail function; it does not mean anyone received it**. If the sending domain has no aligned SPF/DKIM/DMARC, or the host throttles port 25, the mail disappears server-side with no error on your side.

Fix: Confirm the Discussion setting first. If the toggle is correct and mail still does not arrive, the problem is the mail path, not WordPress. We wrote up the full three-layer diagnosis separately — see the links at the end.

Error 5: On multisite, saved HTML and shortcodes get stripped

**Scenario**: On a WordPress multisite network, a site administrator (not a network super admin) saves a post and inline styles, style attributes and some shortcodes are silently removed. The editor looks right; the front end does not.

**Why**: The unfiltered_html capability check has a branch tied to a wp-config.php constant and to whether the install is multisite: when DISALLOW_UNFILTERED_HTML is defined, or on multisite for anyone who is not a super admin, the check appends do_not_allow. The execution order matters more than the name — do_not_allow is unset at the very end of WP_User::has_cap(), **after** the user_has_cap filter runs, so a plugin cannot grant it, deliberately or by accident. Worse, the final check requires every requested capability, so one do_not_allow in the array denies the whole thing.

Fix: Keep inline styling out of post content and let block styles or the theme handle it. For genuine raw-HTML needs, use a super admin account, or handle the markup in an mu-plugin against a controlled allowlist instead of forcing the capability check open.

Two patches to apply before you roll this out

These read as unrelated to collaboration, but they decide how trustworthy the permission checks above are:

If your site still runs 7.1.0, both the note authorization fix and the template resolution fix are missing. The upgrade is short, but keep the order:

wp db export backup-$(date +%F).sql   # back up first, then change versions
wp core update
wp core version
wp core update-db

The review desk (separate section, affiliate links)

Nothing here connects to the permission conclusions above. These are simply the two pieces of hardware we use for long review sessions, kept in their own section so you can skip it. The links are affiliate links; purchases may earn this site a commission.

Dell UltraSharp U2723QE 27" 4K USB-C Hub monitor — at 4K the editor sidebar, the content and the notes panel fit on screen without constant panel folding, and the USB-C single-cable setup powers the laptop while carrying keyboard and mouse. The honest downside: it is built for port selection and color consistency, not refresh rate, so if you also play games you want a different model for 144Hz. Roughly $429–529 as of publication; check the live listing.

👉 https://www.amazon.com/dp/B09TRW57WB?tag=techpassive-20

BenQ ScreenBar Halo 2 monitor light bar — our publishing deadlines run late, and a light bar lights the keyboard area without eating desk space, which suits editing text against a screen better than a ceiling light. Official specs: 2700K–6500K stepless color temperature, three-zone backlight, 1000R–1800R curved monitor support. Downsides, stated plainly: in auto-dimming mode the color temperature locks to 4000K and cannot be changed, which reads cool in the evening; the wireless dial occasionally takes a moment to wake; it wants 5V/3A, so a 5V/1A USB port on an older monitor will flicker. Roughly $179–199 as of publication; check the live listing.

👉 https://www.amazon.com/dp/B0DK59YKRS?tag=techpassive-20

FAQ

Q: Do notes show up on the front end or in comment lists?

No. They are stored as a special comment type, visible only inside the editor to users who can edit that post, and core excludes them from public comment feeds as of 7.1.

Q: Why can I not mention myself?

By design — the current user is excluded from the autocomplete list. If you want a to-do for yourself, leave a normal note.

Q: Can team members see each other's notes?

It follows edit access to that post. Administrators and Editors can view and add notes on all posts; Authors and Contributors on their own; Subscribers cannot. Which means "who can see the notes" is, once again, a capability question.

Related reading

Closing

Notes finally gives editorial feedback a standard answer to "where does this comment belong", but it will not answer "who is allowed to change what". Run wp cap list contributor | sort, read the edit_published_posts and upload_files lines carefully, and only then move your process into the editor — in the other order, your first week is spent explaining errors. And remember 7.1.1 already patched a note authorization issue, so if the site is still on 7.1.0, upgrade before you talk about collaboration.

👉 Join MiniMax Token Plan: AI coding acceleration for businesses

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

☁️ DigitalOcean Cloud ⚡ Vultr VPS ⭐ MiniMax Token Plan 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🔍 WordPress SEO Books 🌐 Web Hosting Books 🐳 Docker Books 🐧 Linux Books 🐍 Python Books 💰 Affiliate Marketing 💵 Passive Income Books 🖥️ Server Books ☁️ Cloud Computing Books 🚀 DevOps Books 🤖 Xiaomi MiMo Platform
← Back to Home