dev->main

docs/.vitepress/sidebar.ts

@@ -43,6 +43,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [
               { text: 'Curated Scripts', link: '/features/apps/install-scripts/curated/' },
               { text: 'Contributing', link: '/features/apps/install-scripts/contributing' },
               { text: 'Schema Reference', link: '/features/apps/install-scripts/reference/schema' },
+              { text: 'Hooks Reference', link: '/features/apps/install-scripts/reference/hooks' },
               { text: 'Macros Reference', link: '/features/apps/install-scripts/reference/macros' },
               { text: 'Debugging', link: '/features/apps/install-scripts/advanced/debugging' },
             ]
@@ -129,6 +130,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [
     collapsed: true,
     items: [
       { text: 'All Posts', link: '/blog/' },
+      { text: 'App Preconfiguration', link: '/blog/2026-06-18' },
       { text: '1.0 Local Rollout Complete', link: '/blog/2026-04-21' },
       { text: 'HexOS 1.0 Has Arrived', link: '/blog/2026-04-02' },
       { text: 'Apps Overhaul', link: '/blog/2025-12-26' },

docs/blog/2026-06-18.md

@@ -0,0 +1,72 @@
+# Stop Configuring. Start Using. HexOS Now Preconfigures Your Apps For You.
+**June 18, 2026**
+
+*By Jon Panozzo*
+
+Maybe you've heard about home servers. Maybe a friend won't stop talking about how they cut their streaming subscriptions and built their own private media library. Maybe you watched a YouTube video that made it look incredible — your movies, your music, your photos, all in one place, accessible from anywhere, completely under your control.
+
+And then you tried to actually set one up. And it wasn't like the video made it look.
+
+That gap — between how exciting the idea sounds and how overwhelming the reality feels — is exactly what HexOS was built to close. This week, we're taking one of our biggest steps yet toward that goal. We got to demo it live during the **June 12th LinusTechTips WAN Show**. If you missed it, keep reading.
+
+## First, Some Honest Talk About Home Servers
+
+Here's something the enthusiast community doesn't always say out loud: setting up a home server is hard. Not impossible, but genuinely, surprisingly hard — especially when you're doing it for the first time.
+
+Installing the hardware or the operating system is just the beginning. Every application you want to run has its own setup process. And unlike installing an app on your phone, home server apps don't just work out of the box. They expect you to know things. Things like what Docker is. What an environment variable is. What a port mapping is. What a file path looks like and why it matters.
+
+If none of those terms mean anything to you, that's completely normal. Most people getting into home servers for the first time feel exactly the same way. And that's a problem, because none of those things are what you actually wanted when you decided to build a home server. You wanted the apps. You wanted the experience. You wanted the control and the privacy that comes with owning your own setup.
+
+The technical concepts are just obstacles standing between you and that.
+
+## Introducing Application Preconfiguration
+
+Today, HexOS is introducing **Application Preconfiguration**: a feature that automatically handles the post-install setup of select apps on your behalf, so that when you open an app for the first time, it's already configured and ready to use.
+
+Not every app supports this yet. We're rolling it out starting with the apps where setup friction is highest and the payoff for eliminating it is greatest. The first three are **Plex**, **Jellyfin**, and **Emby**, three of the most popular media servers in the home server community. More apps will follow. But to understand why this matters, it helps to understand what setting up one of these apps normally involves.
+
+## What Installing a Media Server Actually Feels Like
+
+Let's say you've decided to try Plex. You've heard great things. You install it on HexOS, you click launch, and now Plex is staring at you, waiting.
+
+The first thing it wants you to do is sign in to a Plex account to "claim" your server. Okay, you make an account, you sign in, and you're sent back to a dashboard. Now Plex wants you to name your server. Fine. But then it asks you to create your media libraries, and this is where things start to get confusing.
+
+A "library" in Plex is essentially a folder on your system that Plex monitors for content. You need one for Movies, one for TV Shows, one for Music, one for Photos. For each library, Plex needs you to point it to the exact folder path on your system where that content lives. But if you're new to this, you're now asking yourself questions you didn't expect to be asking: *Do these folders exist yet? Where are they supposed to be? Am I supposed to have created them already? What does this path even mean?*
+
+So you open a second browser tab to look it up. The first guide you find is from 2021 and references a version of Plex that looks nothing like what's on your screen. You try another. That one assumes you already know what a mount point is. You're now three tabs deep, reading forum posts, trying to figure out a prerequisite to a prerequisite, and you haven't even gotten the app working yet.
+
+This is what cognitive overload feels like in practice. It's not one hard thing. It's a cascade of unfamiliar concepts, each one blocking the next, each one pulling your attention further from the reason you started. And for a lot of people, this is the moment they close the laptop and decide home servers just aren't for them.
+
+That's the moment we're trying to eliminate.
+
+## How Preconfiguration Works
+
+Rather than walk through it in text, here's a short video that shows exactly what the experience looks like:
+
+<video controls playsinline style="width:100%; border-radius:8px;">
+  <source src="/videos/hexos-apps-preconfig.mp4" type="video/mp4">
+</video>
+
+## Why We Started With Plex (And Then Kept Going)
+
+Plex was the natural starting point for preconfiguration. It's one of the most requested apps in the HexOS community, and its setup process is a textbook example of the friction we're trying to eliminate.
+
+But when Plex announced plans to significantly raise their lifetime license pricing ahead of July, we moved fast. We didn't want our users to feel like they only had one option. So alongside Plex, we immediately prioritized preconfiguration support for **Jellyfin**, a fully open-source alternative that requires no Plex account at all, and **Emby**, giving you a real choice of media server, all with the same seamless setup experience.
+
+All three launch this Thursday.
+
+## This Is What HexOS Is For
+
+The appeal of a home server is real: more control over your data, more privacy, software that works for you instead of the other way around. But for too long, the cost of entry has been a steep and discouraging learning curve that has nothing to do with any of that.
+
+HexOS exists to change that equation. We handle the infrastructure, the complexity, the configuration — so you can focus on the part that actually matters: using your apps and experiencing what your home server can do.
+
+Application preconfiguration is that philosophy applied directly to the apps themselves. Not just making them easy to install, but making them genuinely ready to use the moment installation is done. No second browser tab. No forum posts. No wondering if you did it right.
+
+Just open the app and go.
+
+This is the first of many apps we'll be bringing this experience to. Anywhere we see an opportunity to take something off your plate and get you to that *"wait, this is actually incredible"* moment faster, we're going to take it.
+
+Because that moment is worth it. You just shouldn't have to fight for it.
+
+**Application preconfiguration for Plex, Jellyfin, and Emby is available now.** If you've been curious about home servers but intimidated by where to start, this is exactly the kind of thing HexOS was built for.

docs/blog/index.md

@@ -4,6 +4,7 @@ Stay up to date with the latest news and updates from the HexOS team.
 
 ## 2026
 
+- [HexOS Now Preconfigures Your Apps For You - June 18, 2026](/blog/2026-06-18)
 - [HexOS 1.0 Local Rollout Complete - April 21, 2026](/blog/2026-04-21)
 - [HexOS 1.0 Has Arrived - April 2, 2026](/blog/2026-04-02)
 

docs/features/apps/install-scripts/advanced/debugging.md

@@ -1,17 +1,35 @@
 ## Debugging Workflow : Troubleshooting Failed Installations
 
-If an install scripts fails, this will help:
+If an install script fails, this will help:
 
 ### 1. Check HexOS Task Failure
 1. In the HexOS UI, check your notifications for an app install failure
 2. Click the notification to view the error message
 
-### 2. Check TrueNAS Job Failure
+### 2. Check Hook Failures (V5 Scripts)
+
+If your install script uses lifecycle hooks, hook tasks appear as children of the main install task in the HexOS activity center:
+
+1. Open the **Activity Center** (bell icon) in the HexOS UI
+2. Expand the install task to see individual hook steps
+3. Each hook shows its checkpoints and current status
+4. If a hook failed:
+   - Click **View Details** to see structured error context (endpoint, status code, etc.)
+   - Click **Retry** to re-run the hook from the failed checkpoint
+   - Click **Skip** to skip the hook and continue (if allowed)
+
+**Common hook failure causes:**
+- **App not ready** — the container hasn't finished starting. Increase the hook's `timeout` or add a longer delay in `waitForApp()`
+- **Network unreachable** — the hook can't reach the app's HTTP endpoint. Check that the port is correct and the app binds to `0.0.0.0`
+- **OAuth timeout** — the user didn't complete the OAuth flow within the time limit. Retry the hook to get a fresh OAuth prompt
+- **Missing input** — a required hook input wasn't provided. Check your `inputs` declarations
+
+### 3. Check TrueNAS Job Failure
 1. Navigate to the TrueNAS web interface (e.g., `https://10.0.1.13`)
 2. Go to **Jobs** section to view the installation job details
 3. Look for error messages in the detailed job output
 
-### 3. Check Application Logs (if app installed but won't start)
+### 4. Check Application Logs (if app installed but won't start)
 **Option A: TrueNAS Apps UI (if container is running)**
 1. Navigate to `https://10.0.1.13/ui/apps/installed`
 2. Click on the app, under `Workloads > Containers`, click the "View Logs" button
@@ -23,7 +41,7 @@ If an install scripts fails, this will help:
 3. Copy the container ID
 4. Run `sudo docker logs <container_id>` to view detailed logs
 
-### 3. Common Issues and Solutions
+### 5. Common Issues and Solutions
 
 #### Permission Errors
 - **Symptom**: App fails to start, logs show permission denied errors
@@ -38,5 +56,12 @@ If an install scripts fails, this will help:
 - **Symptom**: TrueNAS job fails with validation errors
 - **Solution**: Compare your `app_values` structure with the official TrueNAS app schema
 
+#### Hook Script Errors
+- **Symptom**: Hook task shows `AWAITING_RETRY` with an error message
+- **Solution**: Check the error context details for the specific failure. Common fixes:
+  - Ensure the `entrypoint` function name matches what's exported in your script
+  - Verify the app's API endpoint path is correct
+  - Confirm all `await` keywords are present on async calls
+
 ### Future Improvements
 The current debugging workflow requires accessing the TrueNAS interface directly, in the future we plan to expose more of this debugging workflow within HexOS's UI.

docs/features/apps/install-scripts/contributing.md

@@ -1,10 +1,77 @@
-# Contributing a new app
+# Contributing a New App
 
-Want to add your app curation to the official HexOS catalog? Follow these steps to contribute your install script, or share it in our forums first to get community feedback:
+Want to add your app curation to the official HexOS catalog? Install scripts now live in the [hexos-app-catalog](https://github.com/eshtek/hexos-app-catalog) repository — this is the single source of truth for all curated and community install scripts.
 
-1. Test your custom curation in HexOS and verify it works reliably
-2. Click [Here](https://github.com/eshtek/hexos-docs/new/main/docs/public/install-scripts) to start the contribution process
-3. Click the green "Fork this repository" button
-4. Paste the contents of your install script into the editor and press the green "Commit Changes"
-5. Click the green "Create pull request" on the following page
-6. In your PR description, include any special requirements (unique mounts, GPU usage, special environment variables, etc.)
+## Contribution Steps
+
+1. **Test your install script** in HexOS using Custom Install (Expert Mode) and verify it works reliably
+2. **Fork** the [hexos-app-catalog](https://github.com/eshtek/hexos-app-catalog) repository
+3. **Add your install script** as a JSON file named after the TrueNAS app (e.g., `myapp.json`)
+4. **If your script includes hooks** (V5), add the hook `.ts` files in a subdirectory (e.g., `myapp/myapp_hook.ts`) — or use inline `scriptContent` for simpler hooks
+5. **Submit a Pull Request** with a description of:
+   - What the app does
+   - Any special requirements (unique mounts, GPU usage, special environment variables)
+   - What the hooks do (if V5)
+
+## Repository Structure
+
+```
+hexos-app-catalog/
+├── _lib/
+│   └── hook_context.ts        # HookContext type stubs (import for autocompletion)
+├── myapp.json                 # Your install script (V4 or V5)
+├── myapp/                     # Hook scripts directory (V5 only, optional)
+│   └── myapp_hook.ts          # Hook implementation
+├── plex.json                  # Example: first-party V5 with hooks
+├── plex/
+│   └── plex_hook.ts
+├── jellyfin.json              # Example: V4 script (no hooks)
+└── ...
+```
+
+## Script Format
+
+- **V4**: Standard install scripts without hooks. Set `"version": 4`.
+- **V5**: Install scripts with lifecycle hooks. Set `"version": 5` and add a `hooks` array. See the [Hooks Reference](/features/apps/install-scripts/reference/hooks) for details.
+
+Both formats are fully supported. Use V5 only if your app benefits from post-install automation.
+
+## Using Inline Hooks (`scriptContent`)
+
+Community contributors who don't need separate `.ts` files can embed hook code directly in the JSON using the `scriptContent` field. This keeps everything in a single file:
+
+```json
+{
+  "version": 5,
+  "custom": true,
+  "metadata": { "name": "My App", "description": "...", "icon": "...", "version": "1.0.0" },
+  "hooks": [
+    {
+      "id": "health-check",
+      "event": "onAfterInstall",
+      "scriptContent": "export async function setup(ctx) {\n  await ctx.waitForApp('/health');\n  await ctx.emitCheckpoint('ready');\n}",
+      "entrypoint": "setup",
+      "timeout": 60,
+      "description": "Post-install health check",
+      "optional": true
+    }
+  ]
+}
+```
+
+::: tip Testing with Custom Install
+You can test inline hook scripts using **Custom Install in Expert Mode** — paste your V5 JSON with `scriptContent` hooks directly into the editor and run it. This is useful for development and testing before submitting a PR. Inline scripts should not be part of a PR submission for testing purposes only — submit them when they're ready for production use.
+:::
+
+## Best Practices
+
+- Use the [Schema Reference](/features/apps/install-scripts/reference/schema) and [Macros Reference](/features/apps/install-scripts/reference/macros) to understand all available fields and template variables
+- Browse existing scripts in the [hexos-app-catalog](https://github.com/eshtek/hexos-app-catalog) for real-world examples
+- Test thoroughly before submitting — both fresh installs and upgrades
+- Keep hooks focused and use `optional: true` for non-critical automation
+- Use `$LOCATION()` macros instead of hardcoded paths
+- Declare `owner` on directories that need specific permissions
+
+## Sharing Before Contributing
+
+Not ready for a PR? Share your install script JSON in the [HexOS Community Forums](https://forums.hexos.com) to get feedback from other users first.