diff --git a/docs/features/app-store.mdx b/docs/features/app-store.mdx
index d128bd31..f43f72bb 100644
--- a/docs/features/app-store.mdx
+++ b/docs/features/app-store.mdx
@@ -1,107 +1,155 @@
---
title: App Store
-description: Browse and deploy pre-configured application templates in one click.
+description: Browse a curated catalogue of Docker Compose templates and deploy any of them as a new stack with one click.
---
-The **App Store** tab lets you browse a curated catalogue of Docker Compose templates and deploy any of them as a new stack with environment-specific configuration, no YAML required.
+The **App Store** is a browseable catalogue of Docker Compose templates. Each template is a turn-key recipe with sensible defaults for ports, volumes, and environment variables, so you can stand up a new stack without writing YAML. Pick a tile, fill in a name, click **Deploy** and Sencho creates the directory, generates `compose.yaml` and `.env`, runs `docker compose up -d`, and switches you to the editor for the new stack.
- 
+
## Browsing templates
-Templates are loaded from a remote registry (configurable in **Settings > App Store**). The default registry is LinuxServer.io. A live count of available apps is shown in the top right of the view.
+Templates load from a remote registry. The default registry is **LinuxServer.io**; you can point Sencho at any [Portainer v2 compatible JSON catalogue](#custom-template-registry) instead.
-**Search:** Type in the search bar to filter templates by name, description, or category in real-time.
+### Search and counts
-**Category sidebar:** The left rail lists every category with its count. Click a category to narrow the grid. The active category is highlighted with a cyan rail and tinted background.
+The search bar at the top filters tiles by name, description, or category in real time. The chip on the right shows the number of templates currently visible (for example, `201 apps`).
-**Featured hero:** A featured template is pinned at the top of the grid with its logo, title, description, and a primary **Deploy** button. The hero disappears while you have an active search query.
+### Categories rail
+
+The left rail lists every category the registry exposes, plus an **All** entry, with a count for each. The active category gets a brand-coloured rail and tinted background. The rail appears once at least one template has loaded.
+
+### Featured template
+
+A single template is pinned to the top of the grid in a wide editorial banner. Sencho rotates the featured pick **weekly** through the five most-starred templates in the registry, so the catalogue stays fresh without you doing anything. The banner disappears whenever you have a search query active.
+
+### Tiles
Each tile shows:
-- A brand-tinted logo square (falls back to the first letter of the template name)
-- Name and first-sentence pitch
-- GitHub star count and primary category
-- A **security scan badge** on the right: `CLEAN` (no CVEs detected), `{n} CVE(s)` (amber, open vulnerabilities), or `UNSCANNED` (no scan recorded yet)
+
+- A brand-tinted logo (falls back to a generic icon when the registry has no artwork)
+- The template name and the first sentence of its description
+- A GitHub star count (when the registry provides one)
+- The primary category
+- A **scan badge** on the right, derived from Sencho's vulnerability scanner:
+ - **Clean** (no CVEs detected on the most recent scan)
+ - **{N} CVE** or **{N} CVEs** (the count of open vulnerabilities, in amber)
+ - **Unscanned** (no scan has been recorded for this image yet)
+
+Tiles are sorted by GitHub star count, descending. Click any tile to open the deployment sheet on the right.
## Deploying a template
-Click any tile to open the **deployment sheet** on the right side of the screen. The sheet splits configuration into two tabs: **Essentials** for a fast one-click deploy and **Advanced** for full control over ports, volumes, and environment.
+The deployment sheet slides in from the right. The header carries a breadcrumb (`App store › `), the template name in the cockpit display face, and a meta line that combines the supported architectures, the GitHub star count, and the target node name when you are deploying to a remote node.
-
- 
-
+### About
-The sheet header displays the app logo, title, and a truncated description with a **Read more** / **Read less** toggle. Below the description you may see:
-
-- **Architecture badges** (e.g. `amd64`, `arm64`) when the template declares supported platforms
-- **GitHub stars** count
-- **Source** link to the GitHub repository
-- **Docs** link to the official documentation
-
-When deploying to a remote node, a badge at the top of the sheet shows the target node name.
+The first section is a description block with the template logo, the full description, a **Read more** / **Read less** toggle, and a row of secondary metadata: architecture chips (for example `amd64`, `arm64`), GitHub stars, a **Source** link to the template's repository, and a **Docs** link to the project's official documentation when the registry provides one.
### Essentials tab
-The **Essentials** tab has a single field (the stack name) plus a hint that the template's recommended ports, volumes, and environment variables will be used as-is. Click **Deploy {template}** to ship it in one click. For anything more nuanced, switch to **Advanced**.
+The **Essentials** tab is intentionally minimal: a single **Stack Name** field and a hint that the template's defaults will be used as-is. Click **Deploy {template}** to ship it.
-### Stack name
+
+
+
-Pre-filled with the template name in lowercase. You can change it; the same [naming rules](/features/stack-management#creating-a-stack) apply (lowercase, hyphens, no spaces).
+The stack name pre-fills with the template slug (lowercased, hyphens, no spaces). You can change it; the same [naming rules](/features/stack-management#creating-a-stack) apply.
+
+For anything beyond the defaults, switch to **Advanced**.
### Advanced tab
-The **Advanced** tab exposes every knob the template declares: port mappings, volumes, environment variables, custom key/value pairs, and the post-deploy vulnerability scan toggle. Fields on this tab are pre-populated with the template's defaults, so customizing is additive rather than required.
-
-### Ports
-
-For each exposed port, the sheet shows an editable **host port** field (left side) and the fixed **container port** (right side). Edit the host port to avoid conflicts with other services on the same machine. Ports must be in the valid range (1 to 65535); invalid values are highlighted and block deployment.
-
-If a host port is already in use by a running container, a pulsating warning dot appears next to the port. Hover over the dot to see which application is using the port. If the application is managed by Sencho, the stack name is shown; otherwise the indicator reads "used by an external app".
+The **Advanced** tab exposes every knob the template declares. Every field is pre-populated with the template's recommended value, so customisation is additive rather than required.
- 
+ 
-### Volumes
+#### Ports
-For each container mount point, enter the **host path** where that data should be stored. Suggested defaults (e.g. `./config`, `./data`) are pre-filled.
+Each declared port shows an editable **host port** on the left and the fixed **container port** on the right. Host ports must be integers between 1 and 65535; invalid values are highlighted and block deployment.
+
+When the host port you typed is already in use somewhere on the active node, a pulsing amber dot appears next to the container port. Hover the dot for a tooltip that names the offending stack (`Port {N} used by {stack}`) when Sencho manages it, or `Port {N} used by an external app` when the binding belongs to a process outside Sencho.
+
+
+
+
+
+#### Volumes
+
+For each container mount point the template declares, type the **host path** where that data should live. Sencho pre-fills sensible defaults like `./config` or `./data`.
- Relative paths like `./config` are resolved relative to the stack directory inside your `COMPOSE_DIR`. Absolute paths map directly to the host filesystem.
+ Relative paths such as `./config` resolve against the new stack's directory inside `COMPOSE_DIR`. Absolute paths map directly onto the host filesystem.
-### Environment variables
+#### Environment variables
-Each template declares the variables it needs. Sencho pre-fills sensible defaults where available (e.g. `PUID=1000`, `PGID=1000`, `TZ` from your browser locale). Edit any value before deploying.
+Each template declares the variables it expects. Sencho pre-fills sensible defaults where it can, and adds three baseline LinuxServer.io conventions automatically when the template does not already define them: **PUID** (`1000`), **PGID** (`1000`), and **TZ**, seeded from your browser's reported timezone.
-### Custom variables
+#### Custom variables
-Below the template variables, an **Add Custom Variable** section lets you define arbitrary key-value pairs not declared by the template. Type a key and value, then click **+** to add it. If you add a key that already exists in the template defaults, a warning will let you know your custom value will override the default.
+The **Custom variables** block lets you add arbitrary key/value pairs that the template did not declare. Type a key and value, then click **+** to add it. If you add a key that already exists in the template defaults, a toast warns you that your custom value will override the default (`"{KEY}" already exists in template defaults. The custom value will override it.`).
-### What happens on Deploy
+#### Security
-1. Sencho creates a new stack directory in `COMPOSE_DIR`
-2. Writes the generated `compose.yaml` (and `.env` file if environment variables are configured)
-3. Runs `docker compose up -d`
-4. On success: switches you to the Editor view for that stack
-5. On failure: rolls back by running `docker compose down` and deleting the stack directory
+When [vulnerability scanning](/features/vulnerability-scanning) is configured on the active node, a **Security** section appears at the bottom of the Advanced tab with a single checkbox: **Scan images for vulnerabilities after deploy**. The checkbox is on by default. Leave it on to queue a Trivy scan against every image the new stack pulls. The scan runs in the background once the stack is up; results land on the per-image severity badges in the [Resources Hub](/features/resources) and open the [scan results drawer](/features/vulnerability-scanning#the-scan-results-drawer) when clicked.
-A toast notification confirms success or shows the error message. Large images may take a few minutes to pull.
+The Security section is hidden entirely when Trivy is not available on the node.
-If a previous stack with the same name was removed outside of Sencho (for example, through the Docker CLI or Docker Desktop), the leftover directory is cleaned up automatically and the deploy proceeds as normal.
+## What happens on Deploy
+
+Clicking **Deploy** runs the following sequence:
+
+1. **Pre-flight name check.** Sencho asks the active node whether a stack of that name already exists. If it does, you get an immediate error toast and nothing else happens.
+2. **Directory creation.** A new directory is created under `COMPOSE_DIR/` on the active node.
+3. **File generation.** Sencho writes `compose.yaml` (rendered from the template, with your port and volume overrides) and a `.env` file (when you configured environment variables).
+4. **Policy gate.** Any [deploy-enforcement policies](/features/deploy-enforcement) configured on the node run against the generated compose. If a rule blocks the deploy, the directory is cleaned up and you get the rule's reason.
+5. **`docker compose up -d`.** On Skipper and Admiral the deploy is **atomic**: any container that fails to start triggers an automatic rollback to the previous state. On Community the deploy is non-atomic.
+6. **Outcome.**
+ - On success, you are switched to the editor for the new stack and a success toast confirms the deploy.
+ - On failure, Sencho parses the error. Most failures (image pull, port collision, volume permission, compose validation) trigger a clean rollback: the stack is brought down and the directory is removed. A small set of failures that point to live containers (for example, a startup that crashes after the container is running) leave the stack on disk so you can inspect it. The error toast tells you which.
+
+## Watching the deploy
+
+Sencho can stream the live `docker compose` output for every template install. Open **Settings › Appearance › Display** and enable **Deploy progress modal**; from then on, every App Store deploy opens a structured log modal you can minimise to a pill that follows you across navigation. See [Deploy Progress Modal](/features/deploy-progress) for the full reference.
- Deploying a template requires the `stack:create` permission. Users without this permission will see the Deploy button disabled.
+ Deploying a template requires **admin access** on the target node. The Deploy button stays disabled when your account does not have it.
## Custom template registry
-By default Sencho uses the LinuxServer.io template registry. To use your own:
+By default Sencho uses LinuxServer.io's hosted catalogue. To point at your own:
-1. Open **Settings > App Store**
-2. Enter your registry URL (must serve a JSON array of template objects in Portainer v2 format)
-3. Click **Save & Refresh**
+
+ 
+
-Sencho saves the new URL and automatically refreshes the template cache from the new source. To revert to the default registry, click **Reset to Default**.
+1. Open **Settings › Advanced › App Store**.
+2. Type your catalogue URL into **Registry URL**. The URL must start with `http://` or `https://` and serve a JSON array of template objects in the [Portainer v2 template format](https://documentation.portainer.io/v2.0-be/api/templates/).
+3. Click **Save & refresh**. Sencho persists the new URL and immediately invalidates the template cache so the App Store reloads from the new source.
+
+A small chip under the input reads **using custom registry** when an override is set and **using default** when the field is empty. Click **Reset to default** to clear the override and fall back to LinuxServer.io.
+
+The default registry display at the top of the page is informational only; you cannot remove the LinuxServer.io fallback, and Sencho uses it whenever the custom field is empty.
+
+## Troubleshooting
+
+
+
+ Sencho fetches templates from the configured registry on demand. If the grid stays empty and the loading spinner is gone, the registry returned an empty list or the request failed before parsing. Open **Settings › Advanced › App Store** and confirm the **Registry URL** is reachable from the node (try the URL in a browser tab); a custom catalogue served from a private host will not load if the Sencho container cannot resolve or reach it. Click **Save & refresh** to invalidate the cache and try again. If you switched to a custom registry by mistake, click **Reset to default**.
+
+
+ The conflict indicator is computed against a snapshot of the node's bound ports taken when you opened the deployment sheet. If you freed the port from another stack while the sheet was open, the dot does not refresh on its own. Close the sheet and reopen it to recompute, or pick a different host port. Tooltip text that reads `used by an external app` means a process outside Sencho holds the binding (often the host's reverse proxy or a system service); changing the host port is usually faster than tracking down the offender.
+
+
+ Sencho rolls back the directory only when the failure points cleanly at template generation, image pull, or first-time container creation. Failures that involve a container that did manage to start (for example, a crashloop after Compose returned success, or a healthcheck that flapped) leave the stack on disk so you can read the logs and decide whether to fix forward. The error toast tells you which path was taken; the response also carries a `rolledBack` flag and a `ruleId` you can search for in the [audit log](/features/audit-log). Use the editor to repair the compose, or delete the stack from the cockpit if you want to retry from scratch.
+
+
+ The **Scan images for vulnerabilities after deploy** checkbox renders only when the active node reports that Trivy is installed. Configure scanning per the [Vulnerability Scanning](/features/vulnerability-scanning) page, then reopen the deployment sheet. Even with the checkbox missing, the rest of the Advanced tab works exactly the same; you just lose the post-deploy scan trigger.
+
+
diff --git a/docs/images/app-store/app-store-hero.png b/docs/images/app-store/app-store-hero.png
index ef9563c5..bd2e7717 100644
Binary files a/docs/images/app-store/app-store-hero.png and b/docs/images/app-store/app-store-hero.png differ
diff --git a/docs/images/app-store/app-store-port-conflict.png b/docs/images/app-store/app-store-port-conflict.png
index 5459e824..929e16d7 100644
Binary files a/docs/images/app-store/app-store-port-conflict.png and b/docs/images/app-store/app-store-port-conflict.png differ
diff --git a/docs/images/app-store/app-store-settings-registry.png b/docs/images/app-store/app-store-settings-registry.png
new file mode 100644
index 00000000..b7d1d141
Binary files /dev/null and b/docs/images/app-store/app-store-settings-registry.png differ
diff --git a/docs/images/app-store/deploy-sheet-advanced.png b/docs/images/app-store/deploy-sheet-advanced.png
new file mode 100644
index 00000000..b7b91089
Binary files /dev/null and b/docs/images/app-store/deploy-sheet-advanced.png differ
diff --git a/docs/images/app-store/deploy-sheet-essentials.png b/docs/images/app-store/deploy-sheet-essentials.png
index 6c5ebda0..552554d3 100644
Binary files a/docs/images/app-store/deploy-sheet-essentials.png and b/docs/images/app-store/deploy-sheet-essentials.png differ