Portal AI Suite Pro 1.0.0

---

General

What is Portal AI Suite Pro?
Portal AI Suite Pro is a comprehensive portal addon for XenForo 2.3+. It replaces the default homepage with a modern community portal featuring articles, live statistics, polls, events, and over 20 configurable widgets. The built-in AI engine automatically routes new posts to the correct forum and can generate complete news articles from RSS feeds on demand.

Do I need an OpenAI API key?
No. The portal works fully without OpenAI. The API key is optional and unlocks additional features:

• AI-powered thread routing (instead of BM25 fallback)
• Automatic title generation in the AskBox
• AI News Generator (article creation from RSS feeds)
• DALL-E cover image generation
• AI enrichment of forum profiles (SEO)

Without an API key, the BM25 FULLTEXT routing is used, which also delivers good results.

How much does OpenAI usage cost?
Costs depend on the chosen model and usage. Approximate values:
Routing results are cached, so identical questions don't trigger additional API calls.

Is the addon compatible with other portal addons?
Yes. Portal AI Suite Pro can be installed alongside other addons. If you're migrating from EWR Porta 2 (XenPorta 2), there's a built-in importer that transfers all featured articles, images, and categories.

What XenForo version is required?
XenForo 2.3.9 or higher with PHP 8.1 or higher.

---

Installation & Setup

How do I install the addon?

1. Extract the ZIP file
2. Upload the folder upload/src/addons/DEB/DEBPortal to your server
3. In the ACP: Add-ons -> Install add-on -> select DEB/DEBPortal
4. Configure under ACP -> Portal AI Suite Pro -> Dashboard

How do I make the portal my homepage?
There are two ways:

• Recommended: In the ACP under Setup -> Options -> Basic board information -> Index page route, enter portal/.
• Alternative: In the portal options, enable Replace forum index with portal.

How do I set up the OpenAI API key?

1. Create an API key at platform.openai.com/api-keys
2. In the ACP: Portal AI Suite Pro -> Options -> Routing
3. Set routing method to OpenAI
4. Paste the API key and select a model
5. Verify with the OpenAI Connection Test in the dashboard

How do I set up the AI News Generator?

1. In the ACP: Portal AI Suite Pro -> AI News -> Sources
2. Create a new source: enter the feed URL, select category and target forum
3. Configure language, article tone, and word count
4. Optional: enable DALL-E image generation under Portal AI Suite Pro -> Options -> AI News
5. News is fetched automatically via cron job every 4 hours (configurable)
6. Alternatively: trigger manually via Fetch Now in the ACP

How do I migrate from EWR Porta 2 (XenPorta)?
In the ACP: Portal AI Suite Pro -> Dashboard -> Import from EWR Porta 2. A preview analysis will show the number of articles, images, and categories. After confirmation, the import runs as a background job. Alternatively via CLI:
php cmd.php deb-portal:import-porta
The import can safely be run multiple times -- already imported articles are skipped.

---

Routing & AskBox

How does automatic routing work?
When a new thread is created in the configured inbox forum, the routing engine analyzes the content in 3 stages:

1. Rule engine: Checks keyword and prefix rules (highest priority)
2. OpenAI: Semantic analysis via Chat Completions API (if enabled)
3. BM25 fallback: FULLTEXT scoring against forum profiles

Depending on the confidence level, the thread is automatically moved (>78%), sent for review (>60%), or placed in the manual queue (<60%).

What happens with ambiguous results?
When the routing result is ambiguous (e.g., multiple similar subforums for "Dreambox"), the AskBox displays a disambiguation dialog with up to 4 subforums for the user to choose from. For threads submitted via the inbox forum, they land in the review queue for moderators.

What are forum profiles and why do I need them?
Forum profiles are descriptions and keywords for each forum that the routing engine matches against. They are automatically generated from forum titles, descriptions, and thread titles. Optionally, OpenAI can enrich these profiles with SEO-optimized descriptions (120-155 characters) and 10-20 keywords. The better the profiles, the more accurate the routing.

Can I exclude certain forums from routing?
Yes. In the routing options, there are include and exclude lists where you can enter node IDs to be considered or ignored during routing.

What is the hallucination guard?
OpenAI can sometimes return invalid forum IDs. The hallucination guard validates every AI response, checks whether the node ID exists, corrects deviations within a +/-10 range, and falls back to the best BM25 candidate if necessary.

---

Widgets & Layout

How do I change the portal layout?
In the ACP: Portal AI Suite Pro -> Layout Builder. There you can add rows via drag-and-drop, adjust column widths, and place widgets in different positions. Changes are saved via AJAX.

Can I display XenForo native widgets in the portal?
Yes, via the XF Widget Bridge widget. In the widget manager, you can embed any XenForo core or third-party widget. Rendering is cached for optimal performance.

Can users customize the portal individually?
Yes. Every logged-in user can show/hide individual widgets and switch between card and list view for articles via the personalization button. Settings are stored per user and can be reset at any time.

What is lazy loading?
When lazy loading is enabled, only the basic page structure is loaded initially. Widgets are loaded asynchronously via AJAX. This significantly speeds up the initial load time, especially with many active widgets.

---

AI News Generator

How does the News Generator create articles?

1. The cron job fetches configured RSS feeds or web pages
2. New entries are checked for duplicates via content hash
3. OpenAI rewrites the source text into a unique, in-depth article
4. Optionally, DALL-E generates a matching cover image
5. The article is saved as a draft in the news queue
6. After approval, it's published as a forum thread and displayed as a featured article

Can I configure different sources individually?
Yes. Each source has its own settings for: AI model, language, article tone, word count (min/max), custom prompt, category, target forum, and fetch interval.

In which languages can articles be generated?
German, English, Spanish, French, Italian, Portuguese, Dutch, Polish, Turkish, and Russian.

What do the article tone settings mean?

How does DALL-E image generation work?
When enabled, DALL-E generates a matching cover image based on the article content. DALL-E 3 creates HD images in a natural style, DALL-E 2 is the cheaper alternative. Images are stored locally on the server (800x600 JPEG).

---

Performance & Caching

Which caching backend is recommended?
The addon automatically detects the available backend. You can also set it manually in the options.

How often is widget data refreshed?
The widget cache cron job runs every 10 minutes and pre-calculates stats, tags, ticker data, categories, and more. The TTL is configurable.

Can I clear the cache manually?
Yes. In the Portal AI Suite Pro Dashboard, there's a Clear Cache button that immediately flushes all portal and widget caches.

---

Troubleshooting

The portal shows no articles

• Check if the portal is enabled: Portal AI Suite Pro -> Options -> Enable portal
• Check if featured articles exist: Portal AI Suite Pro -> Dashboard -> Featured Articles
• Check permissions: the user group needs viewPortal
• Clear the cache via the dashboard button

OpenAI routing doesn't work

• Test the API key via Dashboard -> OpenAI Connection Test
• Make sure the routing method is set to OpenAI
• Check if enough forum profiles exist (dashboard shows coverage)
• Check the routing logs in the ACP

Widgets are not displayed

• Check if the widgets are enabled in the Widget Manager
• Check if they're assigned to a row/column in the Layout Builder
• Has the user possibly hidden them via personalization?
• Clear the cache and reload the page

The News Generator doesn't create articles

• Check if sources are created and active: Portal AI Suite Pro -> AI News -> Sources
• Use the Debug page for feed diagnostics per source
• Verify the OpenAI API key is valid
• Check the bot user in the news options (must be a valid account)
• Test the feed manually via the Test Feed button on the source

Icons are not displayed in the frontend
XenForo 2.3 uses an SVG sprite system instead of CSS FontAwesome. After installation, the icon sprites need to be regenerated:
php cmd.php xf-dev:generate-icon-sprites
The addon automatically registers all 38 required icons via the icon_usage_analyzer_extra listener.

---

Miscellaneous

Is there a help page for users?
Yes. The addon automatically creates a help page at /help/portal-features that explains the portal features to users.

Are updates supported?
Yes. Simply upload the new ZIP file and update in the ACP. All data and settings are preserved.

How can I customize the portal?

• Layout: Drag-and-drop layout builder in the ACP
• Design: Custom CSS directly in the portal options
• Content: Configure, enable, and disable widgets individually
• Page title: Custom portal title configurable
• Width: Maximum portal width freely adjustable

---