Merge pull request #7 from vapvarun/docs/1.4.x-coverage

docs(website): cover 1.4.x features + clear stale references

Author: vapvarun

docs/website/admin-settings/01-general.md

@@ -72,7 +72,7 @@ Turn this off if your community is members-only and you do not want any content
 **Default:** `true` (on)
 **Location:** General tab → Access section
 
-When enabled, any action that writes data (posting, replying, voting, following) requires the user to be logged in. Guests are redirected to the WordPress login page.
+When enabled, any action that writes data (posting, replying, voting, following) requires the user to be logged in. Guests are routed to Jetonomy's in-page sign-in form (no wp-login.php bounce) and returned to whatever they were doing once they sign in.
 
 This is always recommended on. Disable it only if you are running a very specific open-participation setup where anonymous contributions make sense.
 

docs/website/admin-settings/04-appearance.md

@@ -49,6 +49,50 @@ When on, the `--jt-accent` token pulls from `--wp--preset--color--primary` in yo
 
 Turn this off if you have set a custom accent color above and do not want theme updates to override it.
 
+## Layout
+
+Jetonomy 1.4.0 added a Layout panel with three controls that decide how the community canvas sits inside your active theme. Every option defaults to **Theme Default**, so existing installs see no visual change after the upgrade. When you do change a value, Jetonomy emits a small block of CSS scoped to `body.jt-page` - the rules only apply on community routes and never leak into the rest of your site.
+
+### Container Width
+
+**Setting:** `container_width`
+**Default:** Theme Default
+**Options:** Theme Default, Full Width, Custom (px)
+**Location:** Appearance tab → Layout section
+
+Controls how wide the community canvas can grow before it stops expanding.
+
+- **Theme Default** - Inherits the host theme's content container width. Use this when your theme's reading width already feels right.
+- **Full Width** - Lets the community stretch edge-to-edge of the viewport. Best for kanban-style spaces, leaderboards, and dense feeds that benefit from horizontal room.
+- **Custom (px)** - Pins the canvas to a specific pixel width (e.g. `1280`). Useful when you want a wider reading column than the theme provides without going fully edge-to-edge.
+
+### Theme Sidebar
+
+**Setting:** `theme_sidebar`
+**Default:** Theme Default
+**Options:** Theme Default, Hide on community pages
+**Location:** Appearance tab → Layout section
+
+Decides whether the host theme's sidebar shows on community routes.
+
+- **Theme Default** - Leaves the theme's sidebar exactly where the theme renders it.
+- **Hide on community pages** - Suppresses the host theme's sidebar across `/community/*` so the forum renders at full width even when the rest of the site has a sidebar everywhere. Pair this with **Full Width** above when you want a true full-bleed community experience.
+
+### Page Padding
+
+**Setting:** `page_padding`
+**Default:** Theme Default
+**Options:** Theme Default, None, Comfortable
+**Location:** Appearance tab → Layout section
+
+Adjusts the inline padding around the community canvas.
+
+- **Theme Default** - Uses whatever inline padding the theme provides.
+- **None** - Removes the inline padding so the community sits flush against the viewport edges. Good for themes that already hug the edges.
+- **Comfortable** - Adds a generous inline padding. Useful for themes that hug the edges too tightly and leave content butting against the screen on mobile.
+
+> **Tip:** If your theme has a sidebar everywhere but you want the community to feel like a standalone app, set **Container Width** to Full Width, **Theme Sidebar** to Hide on community pages, and **Page Padding** to Comfortable. The rest of your site keeps the original theme layout.
+
 ## Layout Density
 
 **Setting:** `layout_density`

docs/website/admin-settings/05-seo.md

@@ -45,6 +45,17 @@ Private, hidden, and archived spaces are excluded. Draft and scheduled posts are
 
 > **Tip:** Check **Settings → Reading → Search engine visibility** is not set to "Discourage search engines" or your sitemap will be disregarded.
 
+### Sitemap Link
+
+**Location:** SEO tab → Sitemap section
+
+Right next to the toggle is a button that surfaces the live sitemap URL for your install (typically `https://example.com/wp-sitemap.xml`). Copy the URL straight from the admin and submit it to:
+
+- [Google Search Console](https://search.google.com/search-console) - the standard sitemap submission flow under Index → Sitemaps
+- [Bing Webmaster Tools](https://www.bing.com/webmasters) - submit under Sitemaps in the left nav
+
+You only need to submit the sitemap once per search engine. Google and Bing both recrawl the file automatically after the first submission, so new posts and spaces appear in the index without any further action.
+
 ## Schema Markup
 
 **Setting:** `seo_schema`
@@ -107,6 +118,35 @@ Jetonomy outputs Open Graph and Twitter Card meta tags automatically on all publ
 
 > **Note:** If you use an SEO plugin like Yoast SEO, RankMath, or The SEO Framework, its OG tags may override Jetonomy's. This is fine - SEO plugin output takes priority via standard WordPress `wp_head` hook priority ordering.
 
+### Twitter / X Handle
+
+**Setting:** `seo_twitter_handle`
+**Default:** Empty
+**Location:** SEO tab → Twitter handle
+
+Enter your community's Twitter or X handle (with or without the leading `@`). When set, Jetonomy emits `twitter:site` and `twitter:creator` meta tags on every community page that does not already declare a per-page override. This gives X / Twitter a verified attribution to display alongside link previews and unlocks richer card layouts.
+
+Leave this empty if the community has no Twitter / X presence - Jetonomy simply omits the tags instead of emitting empty ones.
+
+### Default Share Image
+
+**Setting:** `seo_default_share_image`
+**Default:** Empty
+**Location:** SEO tab → Default share image
+
+Pick an image from the WordPress media library to use as the fallback `og:image` whenever a specific post does not have an image of its own. Posts that already include their own image continue to use that image - this setting only kicks in when there is nothing else to show.
+
+**Recommended specs:**
+
+| Property | Value |
+|---|---|
+| Dimensions | 1200 x 630 px |
+| Format | PNG or JPG |
+| File size | Under 5 MB |
+| Aspect ratio | 1.91:1 |
+
+Twitter / X, Facebook, LinkedIn, and Slack all read this image when generating link previews, so picking a branded fallback (logo + community name on a clean background) keeps shared links recognizable.
+
 ## What's Next?
 
 Set up anti-spam protection to keep your community clean without frustrating legitimate members.

docs/website/developer-guide/08-visibility-and-access-matrix.md

@@ -0,0 +1,155 @@
+Jetonomy 1.4.1 introduced the **Public / Private community toggle** documented in [Access Control Settings](../admin-settings/07-access-control.md). On the code side that toggle is enforced through two pieces:
+
+1. A small helper class - `Jetonomy\Visibility` - that every front-end template and REST permission callback can call to decide "is this caller allowed to see community content right now?"
+2. A shell script - `bin/access-matrix-check.sh` - that walks every public REST route as every role in both modes and asserts the responses match the documented contract.
+
+This page covers both.
+
+**Namespace:** `Jetonomy\`
+**Source:** `includes/class-visibility.php`, `bin/access-matrix-check.sh`
+
+---
+
+## Why the helper exists
+
+Before 1.4.1 the public/private check was sprinkled across templates, the template loader, and individual REST controllers. Each call site had its own "is the community private and the user a guest?" expression, and any new endpoint had to remember to repeat the pattern. The fastest way to ship a leak was to forget the check.
+
+`Jetonomy\Visibility` consolidates that into one read of `jetonomy_settings.guest_read`. The front-end template loader and every public-read REST endpoint route through the same helper, so they answer the same question with the same logic. New endpoints opt into the gate with a single line.
+
+The helper deliberately does **not** look at per-resource visibility (private spaces, blocked users, restricted posts). Those remain the responsibility of individual controllers - `Visibility` only answers the global "can this caller see ANY community content right now?" question.
+
+---
+
+## API Reference
+
+### `Visibility::can_view_community()`
+
+Returns `true` if the current request should be allowed to see community content, `false` otherwise. In public mode this is always `true`. In private mode it requires the caller to be authenticated.
+
+**Returns:** `bool`
+
+**Example - gating a custom template fragment:**
+
+```php
+add_action( 'jetonomy_sidebar_before', function () {
+    if ( ! \Jetonomy\Visibility::can_view_community() ) {
+        return;
+    }
+    echo do_shortcode( '[my_member_only_widget]' );
+} );
+```
+
+The check is global, not per-resource - you do not need to pass a user ID or a post ID. Per-resource visibility (private spaces, restricted access rules) is enforced separately inside the relevant controllers.
+
+---
+
+### `Visibility::get_mode()`
+
+Returns the active visibility mode as a string. Useful when you want to render a different UI in private mode (e.g. a "Members only" badge in the site header) without duplicating the option read.
+
+**Returns:** `string` - `'public'` or `'private'`
+
+**Example - tagging the body class:**
+
+```php
+add_filter( 'body_class', function ( array $classes ): array {
+    $classes[] = 'jt-mode-' . \Jetonomy\Visibility::get_mode();
+    return $classes;
+} );
+```
+
+The function defaults to `'public'` on a fresh install - an unset, null, or `true` value of `guest_read` all resolve to public. Only an explicit `false` flips the community to private.
+
+---
+
+### `Visibility::rest_check()`
+
+Designed to be used as a REST `permission_callback`. Returns `true` when the caller may proceed, or a 401 `WP_Error` with code `community_private` when the community is in private mode and the caller is not logged in.
+
+**Returns:** `true|\WP_Error`
+
+**Example - protecting your own REST route:**
+
+```php
+register_rest_route( 'my-plugin/v1', '/community-events', [
+    'methods'             => 'GET',
+    'callback'            => 'my_plugin_list_events',
+    'permission_callback' => [ '\Jetonomy\Visibility', 'rest_check' ],
+] );
+```
+
+**Example - chaining with an existing capability check:**
+
+```php
+'permission_callback' => static function ( $request ) {
+    $vis = \Jetonomy\Visibility::rest_check( $request );
+    if ( is_wp_error( $vis ) ) {
+        return $vis;
+    }
+    return current_user_can( 'read' );
+},
+```
+
+Anonymous calls in private mode return:
+
+```json
+{
+    "code": "community_private",
+    "message": "This community is private. Please log in to view content.",
+    "data": { "status": 401 }
+}
+```
+
+Authenticated calls fall through to your route's own permission logic.
+
+> **Note:** `/auth/*` and `/admin/*` endpoints intentionally do not route through this helper. Locking `/auth/*` would lock users out forever, and admin endpoints have their own capability gates. Apply `Visibility::rest_check` to public-read endpoints only.
+
+---
+
+## The Access Matrix Runner
+
+`bin/access-matrix-check.sh` is the regression safety net that proves the helper actually works. It walks a representative subset of every Jetonomy REST route as every role, makes the real HTTP call, and asserts the response code matches the documented expectation.
+
+### What it covers
+
+- **78 checks** across the public REST surface
+- **6 roles** - anonymous, subscriber, author, editor (space-admin), moderator, administrator
+- **Both modes** - the runner can flip `jetonomy_settings.guest_read` to private for the duration of the run and restore it on exit (even if a check fails midway)
+
+In public mode the runner asserts that anonymous reads return `200`. In private mode it asserts the same anonymous reads return `401` from the central `Visibility::rest_check` gate. Logged-in calls are mode-independent and stay unchanged in either mode.
+
+### Running it locally
+
+```bash
+# From the plugin root:
+bin/access-matrix-check.sh                # public mode (default)
+bin/access-matrix-check.sh --mode=private # private community gate
+bin/access-matrix-check.sh --quiet        # only show failures
+```
+
+Sample output:
+
+```
+PASS  GET   /spaces             [anon]       expected=200  got=200
+PASS  GET   /spaces             [subscriber] expected=200  got=200
+PASS  POST  /posts/123/vote     [anon]       expected=401  got=401
+FAIL  GET   /posts/recent       [anon]       expected=401  got=200  <- regression
+
+Summary: 77 passed, 1 failed (78 total)
+```
+
+A regression is any row where the actual response code does not match the documented expectation. Exit code is `0` on a clean run, `1` if any row fails.
+
+### Release gating
+
+`bin/build-release.sh` invokes the access matrix runner before producing the release zip. If any row regresses, the build aborts and no zip is produced - the gate exists so we never ship a release that quietly opens up a previously-locked endpoint or quietly locks a previously-open one.
+
+Run the matrix locally before every commit that touches `permission_callback` wiring, the `Visibility` helper, or REST route registration.
+
+---
+
+## What's Next?
+
+- [Hooks Reference](./02-hooks-reference.md) - All `jetonomy_*` actions and filters
+- [REST API Reference](./01-rest-api.md) - Full endpoint listing with permission contracts
+- [Modal Toolkit](./09-modal-toolkit.md) - Front-end `jetonomyConfirm` / `jetonomyAlert` / `jetonomyPrompt` API