Improve customer documentation journeys

.github/workflows/docs-quality.yml

@@ -2,6 +2,11 @@ name: Documentation quality
 
 on:
   pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
   push:
     branches:
       - v1.0
@@ -19,4 +24,7 @@ jobs:
         with:
           node-version: 22
       - run: npm run check
+      - name: Enforce live-release gates
+        if: (github.event_name == 'pull_request' && github.base_ref == 'v1.0' && github.event.pull_request.draft == false) || github.ref == 'refs/heads/v1.0'
+        run: npm run check:release
       - run: npm run check:media

CONTRIBUTING.md

@@ -14,7 +14,7 @@ Keep one primary purpose per page. Link to nearby troubleshooting instead of add
 
 ## Work on the correct branch
 
-- Use `v1.0_kb-screenshot-system` for the current first-release ReadMe preview and review.
+- Use `v1.0_kb-customer-docs-improvements` for the current customer-experience preview and review.
 - Keep upcoming product behavior on an unpublished feature branch.
 - Merge to `v1.0` only after Product and Support approval.
 - Do not modify API Reference files as part of customer workflow documentation.
@@ -54,23 +54,25 @@ release-status: draft
 
 Use `release-status: draft` while any verification, screenshot, video, or review evidence is pending. Change it to `ready` only when the page has a verified release and date, approved media, and both required reviews.
 
+ReadMe renders the page title from frontmatter. Do not repeat it as a body H1; begin body sections at H2.
+
 ## Workflow page contract
 
 Every workflow must include:
 
 - A 30-second **If you're stuck** section with the fastest safe checks
 - Outcome, audience, permission, time, and changes made
 - Prerequisites and warnings before consequential actions
-- A field, option, action, or checkpoint table using exact released UI labels
+- Compact field, option, action, or checkpoint tables using exact released UI labels; keep tables to four columns or fewer
 - Numbered steps using released UI labels
 - Expected results at important checkpoints
 - Troubleshooting beside the step where failure occurs
 - A final verification procedure
 - Undo, detach, or deletion guidance when data changes
-- Learn, Show me, and Do it links where available
+- A **Learn and continue** section with a relevant concept and the exact **In WanAware** navigation path
 - Related next steps and the standard Support footer
 
-The article is authoritative. Hide an embedded clip as soon as its UI or behavior becomes inaccurate.
+The article is authoritative. Add **Show me** only when an approved clip exists, and hide the clip as soon as its UI or behavior becomes inaccurate.
 
 ## Troubleshooting page contract
 
@@ -119,7 +121,7 @@ Before publication:
 
 1. Run every procedure in Harbor Meridian Systems with a normal customer role and the appropriate administrator role.
 2. Verify permissions, side effects, background processing, messages, recovery, links, media, and cleanup.
-3. Run `npm run check`.
+3. Run `npm run check`. For a pull request targeting `v1.0`, also run `npm run check:release`.
 4. Render the ReadMe branch preview and run Docs Audit.
 5. Obtain Product approval for behavior and Support approval for clarity, diagnosis, and escalation.
 6. Confirm the complete pull request does not contain planning, agent instruction, handoff, or status documents.

docs/administration-and-personal-settings/choose-a-theme.md

@@ -28,8 +28,6 @@ video-status: not-planned
 release-status: draft
 -->
 
-# Choose a theme
-
 **Outcome:** Change your personal appearance without changing another member's settings.
 
 **For:** Signed-in WanAware members
@@ -61,6 +59,9 @@ Theme changes affect your view. They do not change company data or another membe
 1. Select **Theme Settings**.
 2. Choose **Light** or **Dark** mode.
 3. Under **Assigned Themes** or **Color Themes**, select the intended preset.
+
+![Theme Settings showing the available Light and Dark modes and color presets.](https://files.readme.io/bababdfbea8a1fbebc998a60a50586adea6315925cc1016f5a2705f1cc642cfe-theme-settings-light-and-dark.png)
+
 4. Close the Theme Settings panel.
 
 **Expected result:** The Portal updates immediately and keeps your selection when you move to another page.
@@ -75,11 +76,14 @@ Open Assets and Administration, then confirm text, controls, tables, and dialogs
 
 Open **Theme Settings** and choose the previous mode and preset.
 
-## Learn, show me, do it
+## Learn and continue
 
 - **Learn:** [Product map and terminology](https://docs.wanaware.com/docs/product-map-and-terminology)
-- **Show me:** Approved Light and Dark screenshots are pending capture and privacy review.
-- **Do it:** Select **Theme Settings** in your WanAware workspace.
+- **In WanAware:** Select **Theme Settings** in your WanAware workspace.
+
+## Next steps
+
+- [Manage your profile and security](https://docs.wanaware.com/docs/manage-profile-and-security)
 
 ## Get help
 

docs/administration-and-personal-settings/create-and-edit-roles.md

@@ -20,15 +20,13 @@ permission: read roles and create roles; update roles for edits
 product-area: Administration and access
 content-owner: Product
 review-owner: Support
-last-verified: pending
+last-verified: 2026-09-04
 last-verified-release: pending
 screenshot-set: administration-roles
 video-status: not-planned
 release-status: draft
 -->
 
-# Create and edit Roles
-
 **Outcome:** Create or update a customer Role with the smallest set of Permissions needed for a job.
 
 **For:** Customer administrators
@@ -52,22 +50,28 @@ release-status: draft
 
 | UI label | Purpose | What to enter or select | Where it appears later |
 | --- | --- | --- | --- |
-| **Role Name** | Identifies the access profile | A unique, job-based name such as `Asset reviewer` | Role list and member assignment |
+| **Name** | Identifies the access profile | A unique, job-based name such as `Asset reviewer` | Role list and member assignment |
 | **Permissions** | Controls visible areas and allowed actions | Only the `action resource` pairs the job requires | The member's navigation and available controls |
 | **Create Role** | Saves a new customer Role | Select after reviewing the name and Permissions | Role list |
 
 ## Create a Role
 
 1. Open **Administration → IAM → Roles**.
+
+![IAM Roles list showing system and customer Roles, member counts, Permissions, and the Create Role action.](https://files.readme.io/3431077d146ae19f5296ef7967e8f70f01c4b0ea784da2adb5f81cc739f95869-iam-roles-list.png)
 2. Select **Create Role**.
-3. Enter **Role Name** using a job or responsibility, not a person's name.
+3. Enter **Name** using a job or responsibility, not a person's name.
 4. In **Permissions**, expand each product area and select the required actions.
+
+![Create Role page showing the Name field and grouped action-resource Permission selections.](https://files.readme.io/0534e10ef59e6fdbdafd9fc2c149bf61b655dc11eaa9d3bf2132d6bc2ddaaa0a-iam-role-editor.png)
 5. Recheck navigation dependencies. For example, Billing requires all four read permissions listed in [Understand billing](https://docs.wanaware.com/docs/understand-billing).
 6. Select **Create Role**.
 
 **Expected result:** The Role opens or appears in the Roles list with the selected Permissions.
 
-If saving fails, keep the page open, copy the Role Name and selected Permission list, and check for a duplicate name or a permission that your own account cannot assign.
+![Saved customer Role showing one selected read Assets Permission on the Permissions tab.](https://files.readme.io/1b40d0ecb3506785ef2487af33918fc84bf3819e3e83e24de677b90e04ac6cd8-image.png)
+
+If saving fails, keep the page open, copy the **Name** and selected Permission list, and check for a duplicate name or a Permission that your own account cannot assign.
 
 ## Edit a customer Role
 
@@ -86,13 +90,30 @@ Assign the Role to a test member with the intended responsibilities. Have that m
 
 ## Undo this change
 
-Restore the previous Permission list and save again. If the Role is no longer needed, first move assigned members to an approved Role; do not delete a Role while its impact is unknown.
+To reverse a Permission change, restore the previous Permission list and save again.
+
+To remove a customer Role that is no longer needed:
+
+1. Move every assigned member to an approved replacement Role.
+2. Open the unused Role from **Administration → IAM → Roles**.
+3. Select **Delete Role**.
+4. Confirm that the dialog names the intended customer Role and states that deletion cannot be undone.
 
-## Learn, show me, do it
+![Delete Role confirmation identifying the selected customer Role and warning that deletion cannot be undone.](https://files.readme.io/606771bd138d3b448d60a4885c49d19e58c77eead82c98aec7a9c38fdb95d5ce-iam-role-delete-confirmation.png)
+
+5. Select **Delete**.
+
+**Expected result:** WanAware reports **Role deleted**, returns to the Roles list, and the deleted Role no longer appears. If members still depend on the Role or its impact is unclear, select **Cancel** and review the **Users** tab first.
+
+## Learn and continue
 
 - **Learn:** [Understand Roles and Permissions](https://docs.wanaware.com/docs/understand-roles-and-permissions)
-- **Show me:** Use the written steps until an IAM recording is approved.
-- **Do it:** Open `/administration/iam/roles` in your WanAware workspace.
+- **In WanAware:** Open `/administration/iam/roles` in your WanAware workspace.
+
+## Next steps
+
+- [Invite users and assign Roles](https://docs.wanaware.com/docs/invite-users-and-assign-roles)
+- [Understand Roles and Permissions](https://docs.wanaware.com/docs/understand-roles-and-permissions)
 
 ## Get help
 

docs/administration-and-personal-settings/index.md

@@ -15,8 +15,30 @@ metadata:
   robots: index
 ---
 
-# Administration and personal settings
-
 Company administrators manage shared settings, access, and Billing. Each user manages their own profile, security settings, and theme.
 
-If an action is unavailable, ask an administrator to compare your active Roles with its required Permission. Start with [Missing pages, actions, or permissions](https://docs.wanaware.com/docs/missing-pages-actions-or-permissions).
+## Access
+
+- [Invite users and assign Roles](https://docs.wanaware.com/docs/invite-users-and-assign-roles)
+- [Understand Roles and Permissions](https://docs.wanaware.com/docs/understand-roles-and-permissions)
+- [Create and edit Roles](https://docs.wanaware.com/docs/create-and-edit-roles)
+- [Manage pending invitations](https://docs.wanaware.com/docs/manage-pending-invitations)
+
+## Company and personal settings
+
+- [Manage company settings](https://docs.wanaware.com/docs/manage-company-settings)
+- [Manage your profile and security](https://docs.wanaware.com/docs/manage-profile-and-security)
+- [Choose a theme](https://docs.wanaware.com/docs/choose-a-theme)
+
+## Billing
+
+- [Understand billing, usage, payments, and invoices](https://docs.wanaware.com/docs/understand-billing)
+- [View your plan and usage](https://docs.wanaware.com/docs/view-plan-and-usage)
+- [Manage payment methods](https://docs.wanaware.com/docs/manage-payment-methods)
+- [View billing history and invoices](https://docs.wanaware.com/docs/view-billing-history-and-invoices)
+
+## Fix a problem
+
+- [A page or action is missing](https://docs.wanaware.com/docs/missing-pages-actions-or-permissions)
+- [I cannot sign in, reset my password, or complete MFA](https://docs.wanaware.com/docs/sign-in-password-and-mfa)
+- [A billing or payment action fails](https://docs.wanaware.com/docs/billing-and-payment-failures)

docs/administration-and-personal-settings/invite-users-and-assign-roles.md

@@ -8,6 +8,7 @@ metadata:
   description: Invite WanAware members, assign roles, and verify their access.
   keywords:
     - invite user
+    - invite teammate
     - IAM
     - assign role
     - member access
@@ -28,8 +29,6 @@ video-status: not-planned
 release-status: draft
 -->
 
-# Invite users and assign roles
-
 **Outcome:** Invite a company member and assign the smallest role that supports their work.
 
 **For:** Customer administrators
@@ -66,6 +65,8 @@ release-status: draft
 3. Enter the person's business name in **User name**.
 4. Enter the exact company address in **Email**.
 5. Under **Roles**, select at least one approved Role. If none is selected, the form reports **Select at least one role**.
+
+![Create User form showing the User name, Email, Role selection, and Create User action with sample values.](https://files.readme.io/d36aede7c22d78f94ef1b914ecab0697bee19100c324c60c78a07f387c4f8d17-invite-user-form.png)
 6. Review the address and Roles, then select **Create User** once.
 
 **Expected result:** WanAware reports **Invitation sent**, and the member appears with **Invite Status** set to **Pending** until they accept.
@@ -79,7 +80,7 @@ If the email already belongs to a member, update the existing record rather than
 3. Ask them to sign in and open one page required for their work.
 4. Confirm they do not see unrelated administration actions.
 
-If the expected page is missing, use [Missing pages, actions, or permissions](https://docs.wanaware.com/docs/missing-pages-actions-or-permissions).
+If the expected page is missing, use [A page or action is missing](https://docs.wanaware.com/docs/missing-pages-actions-or-permissions).
 
 ## Check your result
 
@@ -89,11 +90,15 @@ The member is active in the correct company, has the intended role, can complete
 
 Do not share an invitation with a different person. If the wrong Role was assigned, correct the existing user record before resending. If the wrong email was invited, stop and contact Support rather than assuming an unverified cancellation or deletion control exists. Before reducing your own administrator access, verify another active administrator can manage IAM.
 
-## Learn, show me, do it
+## Learn and continue
 
 - **Learn:** [Understand Roles and Permissions](https://docs.wanaware.com/docs/understand-roles-and-permissions)
-- **Show me:** Use the written steps until an access-management clip is approved.
-- **Do it:** Open `/administration/iam` in your WanAware workspace.
+- **In WanAware:** Open `/administration/iam` in your WanAware workspace.
+
+## Next steps
+
+- [Manage pending invitations](https://docs.wanaware.com/docs/manage-pending-invitations)
+- [Create and edit Roles](https://docs.wanaware.com/docs/create-and-edit-roles)
 
 ## Get help
 

docs/administration-and-personal-settings/manage-company-settings.md

@@ -27,8 +27,6 @@ video-status: not-planned
 release-status: draft
 -->
 
-# Manage company settings
-
 **Outcome:** Update an approved company setting and confirm the shared result.
 
 **For:** Customer administrators
@@ -66,6 +64,8 @@ release-status: draft
 3. Confirm the company name or identifier.
 4. Change only the approved field.
 5. Preview logo cropping and contrast before accepting an uploaded image.
+
+![Platform Customization settings showing Dark Mode Logo and Light Mode Logo upload controls.](https://files.readme.io/86716aa8e278f798f5e6bba4691e8f856f7e7ad6431ec1bc1e67dcc5d03621b6-company-branding.png)
 6. Select **Save**.
 
 **Expected result:** WanAware confirms the save and the value remains after refresh.
@@ -80,11 +80,15 @@ Refresh the page and confirm the saved value. Ask a second permitted user to che
 
 Restore the recorded value and save again. Contact Support if the setting has no edit control or its effect cannot be reversed safely.
 
-## Learn, show me, do it
+## Learn and continue
 
 - **Learn:** [Understand Roles and Permissions](https://docs.wanaware.com/docs/understand-roles-and-permissions)
-- **Show me:** Use the written steps until a company-settings clip is approved.
-- **Do it:** Open `/administration/general/company` in your WanAware workspace.
+- **In WanAware:** Open `/administration/general/company` in your WanAware workspace.
+
+## Next steps
+
+- [Invite users and assign Roles](https://docs.wanaware.com/docs/invite-users-and-assign-roles)
+- [Understand Roles and Permissions](https://docs.wanaware.com/docs/understand-roles-and-permissions)
 
 ## Get help
 

docs/administration-and-personal-settings/manage-payment-methods.md

@@ -27,8 +27,6 @@ video-status: not-planned
 release-status: draft
 -->
 
-# Manage payment methods
-
 **Outcome:** Add, update, or remove an authorized payment method and confirm only its masked details are displayed.
 
 **For:** Billing administrators
@@ -76,11 +74,15 @@ Refresh **Payment & Billing**, reopen **View details**, and confirm the expected
 
 Restore the prior billing contact or approved method and verify again. Removing a payment method can affect renewal; do not remove the only method unless the product confirmation and your billing policy permit it.
 
-## Learn, show me, do it
+## Learn and continue
 
 - **Learn:** [Understand billing](https://docs.wanaware.com/docs/understand-billing)
-- **Show me:** Billing visuals require masked test data and privacy approval before publication.
-- **Do it:** Open `/administration/billing` in your WanAware workspace and select **Payment & Billing**.
+- **In WanAware:** Open `/administration/billing` in your WanAware workspace and select **Payment & Billing**.
+
+## Next steps
+
+- [View your plan and usage](https://docs.wanaware.com/docs/view-plan-and-usage)
+- [View billing history and invoices](https://docs.wanaware.com/docs/view-billing-history-and-invoices)
 
 ## Get help
 

docs/administration-and-personal-settings/manage-pending-invitations.md

@@ -27,8 +27,6 @@ video-status: not-planned
 release-status: draft
 -->
 
-# Manage pending invitations
-
 **Outcome:** Confirm whether a member accepted an invitation and resend the existing invitation when it remains Pending.
 
 **For:** Customer administrators
@@ -74,11 +72,15 @@ Ask the member to open the newest email and complete the invitation. Refresh the
 
 A sent email cannot be recalled. If the address or Role is wrong, do not forward the invitation; contact Support with the member email and timestamp so the access path can be reviewed safely.
 
-## Learn, show me, do it
+## Learn and continue
 
 - **Learn:** [Understand Roles and Permissions](https://docs.wanaware.com/docs/understand-roles-and-permissions)
-- **Show me:** Use the written steps until an IAM recording is approved.
-- **Do it:** Open `/administration/iam` in your WanAware workspace.
+- **In WanAware:** Open `/administration/iam` in your WanAware workspace.
+
+## Next steps
+
+- [Invite users and assign Roles](https://docs.wanaware.com/docs/invite-users-and-assign-roles)
+- [Fix sign-in, password, or MFA problems](https://docs.wanaware.com/docs/sign-in-password-and-mfa)
 
 ## Get help