Fix product slug default value and improve permalinks documentation

- Change default product_slug from 'kb/products' to 'kb/product' for consistency
- Add Pro feature overview to README and readme.txt
- Simplify PERMALINKS-TUTORIAL.md with clearer structure and examples
- Remove overly technical details and focus on practical usage
- Improve troubleshooting section with common solutions

Author: ajaydsouza

README.md

@@ -42,6 +42,8 @@ Effortlessly create a powerful, multi-product knowledge base. Boost your support
 
 ### Pro features
 
+[Knowledge Base Pro](https://webberzone.com/plugins/knowledgebase/#pro) enhances the plugin with advanced features for larger documentation sites, including ratings and feedback, a help widget, a powerful custom permalinks engine, premium layouts, and additional admin tools.
+
 - ⭐ __Article Rating & Feedback System__ — Collect binary or 5-star feedback with optional follow-up questions, admin alerts, Bayesian sorting, and GDPR-friendly tracking modes.
 - 💬 __Help Widget__ — Offer an in-app support hub with live search, suggested articles, and a contact form inside a floating assistant.
 - 🧭 __Custom Permalinks Engine__ — Craft advanced URL structures for articles, sections, tags, and products using dynamic placeholders.

docs/PERMALINKS-TUTORIAL.md

@@ -1,184 +1,92 @@
-# Knowledge Base Permalinks Tutorial
+# Knowledge Base Permalinks
 
-This guide explains how permalinks work in the WebberZone Knowledge Base plugin and how to customise them in both the free and Pro versions. Follow the sections below to configure URLs, understand placeholder behaviour, and troubleshoot issues.
+This guide explains how Knowledge Base handles URLs and how to configure custom permalink structures in [Pro](https://webberzone.com/plugins/knowledgebase/).
 
-## 1. Permalink Settings Overview
+## Quick start
 
-All permalink settings are located in **Knowledge Base → Settings → General** under the **Permalinks** section. The Setup Wizard also exposes these fields during onboarding.
+- **Free version**: Set your slugs in **Knowledge Base → Settings → Permalinks**
+- **Pro version**: Enable **custom permalinks** and use placeholders like `%product_name%` or `%section_name%` in your article structure
 
-### 1.1 Available Settings
+## Permalink settings
 
-- **Knowledge Base slug** (`kb_slug`): Sets the base path for the Knowledge Base post type. Default: `knowledgebase`. Used in free version and as fallback in Pro.
-- **Product slug** (`product_slug`): Base path for product archives. Default: `kb/product`. Supports placeholders in Pro (e.g., `support/product`).
-- **Section slug** (`category_slug`): Base path for section archives. Default: `kb/section`. Supports placeholders in Pro (e.g., `support/product/%product_name%/%section_name%`).
-- **Tags slug** (`tag_slug`): Base path for tag archives. Default: `kb/tags`. Supports placeholders in Pro (e.g., `support/tag`).
-- **Article Permalink Structure** (`article_permalink`): Custom structure for article URLs. **Pro feature only**. Default: empty (uses `{kb_slug}/%postname%`).
+All permalink settings are located in **Knowledge Base → Settings → General** under the **Permalinks** section.
 
-### 1.2 Free Version Behavior
+### Available settings
 
-- Free version uses standard WordPress permastruct rewrite rules for all taxonomies.
-- Article URLs follow the pattern: `{kb_slug}/%postname%`
-- Example: If `kb_slug` is `knowledgebase`, articles appear at `/knowledgebase/article-name/`
-- Taxonomy slugs can be customized but do not support placeholders.
-- To use placeholders and custom article structures, upgrade to Pro.
+- **Knowledge Base slug** (`kb_slug`): Sets the base path for the Knowledge Base. Default: `knowledgebase`
+- **Product slug** (`product_slug`): Base path for product archives. Default: `kb/product`
+- **Section slug** (`category_slug`): Base path for section archives. Default: `kb/section`
+- **Tags slug** (`tag_slug`): Base path for tag archives. Default: `kb/tags`
+- **Article Permalink Structure** (`article_permalink`): Custom structure for articles. **Pro feature only**
 
-## 2. Pro: Custom Permalinks Engine
+## Pro: custom permalinks engine
 
-The Pro module activates custom permalink handling when:
+Pro adds a custom permalinks engine that lets you control your URL structure using placeholders.
 
-- A custom `article_permalink` structure is set (with or without placeholders)
-- Taxonomy slugs include placeholders (e.g., `support/product/%product_name%/%section_name%`)
+**When this activates:**
 
-### 2.1 Supported Placeholders
+- Pro is installed and activated
+- You enter a custom structure in the article permalink field (anything other than the default `%postname%`)
 
-```text
-%product_name%  %section_name%  %section_id%
-%tag_name%      %post_id%       %postname%  %author%
-```
-
-These map to query variables used when building rewrite rules and are sanitised before use.
-
-Placeholders can be filtered with `wzkb_custom_permalink_placeholders`, allowing developers to register additional tokens.
-
-### 2.2 How Custom Permalinks Work
-
-The Pro version automatically builds your article and taxonomy URLs based on the structures you define:
-
-1. **Rewrite rules are generated** - Custom rewrite rules are created for articles, products, sections, and tags based on your structures.
-2. **Placeholders get replaced** - Each placeholder like `%product_name%` or `%section_name%` is replaced with the actual product or section assigned to that article.
-3. **URLs are built automatically** - The plugin combines your custom structure with the replaced placeholders to create the final URL.
-4. **Smart conflict handling** - When multiple structures share the same base path (e.g., article and section structures both starting with `support/product/`), the plugin prioritizes article rules to prevent misrouting.
-5. **Permastruct is disabled** - When custom structures are used, WordPress's default taxonomy permastruct rules are disabled to avoid conflicts. Custom rewrite rules handle all routing instead.
-
-**Example:** If you set:
-
-- `kb_slug`: `support/knowledgebase`
-- `article_permalink`: `support/product/%product_name%/%section_name%/%postname%`
-
-And create an article titled "Installation Guide" in the "Getting Started" section of the "Widget Suite" product, the URL becomes:
-`/support/product/widget-suite/getting-started/installation-guide/`
-
-### 2.3 What Each Placeholder Does
-
-- **%product_name%** - Replaced with the product slug (e.g., `widget-suite`)
-- **%section_name%** - Replaced with the section slug (e.g., `getting-started`)
-- **%section_id%** - Replaced with the section ID number (e.g., `42`)
-- **%tag_name%** - Replaced with the tag slug (e.g., `troubleshooting`)
-- **%postname%** - Replaced with the article slug (e.g., `installation-guide`)
-- **%post_id%** - Replaced with the article ID number (e.g., `123`)
-- **%author%** - Replaced with the author username (e.g., `john-smith`)
-
-**Tip:** Hierarchical placeholders like `%section_name%` can include parent sections, creating nested URLs like `/parent-section/child-section/`.
+**Supported placeholders:**
 
-## 3. Building Custom Structures
+- `%product_name%` — The product slug (from your Products taxonomy)
+- `%section_name%` — The top-level section slug for articles
+- `%postname%` — The article slug
+- `%post_id%` — The article ID
+- `%author%` — The author username
 
-### 3.1 Example: Custom Prefix with Product → Section → Article
+**How custom permalinks work:**
 
-```text
-kb_slug: support/knowledgebase
-product_slug: support/product
-category_slug: support/product/%product_name%/%section_name%
-article_permalink: support/product/%product_name%/%section_name%/%postname%
-```
-
-- Produces article URLs like `/support/product/widget-suite/getting-started/installing-widget-suite/`
-- Produces section URLs like `/support/product/widget-suite/getting-started/`
-- Produces product URLs like `/support/product/widget-suite/`
-- Custom prefix `support/` is shared across all structures to avoid KB slug prepending
-- Requires each article to have a product and section assigned; otherwise the placeholder resolves to an empty segment
-
-### 3.2 Example: Simple Structures Without Placeholders
-
-```text
-kb_slug: knowledgebase
-product_slug: kb/product
-category_slug: kb/section
-tag_slug: kb/tags
-article_permalink: %product_name%/%section_name%/%postname%
-```
+1. You define a structure using placeholders
+2. Pro generates the appropriate rewrite rules
+3. Articles use your custom structure
+4. Taxonomy archives (products, sections, tags) use their configured slugs
 
-- Product URLs: `/kb/product/widget-suite/` (term name appended automatically)
-- Section URLs: `/kb/section/getting-started/` (term name appended automatically)
-- Tag URLs: `/kb/tags/troubleshooting/` (term name appended automatically)
-- Article URLs: `/knowledgebase/widget-suite/getting-started/installing-widget-suite/`
+**Example:**
 
-### 3.3 Example: Numeric Identifiers
+Set `kb_slug` to `help` and `article_permalink` to:
 
 ```text
-article_permalink: %section_id%/%post_id%/%postname%
+%product_name%/%section_name%/%postname%
 ```
 
-- Helpful for legacy systems needing numeric identifiers in the URL
-- Produces URLs like `/42/123/article-slug/`
-- Rewrite tags for `section_id` and `post_id` are registered automatically
-
-### 3.4 Term Archive Structures with Placeholders
-
-- **Sections with product context**: `category_slug` set to `support/product/%product_name%/%section_name%` nests sections under their products
-- **Tags with section context**: `tag_slug` set to `support/product/%product_name%/%section_name%/%tag_name%` provides full context
-- When taxonomy slugs include placeholders, custom rewrite rules are generated to handle the dynamic segments
-
-## 4. Configuration Workflow
-
-1. **Plan taxonomy usage**: Decide which placeholders are meaningful for your data hierarchy.
-2. **Update Knowledge Base → Settings → General → Permalinks** with desired structures.
-3. **Save settings** to trigger rewrite rule regeneration (automatic in setup and admin UI).
-4. **Flush rewrite rules**: Visit **Settings → Permalinks** and click **Save Changes** to ensure WordPress recognizes the new rules.
-5. **Assign terms** consistently (products, sections, tags) so placeholders resolve correctly.
-6. **Test URLs**:
-   - Visit an article, product, section, and tag page.
-   - Verify the URL matches your configured structure.
-   - Use the WordPress Rewrite Rules Inspector or `wp rewrite list` CLI if needed.
-
-## 5. How Pro Handles Custom Structures
-
-### 5.1 Rewrite Rule Generation
+Result: `https://example.com/help/wordpress/getting-started/`
 
-When Pro is enabled and custom structures are detected:
+**Note:** `%section_name%` for articles always returns the top-level parent slug, not the full hierarchy.
 
-1. **Custom rewrite rules are created** for articles, products, sections, and tags based on your configured structures
-2. **Taxonomy permastruct is disabled** to prevent conflicts with custom rules
-3. **Article rules are prioritized** to ensure article URLs are matched before product/section archives
-4. **Child section rules are conditionally disabled** when article structures have more segments than section structures, preventing misrouting
+## Configuration workflow
 
-### 5.2 Permalink Generation
+1. Open Knowledge Base → Settings → General
+2. Configure your base slugs (kb_slug, product_slug, etc.)
+3. Pro users: set your custom article permalink structure
+4. Save changes
 
-When generating permalinks for articles and taxonomies:
+> **Important:** After changing permalink settings, visit Settings → Permalinks in WordPress to flush your rewrite rules. This prevents 404 errors.
 
-1. **Placeholders are replaced** with actual term/post values
-2. **Term slugs are appended** automatically for taxonomy structures without explicit placeholders
-3. **KB slug is intelligently prepended** only when the custom structure doesn't already start with the KB slug's first segment
-4. **Final URL is constructed** and returned via `get_term_link()` and `get_permalink()` filters
+## Troubleshooting
 
-### 5.3 Fallback Behavior Without Pro
+### 404 errors after changing settings
 
-If Pro is not enabled but custom structures are configured:
+Visit Settings → Permalinks in WordPress to flush your rewrite rules.
 
-- **Permastruct rewrite rules remain active** to ensure URLs work
-- **Custom article structures are ignored** and default `{kb_slug}/%postname%` is used
-- **Taxonomy slugs work** but placeholders are not supported
-- **No custom rewrite rules are generated** - WordPress handles routing via permastruct
+### URLs not matching your structure
 
-## 6. Developer Hooks & Extensibility
+- Check you've entered a custom structure (not just `%postname%`)
+- Ensure Pro is active
+- Verify your placeholder syntax
 
-- `wzkb_custom_permalink_placeholders`: Register extra placeholders or override default mappings.
-- `wzkb_article_permalink_structure` and `wzkb_term_permalink_structure`: Filter the resolved path before it is prefixed with the KB slug.
-- `wzkb_after_setting_output`: Used by Pro to inject placeholder documentation beneath the settings header for admins.
+### Conflicts with other plugins
 
-## 7. Troubleshooting Tips
+Some SEO plugins modify rewrite rules. If you experience conflicts:
 
-- **404 errors**: Visit **Settings → Permalinks** and click **Save Changes** to flush rewrite rules. This is the most common fix.
-- **Empty placeholders**: Ensure articles have the required product/section/tag assignments. Missing assignments result in empty URL segments.
-- **Wrong content loading**: If an article URL loads a product/section archive instead, flush rewrite rules. Pro prioritizes article rules, but rule order depends on proper flushing.
-- **Conflicting slugs**: Avoid reusing the KB slug for other pages. Pro attempts to resolve clashes by detecting shared prefixes, but unique slugs prevent ambiguity.
-- **Taxonomy URLs not working**: If product/section/tag URLs return 404, ensure their slugs are configured in settings and rewrite rules are flushed.
-- **Testing root-level URLs**: When using `%postname%` without a prefix, verify that article slugs do not collide with regular posts or pages.
-- **Pro not enabled**: Custom article structures are ignored if Pro is not active. Free version uses default `{kb_slug}/%postname%` structure.
+- Test with other plugins disabled
+- Check your rewrite rules using a plugin like [Rewrite Rules Inspector](https://wordpress.org/plugins/rewrite-rules-inspector/)
+- Priority is given to articles over taxonomy archives to prevent conflicts
 
-## 8. Summary
+## Summary
 
-- **Free version** supports basic slug customization for taxonomies and default article URLs using the KB slug.
-- **Pro version** unlocks placeholder-driven structures for articles and taxonomies with intelligent rewrite rule generation and conflict resolution.
-- **Custom prefixes** (e.g., `support/product/`) allow you to organize URLs outside the KB slug hierarchy.
-- **Consistent taxonomy assignments** and thoughtful structure planning ensure clean, SEO-friendly URLs tailored to your knowledge base.
-- **Rewrite rule flushing** is essential after any permalink setting changes to ensure WordPress recognizes the new URL patterns.
+- Free version: configure base slugs for articles and taxonomies
+- Pro version: build custom URL structures using placeholders
+- Always flush rewrite rules after changing permalink settings
+- Pro handles smart conflict resolution between articles and taxonomies

includes/class-cpt.php

@@ -257,7 +257,7 @@ public static function register_taxonomies() {
 
 		$catslug     = self::sanitize_slug( \wzkb_get_option( 'category_slug', 'kb/section' ) );
 		$tagslug     = self::sanitize_slug( \wzkb_get_option( 'tag_slug', 'kb/tags' ) );
-		$productslug = self::sanitize_slug( \wzkb_get_option( 'product_slug', 'kb/products' ) );
+		$productslug = self::sanitize_slug( \wzkb_get_option( 'product_slug', 'kb/product' ) );
 
 		// Register products taxonomy first.
 		// Disable permastruct rewrite only if Pro is enabled and custom article structure is used, to avoid conflicts.

readme.txt

@@ -35,6 +35,8 @@ Effortlessly create a powerful, multi-product knowledge base. Boost your support
 
 ### Pro features
 
+[Knowledge Base Pro](https://webberzone.com/plugins/knowledgebase/#pro) enhances the plugin with advanced features for larger documentation sites, including ratings and feedback, a help widget, a powerful custom permalinks engine, premium layouts, and additional admin tools.
+
 - ⭐ __Article Rating & Feedback System__ — Collect binary or 5-star feedback with optional follow-up questions, admin alerts, Bayesian sorting, and GDPR-friendly tracking modes.
 - 💬 __Help Widget__ — Offer an in-app support hub with live search, suggested articles, and a contact form inside a floating assistant.
 - 🧭 __Custom Permalinks Engine__ — Craft advanced URL structures for articles, sections, tags, and products using dynamic placeholders.