[Docs] Team Settings new UI: Data & Feature Flag pgs with writer Agents (Phase 5 & 6)

[lisa-tarbo]

Summary: what and why

Pages added after rebuild UI of Team Settings for Feature Flags and the Data and Migration section.

Context

These user docs were not written by changelog automation for the code PR so needs to be done manually.
Used Claude command /write-docs and /review-pr to create and validate how these improved prompts write docs from code (including new prompt checklists).

Resolves: #785 which describes phase 5 and 6 and the previous phases

Changes

Scope

1. Added 3 new pages for Team settings (Data and Feature flags) and new how-to download_team_files.md
2. After Claude drafts of 2 new pages, manually instructed Claude to separated out "How-to / download files" details to keep concept pages high level
3. Also fixes a manual-review finding (a missing Require two-factor authentication control on Members & access)
4. Tightens internal linking across the pages phases 1–4 already touched.

Affected pages / sections

• Page(s) / section(s): docs/concepts/team/members.md with new two-factor authentication
• Folder(s):
• docs/how-to/ - new download_team_files.md and FAQ page to link to new feature flags pages
• docs/concepts/- new feature-flags.md and data_migration.md
• Removed old images for feature flags on FAQ pages.

Decisions and what was not addressed in this PR

• The "Developers" menu has duplicate entries for "Developer" and to be fixed in next PR [Docs] Consolidate duplicated Custom Action content #878
• The mkdocs menu names for sections match the UI menu (e.g. Members) and not the section names (e.g. "Members & access" to help readers match docs menu to the UI.
• Feature flags are not individually enumerated on the new page as they change over time

Validation

• This follows the relevant page-type contract.
• Examples and UI features/behavior were manually checked.
• Internal links and cross-references were manually reviewed for user value.
• Terminology matches current OCS naming and behavior.
• Validation commands run are listed below:
  • uv run zensical build --clean
  • uv run prek run markdownlint-cli2 --all-files
  • uv run prek run --all-files
  • uv run pytest scripts/tests

Risks / notes

• Improvements for the automation to write user docs is continuing with investigation into why these Team setting UI changes did not get written and had to be done manually. Assuming that the code change was very large with not enough detail in PR to trigger user docs
• docs/tech-hub/migrate_team.md picked up a factual correction, not just a wording update: the claim that "the sync endpoints refuse to serve a team that isn't in migration mode" was found to be stale against current source (the check is now client-side in sync_team). Worth a second look since it changes what the page tells an operator to expect if they skip that step.

[claude]

Documentation review

The three new pages fit their page types well — data_migration.md and feature_flags.md stay at the "what/why" level, download_team_files.md is properly task-shaped with prerequisites, numbered steps, expected outcome, and common issues, and splitting the download details out of the concept page was the right call. Dropping the two feature-flag screenshots in favour of a link is also an improvement; screenshots of a rebuilt UI go stale fast.

Two blocking items, both in integrations.md, plus a handful of smaller things — left inline.

Blocking

• integrations.md:3 — "messaging" links to speech_providers.md instead of messaging_providers.md. The strict build will not catch this, since the wrong target exists.
• integrations.md:7 — cutting the "For every row you can see" list left the The Integrations table section opening with "each row also offers...", with no antecedent for "also" and no description of what a row contains.

Should fix

Several edits here remove explanatory content rather than add it, and three of the cuts took something load-bearing with them:

• members.md:27 — the invite dialog's two fields are gone, but the next sentence still refers to Send Invitation inside a dialog the reader was never shown.
• members.md:39 — "Select Update Role to save your changes" is gone, so the section describes the form but never says how to commit the change.
• members.md:8 — "sorted alphabetically by email" dropped; worth confirming the sort order did not change rather than was trimmed.

Also: mkdocs.yml:174 renames the nav entry to "Members" while the H1 stays "Members & Access"; and the Data section is now referred to as "Data", "Data & Migration", and "Data & migration" across the changed files. Details and suggested fixes are inline.

On the factual correction

The reworded step 5 in migrate_team.md does still tell the operator the step is required, so the substance is fine. I cannot verify the sync_team client-side check or the literal error string from this repo — that needs someone with OCS source access. My only note is readability: the sentence runs ~45 words with the error string buried mid-clause. Suggested split inline.

Validation — not run

uv is not installed in my environment and I have no network access to install it, so I could not run zensical build --clean or markdownlint-cli2. The PR's own validation checkboxes are also unchecked. Both need to run before merge — strict: true means the build is what confirms the new anchor links (#editing-a-members-role, #downloading-team-files, and the rest) resolve. I traced them against the default toc slugify rules by hand and they look correct, but that is not a substitute for the build.

One thing the build will not catch is the integrations.md:3 link, since it points at a real file — that one needs the inline fix.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: c110f307-d886-4394-a1ea-60bd95e0821e

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[claude]

Documentation review — second pass

Checked against the current head (c388fa7, "Small review fixes"). The integrations.md messaging link is fixed — that was the real blocker. The three new pages hold up: download_team_files.md is properly task-shaped, and the FAQ screenshot removal is clean (no orphaned references to manage_flags_button.png / manage_flags_page.png anywhere in the repo). I also traced every anchor this PR adds — #downloading-team-files, #migrating-to-another-instance, #deleting-a-team, #inviting-a-new-member, #editing-a-members-role, #removing-a-member-or-invitation — and all six match their heading slugs.

Still outstanding from the first review

These were not picked up in the fix commit. Collecting them here rather than re-commenting inline:

• integrations.md:7 — the section still opens with "each row also offers…". With the Name / Category / Provider list gone, "also" has no antecedent and the section never says what a row contains.
• members.md:27-28 — "Selecting Send Invitation…" still refers to a dialog the reader was never shown, and "them" has no referent.
• members.md:39 — the role form is described but there is still no step that commits the change.
• members.md:8 — "sorted alphabetically by email" is still dropped. Worth confirming the sort order actually changed rather than being trimmed as filler.
• mkdocs.yml:174 — nav says "Members", H1 says "Members & Access".

Naming — now three-way

The Data section appears under three spellings, and migrate_team.md:56 works around the mismatch rather than resolving it ("open the Data section, headed Data & migration"):

• mkdocs.yml:178 → Data
• data_migration.md:1, index.md:43 → Data & Migration
• data_migration.md:3, download_team_files.md:12, migrate_team.md:56 → Data & migration

Pick whatever the UI actually renders and use it verbatim throughout. The nav entry can stay short, but the prose should be consistent.

New findings

Three left inline: the run-on sentence in migrate_team.md:113, the how-to-shaped "Deleting a team" section on a concept page, and the nav placement of "Download Team Files" under "Sessions & Data".

Validation — still not run

uv is not installed in this environment and I cannot install it, so zensical build --clean and markdownlint-cli2 remain unrun on my side, same as the first pass. The PR description checks both boxes, so if they passed locally that gap is covered — flagging only that hand-tracing the anchors is not a substitute for the strict: true build.

🤖 Generated with Claude Code

[snopoke]

LGTM but the branch has merge conflicts that need to be resolved