Registration & Onboarding

Creating Your Account

1. Open your CitadelQuest instance in a web browser
2. Click Register in the top navigation bar
3. Fill in:
   • Username — your unique identity on this Citadel
   • Email — for account recovery (stored only in your local database)
   • Password — choose a strong password
   • Auto-create also CQ AI Gateway account — keep checked for comfort zero-friction start
4. Click Register

The first user to register on a new CitadelQuest installation automatically receives Admin privileges.

Registration can be disabled by the Citadel admin — if you see a "Registration is currently disabled" message, contact Citadel's administrator.

Onboarding Wizard

After your first login, you'll be guided through a 3-step onboarding wizard to get you started:

Step 1: Connect to CQ AI Gateway

CQ AI Gateway provides access to top AI services (Claude, Gemini, Grok, and more) for powering your Spirits.

• Automatic setup: If you selected Auto-create also CQ AI Gateway account, your API key is created automatically during registration — you get free starting credits to begin immediately
• Manual setup: Enter your CQ AI Gateway API key if you have one
• Skip: You can skip this step and configure it later in Settings

Step 2: Create Your First Spirit

A Spirit is your personal AI companion. Give it:

• Name — choose any name you like
• Color — pick a color to visually identify your Spirit

A smart default AI model is selected automatically, so you can start chatting right away. You can always change the model later in the Spirit Profile.

Step 3: After Onboarding

Start Your Journey (Option A)

Click Start to open your first conversation with your new Spirit. From here, you can explore all of CitadelQuest's features together!

Explore Dashboard (Option B)

Click Dashboard to open your central hub for everything in CitadelQuest. See Dashboard for details.

Language Selection

CitadelQuest supports multiple languages. You can switch at any time using the language icon in the top navigation bar:

• English (EN)
• Czech (CZ)
• Slovak (SK)

Your language preference is saved and persists across sessions.

Dashboard

The Dashboard is your home screen — the central hub of your CitadelQuest experience. It appears when you log in or click the CitadelQuest logo in the navigation bar.

Quick Actions

Nine cards providing fast access to the main features:

If you have Admin privileges, a 9th card appears:

• Admin Panel — access the administration panel (/administration)

Tip: The CQ Explorer card shows a red badge when you have pending friend requests, a yellow badge when followed profiles have new content, and a feed badge when there are new posts in your CQ Feed timeline.

CQ AI Gateway

Below Quick Actions, you'll find the CQ AI Gateway panel showing:

• Credits balance — your current AI credits (color-coded: green = plenty, yellow = low, red = very low)
• CQ AI Gateway - Dashboard — opens the CQ AI Gateway web dashboard in a new tab (seamless login, no password needed)
• Add Credits — opens the credits purchase page directly

Storage Usage

The right sidebar shows your storage breakdown:

• Total Storage — combined size of all your data
• Database — your personal SQLite database size
• User Data — files stored in File Browser
• Backups — space used by your backup files

Server Info

At the bottom right, you'll see:

• Server hostname (your Citadel's domain)
• CitadelQuest version number
• CitadelQuest logo

Top Navigation Bar

The navigation bar is always visible and provides:

1. CitadelQuest Logo — click to return to Dashboard
2. Spirit Icon — click to open Spirits list Dropdown
   • icon - click to open Spirit Chat modal
   • name - link to Spirit's profile page
3. User Menu (your username):
   • CQ Explorer
   • CQ Profile
   • CQ Memory
   • File Browser
   • Settings
   • Admin (if admin)
   • Logout
4. CQ Chat — dropdown with recent conversations and unseen message count
5. Notifications — bell icon with unread notification count
6. Language — switch between English, Czech, and Slovak

CQ Memory — Knowledge Graphs

CQ Memory is CitadelQuest's powerful knowledge management system. It transforms unstructured content — documents, web pages, conversations — into interactive 3D knowledge graphs that your Spirits can use for persistent, contextual memory.

Key Concepts

Memory Pack (.cqmpack)

A standalone knowledge graph stored as a portable SQLite database file. Each pack contains:

• Nodes — individual pieces of knowledge (facts, insights, preferences, thoughts)
• Relationships — typed connections between nodes (relates to, contradicts, reinforces, etc.)
• Tags — flexible labels for filtering and search
• Source content — the original documents that knowledge was extracted from

Packs are fully self-contained and portable — they can be shared between users and Citadels.

Memory Library (.cqmlib)

A collection that groups multiple Memory Packs together. Libraries help you organize related knowledge:

• Enable/disable individual packs
• Set priorities for which packs are searched first
• Tag packs for easy categorization

Memory Node

A single unit of knowledge. Each node has:

• Content — the actual information
• Summary — short description shown on the graph
• Category — knowledge, fact, preference, thought, conversation, or internet
• Importance — how relevant this memory is (decays over time if not accessed)
• Source tracking — where this memory came from

Relationships

Connections between nodes, each with a type:

Memory Explorer

Route: /memory

The Memory Explorer is the main interface for viewing and managing your knowledge graphs.

Layout

• Left sidebar — Node list with search, source document sections, extract and analyze tools
• Center — Interactive 3D graph visualization
• Top bar — Library selector, Pack selector, info

3D Graph Visualization

The centerpiece of Memory Explorer — an interactive 3D force-directed graph rendered with Three.js:

• Nodes appear as colored spheres (color = category)
• Edges connect related nodes (color = relationship type)
• Click a node to see its details (content, category, importance, tags, source)
• Hover over a node to highlight its connections and show the node's title
• Scroll to zoom, drag to rotate, right-drag to pan
• Click+Ctrl zoom to node + set camera center of rotation
• Delete key press to show confirm window, delete node and its children
• Node size reflects importance

Library Selector

The dropdown at the top lets you switch between:

• All Packs — shows every .cqmpack file in your project
• Specific libraries — shows only packs in that library
• When viewing a Spirit's memory (/memory?spirit={id}), only that Spirit's library is shown

Pack Selector

Next to the library selector, choose which pack to visualize. Shows:

• Pack name
• Node count badge
• Relationship count badge
• Dropdown for Pack management (Add/Remove from Library, Show details with AI usage stats, Delete)

Creating a New Pack

1. Click the + button next to the pack selector
2. Enter a name for your new pack
3. The pack is created and automatically added to the selected library

Creating a New Library

1. Click the + button next to the library selector
2. Enter a name and optional description
3. The library is created at the default location

Memory Extraction

The Extract Panel lets you add knowledge from various sources into a pack.

Source Types

File

Upload or select a file from your File Browser. Supported: text documents, PDFs, code files, and more.

URL

Enter a web page URL. CitadelQuest fetches the content and extracts knowledge from it.

Text

Paste any text directly. Useful for quick notes, copied content, or manual input.

Conversation

Select a Spirit and one of its conversations. The conversation transcript is extracted into structured knowledge.

Extraction Process

1. Select your source type and provide the content
2. Click Start Extraction
3. Watch the 3D graph update in real-time as nodes are created:
   • Documents are processed recursively — the AI splits content into logical blocks, creating a hierarchical structure
4. After extraction completes, relationship analysis runs automatically, if selected in the extraction settings — the AI discovers connections between all nodes
5. The complete knowledge graph is stored in the selected pack (AI usage logged)

AI Credits: Extraction uses CQ AI Gateway credits. The Pack Details modal shows complete token usage and credit cost statistics.

Memory Analyze Panel

After extracting knowledge, you can run relationship analysis to discover connections between nodes.

Whole Pack Analysis

Analyzes all nodes in the selected Memory Pack to discover relationships across the entire knowledge graph.

Selected Root Node Analysis

Focused analysis on a specific branch (tree) of nodes — useful for analyzing relationships within a particular document or topic without re-analyzing the entire pack.

The analysis uses a hierarchical strategy that's optimized for efficiency — intra-document leaf pairs, then cross-document root-gating with recursive drill-down.

Active CQ Memory Jobs

A status icon in the global app footer shows when memory jobs (extraction or analysis) are actively running. This is visible from any page, so you always know when your knowledge graph is being processed.

Spirit Memory Integration

Each Spirit has its own Memory Library containing one or more packs. This is how Spirits remember things:

Memory Types

How Memory Recall Works

1. You send a message to your Spirit
2. The system searches all enabled packs in the Spirit's library
3. Relevant memory nodes are recalled based on keyword matching
4. For Memory Agent mode: a sub-agent AI evaluates and synthesizes the recalled memories
5. The recalled context is provided to your Spirit alongside your message
6. Your Spirit responds with awareness of past knowledge

Memory Synthesis Display

In Spirit Chat, recalled memories appear above the Spirit's response:

• Expandable panel showing which memories were used
• Mini 3D graph visualizing the recalled nodes and their connections
• Score badges showing relevance strength
• Tags for quick identification
• "Graph" badges for nodes discovered via relationship expansion

Sharing Memory Packs

You can share your Memory Packs with CQ Contacts or publicly via CQ Share:

1. In the Memory Explorer, select a pack and use the pack dropdown menu → Share
2. Or go to the CQ Share management page (/share) and create a share for any pack
3. Choose scope: Public (anyone with the link) or CQ Contacts (authenticated contacts only)

When a CQ Contact downloads your shared pack, it auto-syncs — any updates you make to the original pack are automatically reflected in their copy the next time they open their Memory Explorer.

See CQ Share for the full sharing guide.

Use Cases

• Book/Document Analysis — Upload PDFs or documents, extract key concepts, see information structure at a glance
• Research — Load multiple sources into one library, visualize contradictions and reinforcements across sources
• Spirit Knowledge — Build specialized knowledge bases for your Spirits
• Personal Wiki — Organize your knowledge into themed packs
• Web Research — Extract knowledge from URLs and see connections between different web sources
• Conversation Archives — Extract insights from your Spirit conversations into permanent knowledge
• Relationship Discovery — Run analysis to find contradictions, reinforcements, and connections across different knowledge sources
• Shared Knowledge — Share curated knowledge graphs with friends, team members, or the public via CQ Share

File Browser — Personal Cloud

The File Browser is your personal cloud storage within CitadelQuest. Your files are stored on your server, always accessible, and fully integrated with your AI Spirits.

Route: /file-browser

Interface

The File Browser offers two views, switchable via toggle buttons:

Tree View

A hierarchical tree showing your complete folder structure. Click folders to expand/collapse, click files to select them.

File Preview

• Size
• Last modified date
• Action buttons (download, rename, delete)
• content preview for images, pdf, md, txt

Operations

Uploading Files

1. Click the Upload button
2. Select or drag&drop files from your device
3. Files are uploaded to your current directory

Creating Folders

1. Click the New Folder button
2. Enter a name
3. The folder is created in your current directory

Creating Files

1. Click the New File button
2. Enter a filename
3. An empty file is created — you can edit it or let your Spirit fill it with content

Downloading

Click the download icon next to any file to download it to your device. download in ZIP for directories

Renaming

Click the rename icon, enter the new name, and confirm.

Deleting

Click the delete icon and confirm the deletion.

Sharing

Click the Share button on any file to create a CQ Share link. You can choose to share publicly (anyone with the link) or with CQ Contacts only. See CQ Share for details.

AI Integration

Your Spirits have full access to the File Browser through their tools:

• Read files — Spirit can read any file content to help you
• Create files — Spirit can create new files (notes, documents, code, etc.)
• Edit files — Spirit can make precise edits to existing files
• Manage files — Spirit can rename, move, or delete files
• Browse — Spirit can list directory contents to understand your file structure

This means you can ask your Spirit things like:

• "Create a shopping list in my notes folder"
• "Read the document I uploaded and summarize it"
• "Update the recipe file with the new ingredients"
• "Organize my files into folders by topic"

Mobile Support

The File Browser is fully responsive and optimized for mobile devices:

• Touch-friendly interface
• Icon-based mobile navigation
• Responsive layout adapting to screen size

Storage

Your files are stored in your personal data directory on the server. The Dashboard shows your current storage usage breakdown (Database, User Data, Backups).

Files are stored per-user — other users on the same Citadel cannot access your files.

CQ Chat — Private Messaging

CQ Chat enables private, encrypted messaging between users across different CitadelQuest instances. Communication is direct — messages travel straight from one Citadel to another, with no corporate servers in between.

Route: /cq-chat

Accessing CQ Chat

There are two ways to access your conversations:

Navigation Dropdown

Click the chat icon in the top navigation bar to see:

• Recent conversations with preview of last message
• Unseen message count badge (green number)
• New Chat button to start a conversation
• Click any conversation to open it

Full Chat Page

Navigate to /cq-chat for the complete chat interface with:

• Conversation list on the left
• Active conversation on the right
• Full message history with timestamps

Conversations

Starting a Conversation

1. Click the New Chat button (message+ icon)
2. Select a contact from your CQ Contacts
3. Start typing!

Group Chats

CQ Chat supports group conversations with multiple participants from different Citadels.

Message Features

• Text messages with real-time delivery
• Image attachments
• Timestamps showing when messages were sent
• Read indicators for message status
• Unseen count — badge shows how many unread messages you have

How It Works

CQ Chat uses CitadelQuest's Federation protocol for cross-instance communication:

• Messages are sent directly between Citadels over HTTPS, secured with CQ Contact API Keys
• Your browser polls for new messages in real-time via the global updates endpoint
• Messages are stored only on the sender's and receiver's Citadels — nowhere else

Privacy: Messages travel directly between Citadels. There is no central server that stores or relays your messages. Each user's messages are stored in their own personal database.

CQ Explorer — Profiles, Contacts & Following

CQ Explorer is the unified hub for exploring CQ Profiles, managing your CQ Contacts, following users across Citadels, and browsing your social feed. It combines profile browsing, contact management, content discovery, and social interaction in a single two-column layout.

Route: /cq-contacts

Layout

CQ Explorer uses a two-column layout with tab navigation:

The two tabs switch between profile browsing (CQ Explorer) and social feed (CQ Feed). Your active tab is remembered between visits.

Exploring a Profile

1. Enter a CitadelQuest profile URL in the input field (e.g. https://one.citadelquest.world/Human)
2. Click Explore (or press Enter)
3. The profile is fetched and displayed in the main panel

What You See

• Profile photo — displayed as a thumbnail
• Username and domain — with a link to their public profile page
• Bio — with "show more" toggle for long bios (600+ characters)
• Spirit showcase — their AI Spirits with names, levels, XP, and colors
• Follower count — how many users follow this profile
• Content groups — tabbed navigation for their public CQ Share groups (e.g. "Introduction", "Projects")
• Shared items — publicly shared files and CQ Memory Packs with content previews

What You Can Do

• Add Contact — send a friend request directly from the Explorer
• Follow / Unfollow — subscribe to their content updates (see CQ Follow below)
• Download shared items — download files and Memory Packs to your Citadel
• Add to Library — add Memory Packs to your CQ Memory libraries
• View Memory Packs — preview Memory Pack graphs inline

The Explorer remembers the last profile you viewed (via localStorage) and auto-loads it on your next visit.

Sidebar

The right sidebar consolidates three lists, each in a collapsible glass-panel section:

CQ Contacts

Your friend connections from other Citadels. Shows:

• Profile photo, username, and domain for each contact
• Count badge (green) with total contacts
• Click any contact → loads their profile in the main panel (no page reload)

Following

CQ Profiles you've subscribed to. Shows:

• Profile photo, username, and domain
• Count badge (yellow) with total follows
• Yellow highlight on profiles with new content since your last visit
• Yellow dot badge on items with unseen updates
• Click → loads profile and marks as visited

Followers

Users who follow you. Shows:

• Profile photo, username, and domain
• Count badge (blue) with total followers
• Click → loads their profile in the main panel

Sidebar Features

• Collapsible sections — click any section header to collapse/expand. State is saved to localStorage.
• Active item highlighting — the currently explored profile is highlighted with a cyber-colored left border accent
• SPA-like navigation — clicking any sidebar item loads the profile instantly without page reload
• Feed update indicators — Following items show when there are new feed posts (separate from share/profile updates)

CQ Follow

CQ Follow is a one-way, lightweight subscription to any public CQ Profile. It lets you stay informed about new content — without requiring a mutual CQ Contact (friend) relationship.

Following a Profile

1. Explore any CQ Profile in CQ Explorer
2. Click the Follow button (next to Add Contact)
3. The button changes to a check icon — you're now following
4. The profile appears in your Following sidebar list

Unfollowing

1. Explore a profile you're following
2. Click the Following button → confirms unfollow
3. The profile is removed from your Following list

New Content Notifications

When profiles you follow publish new content:

• Sidebar: Following items get a yellow background and dot badge
• Explorer content: New shares/groups are highlighted with yellow borders
• Dashboard: The CQ Explorer tile shows a yellow badge with the count of profiles that have new content
• Automatic detection: When you open CQ Explorer, it checks all followed profiles for updates
• Feed tab badge: A bell icon with highlight appears on the CQ Feed tab when new feed posts are available

How It Works

• Following is completely separate from CQ Contacts — you can follow anyone with a public profile
• Both sides are aware: the followed user's Citadel receives a notification and records you as a follower
• Your follower count is visible on your public profile page
• Following uses the federation protocol for cross-Citadel communication
• When you follow a profile, you also automatically subscribe to their feeds (see CQ Feed)

CQ Contacts (Friend System)

CQ Contacts is the friend system connecting users across different Citadels. Unlike CQ Follow (one-way), CQ Contacts establishes a mutual, secure connection.

Your Identity

Every CitadelQuest user has a unique identity based on their domain + username, e.g.:

• https://one.citadelquest.world/Human

Your identity is proved by your Citadel's internet domain ownership.

Adding a Contact

Sending a Friend Request

1. Explore a profile in CQ Explorer
2. Click Add Contact
3. A friend request is sent to their Citadel

Receiving a Friend Request

When someone sends you a friend request:

• A notification appears in your notification bell
• A red badge appears on the CQ Explorer card on the Dashboard
• Go to CQ Explorer to accept or reject the request

What Happens on Accept

When a friend request is accepted:

• Both sides exchange CQ Contact API keys
• A secure HTTPS communication channel is established
• You can now send messages via CQ Chat
• The contact appears in both users' sidebar contact lists
• You automatically subscribe to their feeds — their posts appear in your CQ Feed timeline (see CQ Feed)

Contact Detail Page

Click on any contact in the sidebar to explore their profile. CQ Contacts see additional information based on CQ Contact Visibility settings:

• Profile photo — their photo (if they've chosen to share it)
• Username and domain — with a link to their Citadel
• Bio — their personal description (if shared)
• Spirit showcase — their AI Spirits with names, levels, XP, and colors (if shared)
• Shared items — files and CQ Memory Packs shared with CQ Contacts scope

Download to Citadel

Click on any shared item to download it to your Citadel:

• Memory Packs (.cqmpack) are downloaded into a dedicated contact library in your Memory Explorer, with automatic sync — if the contact updates the pack, your copy updates too
• Files are downloaded to your File Browser's downloads folder

See CQ Share for more about sharing.

How Federation Works

CQ Explorer relies on CitadelQuest's decentralized federation protocol:

1. No central directory — you connect directly with people you know
2. CQ Contact API Keys — each friendship uses unique keys exchanged during the friend request process, securing all communication
3. Direct HTTPS — all communication goes directly between Citadels
4. Privacy — no third party can see your contacts or messages
5. Rich profiles — contacts exchange profile data (photo, bio, Spirits) based on individual visibility settings
6. Content sharing — share files and Memory Packs with contacts via CQ Share
7. Social feed — publish and subscribe to feeds with posts, reactions, and comments via CQ Feed
8. Follow notifications — follow/unfollow actions are communicated via federation with fraud prevention (origin/host validation)

Account Migration: If you move your account to a different Citadel, your contacts and followers are automatically notified and updated with your new address.

CQ Share — Sharing Files & Knowledge

CQ Share lets you share files and CQ Memory Packs with your CQ Contacts or make them publicly accessible via a clean URL. It's the bridge between your personal data and the people you choose to share it with.

Route: /share

Overview

CQ Share gives you two ways to share:

• Public sharing (scope: Public) — anyone with the link can access the shared item, no login required
• CQ Contact sharing (scope: CQ Contacts) — only your CQ Contacts can access, authenticated via their CQ Contact API keys

You can share two types of content:

CQ Share Management Page

The Share management page shows all your shared items with:

• Title — display name for the shared item
• Type — File or Memory Pack
• Scope — Public or CQ Contacts
• URL — the share link (click to copy)
• Views — download/access counter
• Status — Active or Paused
• Display style — how the item is rendered (Full, Preview, or Hidden)
• Description — optional markdown text shown alongside the item
• Actions — Edit, toggle active/paused, delete

Search & Filter

The management page includes:

• Search — filter shares by title
• Type filter — show only Memory Packs or Files
• Status filter — show only Active or Paused items

Creating a Share

From File Browser

1. Select a file in the File Browser
2. Click the Share button in the file actions
3. Choose a title and scope (Public or CQ Contacts)
4. The share URL is generated automatically

From Memory Explorer

1. Open Memory Explorer (/memory)
2. Select a Memory Pack
3. Use the pack management dropdown menu and click Share
4. Choose a title and scope

From CQ Share Page

1. Go to CQ Share (/share)
2. Click Create New Share
3. Select the file or memory pack from your File Browser
4. Configure title, scope, and URL slug
5. Save — the share is now live

Share URLs

Each shared item gets a clean, readable URL:

https://your-citadel.com/YourUsername/share/My-Shared-Document

• The URL slug is auto-generated from the title but can be customized
• URLs are unique per user
• Public shares can be accessed by anyone with the link — displayed inline by default (use ?download to force download)
• CQ Contact shares require authentication

Display Styles

Each share has a display style that controls how it appears on your profile and in CQ Explorer:

Display style can be set per-share and optionally overridden at the group level (see Share Groups below).

Share Descriptions

Each share can have an optional description written in Markdown. The description appears alongside the shared content on your profile and in CQ Explorer.

You can also control the description position relative to the content:

• Above — description appears above the content
• Below — description appears below the content
• Left — description on the left, content on the right
• Right — description on the right, content on the left

Share Groups (Profile Content)

Share Groups let you organize your shared items into content groups — named, ordered collections that appear as tabbed navigation on your public profile and in CQ Explorer.

Route: /settings/share-groups (in Settings sidebar as Profile Content)

Creating a Group

1. Go to Settings → Profile Content
2. Click + New Group
3. Configure:
   • Group Title — name shown in the tab navigation (e.g. "Introduction", "Projects")
   • Icon — choose an icon for the group
   • Icon Color — pick a color for the icon
   • URL Slug — URL-friendly identifier
   • Visibility — Public, CQ Contacts, or specific contacts
   • Active — toggle the group on/off
   • Show header — toggle whether the group title is shown as a header
4. Click Save

Adding Shares to a Group

1. Open a group in Profile Content settings
2. Click + to add existing shares
3. Select from your active shares
4. Drag to reorder items within the group

Group Display Controls

Each item within a group can have its display style overridden:

• From share (inherit) — uses the share's own display style
• Full / Preview / Hidden — override for this group only

How Groups Appear

• Public profile page: Groups appear as tabbed navigation below the profile header. Visitors click tabs to browse different content sections.
• CQ Explorer: When exploring a profile, groups appear as tabs in the main content area with the group's icon and title.

Sharing Memory Packs

CQ Memory Pack sharing is especially powerful because of auto-sync:

How It Works

1. You share a Memory Pack via CQ Share
2. A CQ Contact downloads it to their Citadel (see CQ Explorer — Download to Citadel)
3. The downloaded pack remembers where it came from (the source URL)
4. Whenever the contact opens their Memory Explorer, the pack automatically checks for updates
5. If you've added new knowledge to the original pack, it syncs automatically

Use Cases

• Shared knowledge bases — maintain a pack and let contacts always have the latest version
• Team documentation — share project knowledge that stays up to date
• Learning materials — share curated knowledge graphs with friends or students

Managing Shares

Editing a Share

Click the edit icon on any share to change:

• Title — the display name
• URL slug — the URL path
• Scope — switch between Public and CQ Contacts
• Display style — Full, Preview, or Hidden
• Description — optional markdown text
• Description position — Above, Below, Left, or Right

Pausing a Share

Toggle the active/paused status. Paused shares return a 404 — the content is not deleted, just temporarily hidden.

Deleting a Share

Delete removes the share entry — the original file or memory pack is not deleted from your File Browser.

Public Shares on Your Profile

If you have a CQ Profile public page enabled (see CQ Profile), your public shares can be displayed on your profile page in two ways:

1. Share Groups — organized as tabbed content sections (recommended)
2. Shared items list — a flat list of all public shares (toggle in profile settings)

Both can be enabled independently via profile visibility settings.

Viewing Shares in CQ Explorer

When you explore any CQ Profile in CQ Explorer, you can see their public shared items and content groups. You can download files and Memory Packs directly to your Citadel. See CQ Explorer for details.

CQ Profile — Your Public Identity

CQ Profile gives you a beautiful public profile page on your Citadel — a personal landing page where visitors can see who you are, meet your Spirits, and browse your shared content. You control exactly what's visible.

Route: /settings/profile (settings) | /{username} (public page)

Your Public Profile Page

When enabled, your profile is accessible at:

https://your-citadel.com/YourUsername

For example:

• https://one.citadelquest.world/Human

The page displays:

• Profile photo — your uploaded photo (or a default avatar)
• Username and domain — your CitadelQuest identity with a copyable URL link
• Bio — your personal description with full Markdown and HTML support
• Spirit showcase — your AI Spirit companions with their names, levels, and XP
• Follower count — how many users follow your profile
• Profile Content — tabbed content groups with your shared items organized by topic (see CQ Share — Share Groups)
• Shared items list — optional flat list of all public CQ Share items
• Background theme — a customizable visual theme or custom background image
• Feed badges — badges linking to your public CQ Feed pages (see CQ Feed)
• Footer — "Powered by CitadelQuest" with version info

The page is clean, calm, and ad-free — just your identity, your way.

Tip: A Citadel admin can configure the Homepage Redirect to point the root URL (https://your-citadel.com) to any user's public profile page. See Administration.

Profile Settings

Route: /settings/profile

Access profile settings from the user menu → CQ Profile, or from Settings → CQ Profile.

The settings page has two tabs:

Public Profile Page Tab

Controls what visitors see on your public profile:

• Enable/Disable — toggle your public profile on or off
• Profile URL — your shareable link with a copy button
• Show profile photo — toggle photo visibility on the public page
• Show CQ Profile Content (content groups) — toggle display of your Share Groups as tabbed content sections
• Show shared items list — toggle display of a flat list of all public CQ Share items
• Spirit showcase — choose how your Spirits appear:
  • Off — no Spirits shown
  • Primary Spirit only — shows just your main Spirit (without star icon)
  • All Spirits — shows all your Spirits (primary marked with a star when you have multiple)
• Language — choose the language for your public profile page (English, Czech, or Slovak), independent of the visitor's language preference
• Page Theme — choose a background theme with visual previews:
  • Default — uses the visitor's current theme
  • CitadelQuest — the signature CQ cityscape
  • Night Forest — dark enchanted forest
  • Dreamy Flowers — ethereal floral landscape
  • Clear — clean minimal look
• Custom Background Image — upload your own background image (JPEG, PNG, or WebP, max 5MB, recommended 1920×1080+). Overrides the selected theme.
• Background Overlay — toggle a dark overlay on top of the background for better text readability

CQ Contact Visibility Tab

Controls what your CQ Contacts can see about you (via the federation protocol):

• Share bio — allow contacts to see your bio
• Share photo — allow contacts to see your profile photo
• Spirit showcase — same 3-mode control as the public page (Off / Primary only / All)

Profile Photo

Uploading

1. Go to CQ Profile settings (/settings/profile)
2. Click Upload Photo
3. Select an image from your device (JPEG, PNG, WebP, or GIF — max 5MB)
4. The photo is saved and immediately visible

Where It Appears

Your profile photo shows up in several places:

• Your public profile page (if enabled)
• CQ Explorer sidebar — your contacts and followers see your photo
• CQ Chat — your photo appears next to your messages in conversations

Removing

Click Remove to delete your profile photo. A default avatar icon will be shown instead.

Bio

Write a description about yourself in the Bio field. Supports Markdown and HTML for rich formatting — links, lists, bold, code, etc. A character counter is displayed below the field.

Your bio appears on:

• Your public profile page (if enabled) — rendered as formatted HTML
• CQ Explorer — when others explore your profile
• The CQ Contact view when contacts browse your profile

Spirit Showcase

The Spirit showcase displays your AI Spirit companions with:

• Ghost icon in the Spirit's color
• Spirit name
• Level and XP — showing their progression
• Star icon — marks the primary Spirit (only when showing all Spirits and you have more than one)

On desktop, Spirits appear on the right side of the profile header. On mobile, they appear below the header in a compact layout.

Your CQ Contacts also see your Spirits in CQ Explorer and on your public page, based on the visibility settings.

Profile Content (Share Groups)

Profile Content organizes your shared items into content groups that appear as tabbed navigation on your public profile page and in CQ Explorer.

Route: /settings/share-groups (in Settings sidebar as Profile Content)

For example, a profile might have tabs like "Introduction", "Projects", "Gallery" — each containing different shared files and Memory Packs.

See CQ Share — Share Groups for full details on creating and managing content groups.

Themes & Backgrounds

Built-in Themes

Choose from 5 visual themes in the settings, each shown as a thumbnail preview:

• Default — uses the visitor's current theme
• CitadelQuest — the signature CQ cityscape
• Night Forest — dark enchanted forest
• Dreamy Flowers — ethereal floral landscape
• Clear — clean minimal look

Custom Background Image

Upload your own background image to personalize your profile:

1. Go to profile settings → Custom Background Image
2. Click Upload Image
3. Select a JPEG, PNG, or WebP image (max 5MB, recommended 1920×1080 or larger)
4. The custom image overrides the selected theme

Background Overlay

Toggle the Background Overlay switch to add a dark semi-transparent layer on top of your background. This improves text readability, especially with bright or busy custom images.

The theme you choose is independent of the visitor's personal theme — it only affects how your public page looks.

How Others See You

Visitors (Public)

Anyone who visits https://your-citadel.com/YourUsername sees your public profile page with the settings you've configured. No login required. The page language is set by your Language setting, not the visitor's preference.

CQ Explorer

When other CitadelQuest users explore your profile URL in CQ Explorer, they see your profile card, content groups, shared items, and can follow you or send a friend request.

CQ Contacts (Federation)

Your CQ Contacts see additional information based on your CQ Contact Visibility settings. Profile data (bio, photo, Spirits) is fetched via the secure federation protocol.

Followers

Users who follow you can see your public content and receive notifications when you publish new items. Your follower count is displayed on your profile.

Not Enabled

If you haven't enabled the public profile page, visitors to your URL will see a 404 page. CQ Contacts can still see your federation profile data based on your visibility settings.

Settings

The Settings page lets you configure your CitadelQuest experience — from login credentials to AI model selection and account migration.

Route: /settings

General Settings

Login Information

• Username — displayed (read-only)
• Change Email — update your email address via modal dialog
• Change Password — update your password via modal dialog (requires current password)

Theme

• Background Theme — switch between different visual background themes
• CitadelQuest uses a dark cyber-themed design with green (#95ec86) accent color

Database

• Database Size — shows your personal database file size
• Optimize Database — runs SQLite VACUUM to reclaim unused space and improve performance

Account Migration

Move your entire account to another CitadelQuest instance:

1. Select a destination server from your CQ Contacts (must be an admin on the destination)
2. Choose an existing backup or create a new one
3. Confirm with your password
4. The migration transfers your complete database, files, and settings
5. Your contacts are automatically notified of your new address

Important: After migration, your account on the current server will be disabled.

Large accounts: For accounts with lots of data (hundreds of MB), creating a backup first and selecting it during migration is recommended for reliability.

AI Services

Route: /settings/ai

AI Models

• Primary AI Model — the main model used for Spirit conversations
• Secondary AI Model — used for image generation and other specialized tasks
• Update Models List — sync available models from CQ AI Gateway

Click the model selector button to open the AI Model Comparison interface where you can browse all available models with details about:

• Provider and model name
• Capabilities (text, image, code)
• Context window size
• Pricing per token

CQ AI Gateway Connection

• API Key — your CQ AI Gateway API key (auto-configured during registration)
• Credits — your current credit balance
• Add Credits — purchase additional credits
• Gateway Dashboard — seamless login to CQ AI Gateway web interface

CQ Profile

Route: /settings/profile

Manage your public identity and control what others see. See CQ Profile for the full guide.

Public Profile Page

• Enable/disable your public profile at /{username}
• Profile photo — upload, remove
• Bio — personal description with Markdown/HTML support and character counter
• Show/hide photo, profile content groups, shared items list on public page
• Spirit showcase — Off / Primary Spirit only / All Spirits
• Language — choose language for the public profile page
• Theme — choose a background theme for your public page
• Custom background image — upload your own background
• Background overlay — dark overlay for text readability

CQ Contact Visibility

• Spirit showcase — same 3-mode control for what contacts see

Profile Content

Route: /settings/share-groups

Organize your shared items into content groups that appear as tabbed navigation on your public profile and in CQ Explorer. See CQ Share — Share Groups for the full guide.

• Create groups with custom title, icon, color, and visibility
• Add shares to groups and reorder them
• Override display styles per group item
• Groups appear as tabs on your public profile page and in CQ Explorer

My Feeds

Route: /settings/cq-feed/my-feeds

Manage your CQ Feed channels — the feeds where you publish posts. See CQ Feed for the full guide.

• Create feeds with title, URL slug, scope (Public or CQ Contacts), description, and optional cover image
• Edit existing feeds — change title, description, scope, or cover image
• Toggle active/inactive — temporarily disable a feed without deleting it
• Delete feeds — removes the feed and all its posts

A default "General" feed is auto-created for every new user.

Subscribed Feeds

Route: /settings/cq-feed/subscribed

Manage feeds you're subscribed to from other Citadels, grouped by contact:

• Pause/Resume — temporarily stop receiving posts from a specific feed
• Unsubscribe — permanently remove a feed subscription
• Sync Subscriptions — discover and subscribe to new feeds from contacts added after your initial subscription

Subscriptions are created automatically when you accept a friend request or follow a profile.

Settings Navigation

The settings sidebar provides quick access to:

• General Settings — login, theme, database, migration
• CQ Profile — public profile page, contact visibility
• Profile Content — share groups for profile page
• My Feeds — manage your CQ Feed channels
• Subscribed Feeds — manage feed subscriptions from other Citadels
• AI Services — models, gateway, credits

Backup & Restore

CitadelQuest includes a full backup system to protect your data. You can create, download, upload, and restore backups at any time.

Route: /backup

Creating a Backup

1. Go to Backup (/backup)
2. Click Create Backup
3. CitadelQuest packages your complete data:
   • Personal database (all your settings, conversations, memories, contacts, etc.)
   • User data files (everything in your File Browser)
4. The backup appears in your backup list when complete

Backups are stored as .citadel ZIP files on your server in your personal backup directory.

Downloading a Backup

Click the Download button next to any backup to save it to your local device. This is recommended for:

• Off-site backup storage
• Before major updates
• Before account migration
• Peace of mind

Uploading a Backup

1. Click Upload Backup
2. Select a backup .citadel ZIP file from your device
3. The file is uploaded to your Citadel

For large backup files, CitadelQuest uses chunked uploading — the file is split into smaller pieces and reassembled on the server, preventing timeout issues.

Restoring from Backup

1. Click Restore next to the backup you want to restore
2. Confirm the action
3. CitadelQuest:
   • Restores the database from the backup
   • Restores your user data files
4. Refresh the page after restoration completes

Deleting Backups

Click Delete next to any backup to remove it and free up storage space.

Best Practices

• Regular backups — create backups periodically, especially before updates
• Download copies — keep backup copies on your local device or external storage
• Before migration — always create a fresh backup before migrating your account
• Check storage — monitor backup size on the Dashboard's Storage Usage panel

Administration

The Administration panel is available to users with Admin privileges. The first registered user on a new CitadelQuest installation automatically becomes an admin.

Route: /administration

Admin Dashboard

The main admin page shows:

• User statistics — total users, recently registered
• Quick actions — links to user management, updates, system settings
• Recent users — table of recently registered users

User Management

Route: /administration/users

Manage all users on your Citadel:

User List

• View all registered users with username, email, roles, and registration date
• Search to filter users by name or email

User Actions

• View Info — see detailed user information in a modal dialog
• Toggle Admin — grant or revoke admin privileges (cannot remove your own admin role)
• Reset Password — generate a new password for a user
• Delete User — remove a user and their data (cannot delete yourself or the last admin)

Application Updates

Route: /administration/update/check/{step}

Check for and install updates to CitadelQuest:

1. The system checks for available updates on GitHub
2. If a new version is available, you can download and install it
3. The updater:
   • Creates a safety backup
   • Downloads the new version
   • Applies file updates (preserves your .env configuration)
   • Runs database migrations
   • Clears and warms up the cache
4. Refresh the page to see the new version

Tip: Always create a manual backup before updating, just in case.

System Settings

The admin dashboard includes system-level configuration panels:

User Registration

• Toggle Registration — enable or disable new user registration
• Max users — set a maximum number of allowed users (0 = unlimited)
• When disabled, the registration page shows a "Registration is currently disabled" message
• Useful for limiting access to your Citadel

Homepage Redirect

Redirect the Citadel homepage (https://your-citadel.com) to a user's public CQ Profile page — for unauthenticated visitors only. Authenticated users still see their Dashboard.

1. Select a Profile user from the dropdown (any registered user)
2. Toggle the redirect on
3. Visitors to your root URL are now redirected to that user's public profile page

This is ideal when you want your Citadel's domain to serve as a personal website or landing page powered by CQ Profile.

Server Logs

Route: /administration/logs

View and manage server log files:

• List all available log files with size and last modified date
• View log file contents with tail/head navigation and line count
• Download log files for offline analysis
• Clear log files to free space

System Backups

Route: /administration/system-backups

Manage backups across all users:

• View all user backup files
• Delete old or unnecessary backups
• Monitor backup storage usage

Migration Requests

Route: /administration/migrations

When users from other Citadels request to migrate to your instance:

• View incoming migration requests
• Accept to allow the user's account to be transferred to your Citadel
• Reject to decline the request
• Monitor migration progress and status

Installing Your Own CitadelQuest

Running your own Citadel means complete control over your data — your server, your rules, your privacy.

Server Requirements

• PHP 8.4 or higher
• Apache with mod_rewrite enabled
• SQLite3 PHP extension
• HTTPS required
• Standard PHP extensions: mbstring, intl, json, zip

CitadelQuest works on most shared web hosting plans, VPS, or dedicated servers.

Installation — Zero-Click Installer

CitadelQuest features an incredibly simple installation process:

Step 1: Download

Go to GitHub Releases and download the Installer Package (citadelquest-installer-*.zip, ~8 KB).

Step 2: Upload

Extract the ZIP and upload install.php to your web server's /public (sub)directory.

Step 3: Run

Open install.php in your web browser (e.g., https://yourdomain.com/install.php).

The installer automatically:

• Downloads the latest pre-built release package
• Extracts all files
• Sets up the directory structure
• Cleans up after itself

Step 4: Register

Visit your domain and register the first user account. This account automatically receives Admin privileges.

Step 5: Onboard

Follow the onboarding wizard to connect CQ AI Gateway and create your first Spirit.

That's it! Your Citadel is ready.

Alternative: Docker

A Dockerfile is available for containerized deployment. Build and run the container to deploy your Citadel in an isolated environment. See the docker/README.md in the repository for detailed instructions.

Configuration

Environment File (.env)

The .env file in your installation root contains key settings:

• APP_ENV — prod for production
• APP_SECRET — unique secret key for your installation
• DATABASE_URL — path to the main database (default: sqlite:///%kernel.project_dir%/var/main.db)

The .env file is preserved during updates — your configuration won't be overwritten.

Domain Setup

For the best experience:

1. Point your domain to the CitadelQuest installation directory
2. Ensure HTTPS is configured (Let's Encrypt provides free certificates)
3. Apache's mod_rewrite should route all requests through public/index.php
4. On Cloudflare use Full SSL mode!

Updating

Updates are managed from the Admin Dashboard:

1. Go to Administration → check for updates
2. The updater downloads and applies the new version
3. A safety backup is created before every update
4. Database migrations run automatically
5. Cache is cleared and rebuilt

PWA Support

CitadelQuest works as a Progressive Web App (PWA):

• Install it on your phone's home screen for an app-like experience
• Works on Android and iOS
• Desktop fullscreen mode available
• Offline-capable for cached content

Multiple Users

A single CitadelQuest installation supports multiple users:

• Each user gets their own SQLite database
• Each user's data is completely isolated
• Admins can manage users, reset passwords, enable/disable registration
• Storage limits can be configured per Citadel

CQ AI Gateway

To power your Spirits with AI, connect to CQ AI Gateway:

• Automatic: If you select "Auto-create CQ AI Gateway accounts" during user registration, accounts are created automatically
• Manual: Enter your API key in Settings → AI Services
• Credits: New users receive free starting credits; additional credits available via the Add Credits button

Visit cqaigateway.com for more information.

CQ Feed — Social Feed

CQ Feed is CitadelQuest's decentralized social feed — a familiar social network experience where you publish posts, follow feeds from other Citadels, react, and comment. All content stays on your server, distributed peer-to-peer via federation.

Access: CQ Feed tab in CQ Explorer (/cq-contacts)

Overview

CQ Feed brings social networking to CitadelQuest without sacrificing privacy or sovereignty:

• Your posts live on your server — not on a corporate platform
• Federation distributes content — followers on other Citadels receive your posts automatically
• Markdown support — format your posts with rich text, links, and more
• Reactions and comments — interact with posts across Citadels
• Multiple feeds — organize posts into separate feeds with different visibility scopes
• Real-time updates — new posts appear automatically via background polling

Accessing CQ Feed

CQ Feed lives inside CQ Explorer (/cq-contacts) as a tab:

Click the CQ Feed tab to switch to your social timeline. The active tab is remembered between visits.

Timeline

The timeline shows an aggregated, chronological view of posts from all the feeds you're subscribed to, plus your own posts.

Each post displays:

• Author — profile photo, username, and domain (clickable — opens their profile in CQ Explorer)
• Feed badge — which feed the post belongs to, with scope indicator (green = CQ Contacts, gray = Public)
• Timestamp — when the post was published
• Content — Markdown-rendered post text
• Reactions — like (heart) and dislike counts
• Comments — comment count with expandable comment thread

New posts since your last visit are highlighted with a orange left border.

Loading More Posts

The timeline loads posts in batches. Click Load more at the bottom to fetch older posts.

Creating a Post

At the top of the CQ Feed tab:

1. Type your message in the "What's on your mind?" textarea
2. Select which feed to post to (dropdown — defaults to your "Public" feed)
3. Click Publish

Your post is immediately visible in your timeline and distributed to subscribers via federation.

Markdown: Posts support full Markdown formatting — bold, italic, links, lists, code blocks, and more.

Tip: Click the settings icon next to the feed selector to go directly to feed management settings.

Feeds

Each user can have multiple feeds, each with its own scope and audience.

Default Feed

When you register, a "Public" feed is automatically created with Public scope. You can rename it, change its scope, or create additional feeds.

Feed Scopes

Managing Your Feeds

Route: Settings → My Feeds (/settings/cq-feed/my-feeds)

From the feed management settings page you can:

• Create new feeds with a title, URL slug, scope, description, and optional cover image
• Edit existing feeds — change title, description, scope, or image
• Toggle feeds active/inactive
• Delete feeds (and all their posts)

Public Feed Pages

Each feed has a public page accessible at:

https://your-citadel.com/YourUsername/view-feed/public

These pages show paginated posts with the feed header, and are visible based on the feed's scope setting.

Reactions

React to posts with:

• Like (heart icon) — shows in red when active
• Dislike (thumbs down) — shows in white when active

How Reactions Work

• Click a reaction button to toggle it on/off
• You can only have one reaction per post (liking removes a previous dislike, and vice versa)
• Reaction counts update instantly (optimistic UI)
• Reactions on remote posts are sent to the source Citadel via federation
• You cannot react to your own posts

Stats Refresh

After loading the timeline, reaction and comment counts are refreshed in the background from the source Citadels. If a post has been deleted on the source, it's automatically removed from your cached timeline.

Comments

Click the comment icon (with count) on any post to expand the comments thread.

Reading Comments

• Comments are lazy-loaded from the source Citadel when you first open the thread
• Shows commenter's profile photo, username, domain, and timestamp
• Supports nested replies (up to 2 levels deep)

Writing Comments

1. Click the comment icon to expand the comments panel
2. Type your comment in the textarea at the bottom
3. Press Enter to submit (Shift+Enter for newline)
4. Your comment appears immediately

Replying to Comments

• Click the Reply button on any top-level comment
• The textarea placeholder changes to show you're replying
• Your reply appears nested under the parent comment

Editing & Deleting

• Edit your own comments — click the pencil icon for inline editing
• Delete your own comments — click the trash icon and confirm

Comment Moderation

If someone comments on your post, you can:

• Hide/show comments — click the eye icon to toggle a comment's visibility (the comment is hidden from other readers but not deleted)

Notifications

When someone comments on your post, you receive a notification — clicking the notification navigates to the post and auto-opens the comment thread.

Subscribed Feeds

When you accept a friend request or follow a profile, you automatically subscribe to their feeds. Subscribed feeds appear in your timeline.

Managing Subscriptions

Route: Settings → Subscribed Feeds (/settings/cq-feed/subscribed)

The subscribed feeds settings page shows all feeds you're subscribed to, grouped by contact:

• Pause/Resume — temporarily stop receiving posts from a specific feed
• Unsubscribe — permanently remove a feed subscription
• Sync Subscriptions — discover and subscribe to new feeds from contacts you've added since your initial subscription

Feed Badges in CQ Explorer

When exploring a profile in CQ Explorer, you'll see feed badges showing their available feeds:

• Green badge = CQ Contacts scope
• Gray badge = Public scope
• Click a badge for quick actions (pause/unsubscribe)

Feed Badges on Public Profiles

Public feeds are also shown as badges on CQ Profile pages, with links to the feed's public page.

Real-time Updates

CQ Feed integrates with CitadelQuest's global update polling:

• New post detection — background polling checks for new posts from subscribed feeds
• CQ Feed tab badge — a bell icon with highlight appears on the CQ Feed tab when new posts are available
• Sidebar indicators — Following contacts in the sidebar show content-specific update and CQ Chat messages indicators
• Dashboard badge — the CQ Explorer dashboard tile reflects new feed content
• Auto-refresh — when you click the CQ Feed tab or it's already active, new posts are fetched and displayed automatically

How It Works (Federation)

CQ Feed uses CitadelQuest's decentralized federation protocol:

1. Posts stay on your server — you own and control all your content
2. Subscribers fetch posts — other Citadels periodically check for new posts via federation endpoints
3. Incremental sync — only posts newer than the last check are fetched (efficient bandwidth)
4. Reactions and comments travel via federation — when you react to a remote post, the reaction is sent to the source Citadel
5. No central server — content flows directly between Citadels over HTTPS
6. Scope-based access — public feeds are accessible to anyone; CQ Contacts feeds require authentication

Privacy: Your posts are stored only on your Citadel and cached locally on subscribers' Citadels. There is no central feed server. You can delete your posts at any time — deleted posts are cleaned up from subscribers' caches during the next stats refresh.