# Xunaro — Complete Platform Handbook **Source snapshot:** 2026-09-18 **Canonical info page:** `https://xunaro.net/info/` **Purpose:** This document is the single public handbook for understanding how Xunaro works: its public surfaces, identities, projects, Studio, publishing, project runtimes, APIs, servers, accounts, discovery, safety, routing, and source structure. > This handbook intentionally does **not** publish secret values. Database credentials, private API/backend keys, encryption material, session secrets, infrastructure credentials, private signing keys, server-control credentials, and similar secrets are not documentation. Everything needed to understand and use the platform is described; secret values must remain secret. --- ## 1. What Xunaro is Xunaro is a web platform for creating, publishing, discovering, and managing projects. A project can stay private in Studio, be shared as an unlisted project, be published publicly, or receive a product-style public URL such as a Game, App, Tool, Store, Blog, Study project, Wiki, and other supported publishing destinations. The platform has two different ideas that must not be confused: 1. **The project identity / overview** — the permanent public identity of a normal project, addressed by a `P...` UUID on `project.xunaro.net`. 2. **The published project site** — the actual public content made by the creator, which can live on a Game/App/Tool/etc. URL chosen in Studio. The overview is Xunaro-owned UI. The published site is creator-owned content rendered through Xunaro's project runtime. Xunaro also includes global accounts, account profiles, discovery/search, recommendations, project collaboration, templates, project-local accounts, messaging, Community, notifications, moderation/reporting, project analytics, ads, Login APIs, hosted Server APIs, project servers, AI/Codex-oriented tooling, project backups, site files, and project page editing. There is currently **no Company feature**. Company creation, `C...` IDs, Company routes, Company unlocks, and Company Studio screens were removed from the current source. ### Product principles Xunaro's product direction emphasizes mostly-free access, optional rather than forced project advertising, clear separation between public IDs and secrets, creator control over project content, human-readable support/help, and advance transparency around major platform changes. Paid/expanded plans are intended primarily to increase limits/capacity rather than create a completely different product. Exact pricing, quotas, trials, refunds and commercial terms can change and should be read from the live Xunaro UI when money is involved; this handbook describes the platform model rather than acting as a billing contract. --- ## 2. The main public surfaces Xunaro deliberately separates major product surfaces by host. | Surface | Canonical host / path | Purpose | |---|---|---| | Main Xunaro | `https://xunaro.net/` | Home, discovery entry points, global auth, messages, notifications, support, news, public APIs, path-based project types | | Studio | `https://studio.xunaro.net/` | Create and manage projects/templates, pages, files, APIs, servers, team, plans and visibility | | Project overview | `https://project.xunaro.net/P.../` | UUID-only Xunaro project overview | | Accounts | `https://account.xunaro.net//` | Public account profiles | | Settings | `https://settings.xunaro.net/` | Account/settings/safety surfaces | | Games | `https://game.xunaro.net//` | Published Game projects | | Apps | `https://app.xunaro.net//` | Published App projects | | Tools | `https://tool.xunaro.net//` | Published Tool projects | | Stores | `https://store.xunaro.net//` | Published Store projects | | Blogs | `https://blog.xunaro.net//` | Published Blog projects | | Community | `https://community.xunaro.net/` | Community posts/discussion | | AI | `https://ai.xunaro.net/` | Xunaro AI surfaces and host connector/download routes | | Short links | `https://xuna.ro/` | Fixed Xunaro short-link router | Additional project kinds are path-based on the main domain: `/site/`, `/study/`, `/education/`, `/forum/`, `/software/`, `/art/`, `/wiki/`, `/music/`, `/coffee/`, and `/pizza/`. The main host also contains public/global surfaces such as `/discover/`, `/search/`, `/login/`, `/signup/`, `/recovery/`, `/messages/`, `/notifications/`, `/support/`, `/report/`, `/news/`, `/status/`, `/feedback/`, `/rules/`, `/coding/`, `/connect/`, and `/info/`. --- ## 3. Public identifiers Xunaro uses immutable-looking public identifiers in addition to internal numeric database IDs and editable/readable names. ### Account UUID Format: ```text U + 14 random alphanumeric characters ``` Example: ```text U7aK9Lm2Qx4R8Tp ``` The complete length is 15 characters. ### Project UUID Format: ```text P + 34 random alphanumeric characters ``` Example: ```text PaB3dE5fG7hJ9kL2mN4pQ6rS8tU1vW3xY5z ``` The complete length is 35 characters. This is the canonical public identity used by `project.xunaro.net`. ### API UUID Format: ```text API + 7 random alphanumeric characters ``` Example: ```text API7aK9Lm2 ``` The complete length is 10 characters. This is a **public application/server identifier**, not a secret key. All three ID families are generated from digits, uppercase letters, and lowercase letters. The database maintains uniqueness and allocates missing UUIDs for older records. --- ## 4. Accounts and authentication Xunaro has one global Xunaro account system. Authentication is owned by the primary `xunaro.net` host even when a user is browsing a product subdomain. Product hosts redirect login, signup, recovery, connect and logout traffic back to the global authentication surface rather than implementing independent account systems. Global account features in the current source include: - account signup and email-code flows; - login/logout; - password recovery/reset; - public account profiles; - profile images; - follows; - notifications; - messages and message threads; - device/settings surfaces; - safety settings such as blocks/mutes; - account switching/consent helpers; - external-link permissions; - reporting/moderation integration; - per-account Studio preferences. A public account can be reached as: ```text https://account.xunaro.net// ``` The shorthand: ```text https://xunaro.net/@ ``` redirects to the canonical account host. ### Global accounts versus project-local accounts A **global Xunaro account** is the user's identity across Xunaro. A **project-local account** belongs to one project. Project creators can build account-backed experiences without creating new global Xunaro accounts. Project-local accounts support project login/signup, project saves, social/friend/party features, and can connect to a global Xunaro identity through the Xunaro Connect flow when that feature is used. These are deliberately separate identity layers. --- ## 5. Projects A normal project is the core creator object in Xunaro. It has an owner, an internal Studio slug, a `P...` UUID, a name, description, category, project status, visibility, content/pages, optional published destination, analytics, collaboration state, and related project resources. Project creation currently supports two creation kinds: - **Project** - **Project template** There is no Company creation type. A normal project can be created from an empty starting point or from a supported starter template. The source currently includes an Empty starter and a Blog starter. ### Project categories Current project categories include Website, Application, Game, Blog, Documentation, Portfolio, Business, Productivity, Social, Entertainment, News, Sports, Science, Technology, Finance, Health, Travel, Community, Study, Education, Forum, Software, Art, Wiki, Music, Coffee, Pizza, and Other. ### Project stages The public project status/stage system currently normalizes to: - Prototype - Testing - In Development - Released - Archived Older Planning/Paused values normalize to Prototype in the current display logic. --- ## 6. Project identity URL versus published site URL This is one of the most important Xunaro rules. ### Canonical project overview Normal projects use: ```text https://project.xunaro.net/P<34 characters>/ ``` `project.xunaro.net` is UUID-only. A readable project name is not a valid public identity URL there. For example: ```text project.xunaro.net/publictransportmanager/ ``` is not the canonical format and should not become a readable-name project route. ### Published site A project can instead publish its actual creator content to a public product namespace such as: ```text https://game.xunaro.net/publictransportmanager/ https://app.xunaro.net/example/ https://tool.xunaro.net/example/ https://blog.xunaro.net/example/ https://xunaro.net/study/example/ https://xunaro.net/wiki/example/ ``` The readable published URL and the project UUID are different pieces of identity. ### What happens if a `P...` UUID is opened on a product host If a product host receives a valid project UUID as the public name, the request redirects to the canonical UUID project overview instead of treating the UUID as a normal published name. ### `/uuid//...` identity lookup Published namespaces also support a special identity lookup: ```text /// ``` The literal first segment is `uuid`. Xunaro resolves `` **inside the current project kind only** and redirects to the owning project's `project.xunaro.net/P.../` overview. Any trailing page path is ignored because this route asks “which project owns this published URL?” rather than “open this page.” Example: ```text https://game.xunaro.net/uuid/publictransportmanager/play ``` resolves `publictransportmanager` as a **Game** published URL and redirects to that game's project UUID overview. The published name `uuid` is reserved so creators cannot create a conflicting URL. --- ## 7. Published URL rules New custom published names use lowercase letters, numbers, dashes, and underscores and are currently validated as 3–30 characters in Studio. The public routers retain compatibility with some older records, but new names use the current stricter Studio rule. Important rules: - the name `uuid` is reserved; - a project UUID is not a custom project URL name; - a readable published name belongs to one publishing destination/kind; - `project.xunaro.net` does not become a readable-slug publishing host; - the exact published kind matters during lookup; - normal nested page paths may contain lowercase alphanumerics, `_`, and `-` in bounded path segments; - invalid or unknown published routes return Xunaro's not-found behavior rather than silently mapping to a different project. --- ## 8. Publishing destinations Current publishing labels include: | Kind | Public destination | |---|---| | Project overview | `project.xunaro.net/P.../` | | Game | `game.xunaro.net//` | | App | `app.xunaro.net//` | | Tool | `tool.xunaro.net//` | | Store | `store.xunaro.net//` | | Blog | `blog.xunaro.net//` | | Site | `xunaro.net/site//` | | Study | `xunaro.net/study//` | | Education | `xunaro.net/education//` | | Forum | `xunaro.net/forum//` | | Software | `xunaro.net/software//` | | Art | `xunaro.net/art//` | | Wiki | `xunaro.net/wiki//` | | Music | `xunaro.net/music//` | | Coffee | `xunaro.net/coffee//` | | Pizza | `xunaro.net/pizza//` | Store content also has main-domain routing support for `/store//...` as an alias/compatibility path while the canonical project URL helper uses the Store subdomain. --- ## 9. Public project overview The UUID overview is Xunaro UI, not the creator's raw project site. It presents project identity and project information using Xunaro styling. When a project has a published site, the overview can expose a **SITE** action that opens the actual published project. The overview remains at the permanent `P...` route. The overview does not replace the published site and the published site does not replace the UUID identity. --- ## 10. Project preview cards Project cards used in places such as Discover, recommendations, public account pages, and Search follow a split action model: - clicking the **main card/preview area** opens the project's actual published site when it has one; - clicking **MORE →** opens the UUID project overview; - if the project has no published site, both behaviors fall back to the UUID project overview. Cards can show the project icon, banner, name, description, creator, verification badge, collaborator labels, stage, and last-updated information depending on context. On mobile, public project grids use compact responsive layouts instead of turning every recommendation into one oversized horizontal row. --- ## 11. Visibility and public publishing requirements Projects are created Private or Unlisted. A brand-new project cannot be created directly as Public. Before a project can be published publicly or claim a new custom site URL, the current server-side checklist requires: 1. the owner account is at least **10 minutes old**; 2. the project is at least **5 minutes old**; 3. the project name has at least **3 characters**; 4. the description has at least **30 characters**; 5. the project contains a meaningful main page or project page with real content/code. These checks are enforced on the server, not only by disabling buttons in the browser. The purpose is to reduce empty/spam projects and ensure a public URL represents an actual project. Existing already-published projects are not automatically unpublished simply because a newer checklist was introduced. --- ## 12. Studio Studio is the creator workspace at: ```text https://studio.xunaro.net/ ``` The main dashboard separates **Owned** and **Collab** projects and separately shows project templates. On desktop, project cards use a three-column layout; phone layouts use a smaller responsive grid instead of compressing three tiny cards into the same width. Studio project workspaces are still addressed internally with their Studio slug: ```text https://studio.xunaro.net/project// ``` That Studio slug is not the canonical public project identity. ### Main project workspace areas The project command menu includes the major areas: - Customization - Settings - Work - API for the owner (inserted by the Studio navigation code) - Team - Plans - Visibility The responsive mobile command menu wraps into a grid rather than requiring a long horizontal scroll. ### Work The Work area currently contains project-content tools including: - Main page - Pages - Protected page - Not-found page - Files - URL - Server - Ideas/planning-related workspace surfaces The exact sidebar shown depends on permissions and the selected project resource. --- ## 13. Main page and project pages A project can have a custom main HTML document and additional named pages. Project page paths support nested paths. A page URL under a published project stays inside the selected public namespace. A project page can be configured to appear in the project's own page list/navigation or remain hidden from that list while still existing. Studio supports page editing through direct source editing and visual/no-code oriented tooling. The current editor code includes HTML/CSS-style element editing, actions, forms, project account widgets, media/input components, visual programs, and project runtime features. ### Special project documents Projects also have special content concepts for: - Main page - Protected page - Project-specific 404/not-found page A protected project page verifies its project password before project code is loaded. --- ## 14. Runtime page creation/deletion Xunaro supports secure project-page management from project runtime code. The API endpoint is: ```text POST https://xunaro.net/api/project-pages/ ``` It supports create, delete, and list operations through signed/validated capabilities. There are two trust levels: ### Studio editor capability A project owner or accepted collaborator with code-edit permission can receive a short-lived signed page-management capability. The server re-checks project access and collaborator permissions. Collaborators that require owner approval cannot bypass that approval requirement by calling the endpoint directly. ### Project-local account capability A creator can explicitly opt a project document into account-owned page creation with: ```html ``` Xunaro ties the capability to the current source document using a server-side HMAC/fingerprint. Changing/removing the opt-in invalidates the previous capability. Security rules include: - runtime account-created pages are recorded with ownership; - project-local users cannot delete another account's pages; - they cannot create a mixed-ownership page branch under another account or under an unowned/Studio page; - untrusted runtime-created pages cannot later become editor-authorized source pages; - page paths are validated and reserved top-level names are blocked; - project-local runtime pages are limited to **25 pages per project-local account**; - each project-local runtime-created page is capped at **256 KiB** even if the project itself has a larger page allowance; - the normal project page count/storage limits still apply; - create/delete actions are rate-limited; - project-account deletion cleans up that account's runtime-owned pages. This system is designed so a project can safely let its own users create content without giving those users Studio ownership. --- ## 15. Project browser/runtime environment Creator HTML is not treated as first-party Xunaro UI. The custom main page is rendered through a controlled project runtime. The custom project home uses an iframe sandbox that permits the web behaviors needed by normal project pages (scripts, forms, downloads, modals and controlled popups) while keeping the creator document separated from Xunaro-owned UI. Xunaro provides a project-scoped browser-storage bridge so project code can use local/session-style data without freely colliding with another project's stored values. The runtime namespaces data by project. Project pages also receive Xunaro runtime helpers for navigation and higher-level project features. --- ## 16. XunaroPage and no-code actions The browser runtime exposes `XunaroPage` and related helpers used by Studio-generated/no-code actions. Current action families include things such as: - local state and template values; - project saves/load/list/delete; - project account login/signup/logout/delete; - Sign in with Xunaro / Xunaro Connect; - account-aware navigation; - online room creation/join/watch/leave/start/update; - project social status/friend requests/party invites/presence; - normal navigation/redirect actions; - editor-generated visual programs. The runtime keeps these APIs project-scoped rather than exposing the global Xunaro database directly to creator JavaScript. --- ## 17. Project-local accounts and saves Projects can offer their own local account system. Current source contains support for: - project account signup/login/logout; - account deletion; - sessions; - project-specific saves; - save metadata; - project account presence; - project friend requests/friendships; - parties and party invites; - linking/signing in with a global Xunaro account through Xunaro Connect. Project accounts live inside the project boundary. They are not replacements for Xunaro global accounts and do not automatically receive global Xunaro privileges. --- ## 18. Multiplayer/public project primitives Xunaro contains project-facing shared primitives intended for games/apps and interactive projects. Current source includes backing systems for: - public counters; - rooms and room players; - public arena queues/presence/scores/matches; - online room watching/polling; - project account social/presence state; - server-shared project memory features. These are bounded platform primitives, not direct database access. --- ## 19. Project files, uploaded sites and GitHub Studio supports project file storage and static site files. The source includes: - project files/folders; - project web files; - site root records; - secure file download/upload handling; - site-file serving; - project export/backups; - project GitHub source tracking; - GitHub pull support for built static sites. The GitHub pull UI is designed to preserve local edits and report conflicts. Optional automatic pulling requires a host cron job; the current source describes a five-minute cron invocation with project checks performed less frequently internally. Project storage is quota-aware. Page changes, files, site imports and runtime-created content check project capacity before saving. --- ## 20. Templates Project templates are distinct from ordinary projects. A template can be created and managed in Studio, have a public template identity/URL, and be used to create project content. The template system tracks template definitions and template uses. The current project-creation system also has built-in starter templates, currently including Empty and Blog. A template does not use a readable `project.xunaro.net/` project route. --- ## 21. Collaboration and Team Projects can have collaborators. The current role labels include: - Manager - Coder - Tester - Viewer The permission system is more precise than the role name. Collaborator records can control abilities such as: - edit code; - chat; - edit plans; - customize the project; - view statistics; - use Codex/API-related change submission; - manage users; - edit settings; - whether changes require owner approval. Studio checks permissions server-side when loading project workspaces and performing project actions. Projects also support collaboration invite/collab routes and project-transfer flows. --- ## 22. Plans, tasks and project organization The project planning system includes project status/stage, priorities and task columns. Priority labels include Low, Normal, High and Urgent. Task/work columns include To Do, In Progress, Testing and Completed. Studio's Plans surface is part of the project command menu and is permission-aware. --- ## 23. Visibility and statistics The Studio Visibility surface combines the project's public visibility controls and analytics/statistics views. The source contains project view/impression analytics, site visit tracking, project discovery impressions, ad statistics, and date-range based reporting. Visibility/statistics access can be owner-only or granted to collaborators through the corresponding permission. Common analytics periods include 7 days, 30 days, 90 days and all time where the particular screen supports them. --- ## 24. Search, Discover and recommendations Xunaro has global public Search plus Discover/recommendation systems. Global search can find public accounts and public projects. Studio search is a separate creator-focused search mode intended for the signed-in user's Studio content such as projects, pages, messages/tasks/ideas and other Studio entities. Public recommendation and discovery code uses project metadata and impression tracking. Project preview cards always keep the published-site action separate from the UUID overview action as described earlier. --- ## 25. Ads Xunaro contains a project advertising system with: - project ad campaigns; - ad placements; - impressions/views/clicks; - project ad balances/reservations; - video upload/processing; - ad moderation/verification surfaces; - project ad statistics; - creator-side ad editing/preview/player code. The product policy for project advertising is that creator advertising is optional and ad creative should represent the actual project rather than use deceptive fake gameplay. Xunaro's source contains moderation and verification machinery rather than treating uploaded ad video as automatically trusted. The current code also contains Xunaro token/balance records used by parts of the ad system. Token/balance internals are implementation details and are not a substitute for real-world money unless a specific product surface explicitly says so. --- ## 26. Login APIs A project owner can create Login API applications. Their public application identifier uses the `API` + 7-character format. The public ID identifies the API. It is not the private backend credential. The current Login API contract supports a project-owned login integration with explicit backend authentication for private-key flows, PKCE/state, authorization start, token exchange and identity lookup. Important security rule: > A private Login API backend key must never be embedded in public JavaScript, a downloadable app, an executable, a URL, or a public guide. The platform's Login API endpoints are under: ```text https://xunaro.net/api/login/ ``` Operations include `start`, `token`, and `me`. The current API implementation uses diagnostic response headers/request IDs and structured JSON errors. Application code should validate the API/client identity it receives rather than trusting a browser success page alone. --- ## 27. Hosted Server APIs Xunaro also contains hosted Server API functionality for applications that need Xunaro-managed backend features without running arbitrary server code. The hosted backend can provide bounded operations for: - Xunaro login/session integration; - private JSON-like app data; - private file storage; - user lookup by exact username; - contact requests; - accepted contacts; - two-person text messaging; - logout/session revocation. The public hosted base is: ```text https://xunaro.net/api/server/backend/ ``` A Server API is linked to a Login API in the same project and hosted mode must be explicitly enabled by the project owner. Changing hosted backend settings revokes old hosted sessions/pending attempts so apps should start a fresh login after changes. The hosted API is **not** arbitrary server-side code hosting. It does not turn user uploads into trusted PHP/SQL/executable backend code. --- ## 28. Project API management in Studio The owner-facing API tab is inserted into the normal project Studio navigation and is project-scoped. The current project API UI exposes Login APIs. Some server-API UI paths are still marked as coming soon in the API tab even though the codebase contains hosted Server API functionality and project-server infrastructure elsewhere. Treat the deployed UI as the authority for what creators can currently activate. API/Codex change-submission keys can carry capabilities such as reading project data, submitting page/Work changes, accessing Plans/Ideas, requiring review, and expiring after a configured interval. Turning off review requires explicit acknowledgement because changes can then apply immediately. --- ## 29. Project servers / VPS-style containers A project can create a server from **Studio → Work → Server**. The creator supplies only the server name. Xunaro assigns an `API` + 7-character server identifier automatically. There is no creator-selected `/vps//` management URL. A server's management UI is embedded inside the project's Work tab rather than existing as a disconnected Studio product. Current server management surfaces include areas such as overview/status, terminal/files/settings-style management, allocation, public-port exposure and deletion depending on server state and deployment support. The public application route uses the generated server identifier, for example: ```text https://xunaro.net/vps/API7aK9Lm2/ ``` The current UI describes project servers as free during testing and contains testing-era allocation controls. That is not a guarantee of permanent pricing or availability. Server deletion requires a deliberate confirmation using the server's generated identifier. --- ## 30. Xunaro AI and coding/Codex tooling The codebase has a dedicated AI host and Xunaro AI connector/download routing, plus AI relay/question/intent pack endpoints. Studio also contains Codex-oriented project access/change workflows. These are permission-aware and can require review before submitted changes are applied. Xunaro's coding tools include a browser coding editor, examples and a runner/API surface on the main domain. AI/Codex access is separated from ordinary public project rendering so that creator content does not automatically gain privileged editing capabilities. --- ## 31. Messages, notifications and social platform features Global Xunaro includes: - direct messages/message threads; - message polling/typing endpoints; - notifications; - follows; - account profile navigation; - Community posts/categories; - news; - feedback; - reports; - moderation/owner review surfaces. Community is hosted on its own canonical subdomain while global accounts, reports and messages retain their canonical Xunaro hosts/routes. --- ## 32. Support, rules, reports and safety The main Support hub links to tutorials, reports, keyboard shortcuts, feedback, rules and safety settings. Reporting supports categories such as bug, general, project and account reports. Public report rate-limit storage exists so reporting endpoints cannot be used as unlimited write surfaces. Safety/settings pages handle account-level safety controls. Moderation and owner approval surfaces exist separately from creator Studio. --- ## 33. Xunaro short links (`xuna.ro`) `xuna.ro` is a fixed redirector. It does not accept arbitrary redirect destinations. Current shortcuts include: | Short form | Destination family | |---|---| | `/p/P...` | `project.xunaro.net/P.../` | | `/game/` | `game.xunaro.net//` | | `/app/` | `app.xunaro.net//` | | `/tool/` | `tool.xunaro.net//` | | `/store/` | `store.xunaro.net//` | | `/blog/` | `blog.xunaro.net//` | | `/study/` | `xunaro.net/study//` | | `/edu/` | `xunaro.net/education//` | | `/forum/` | `xunaro.net/forum//` | | `/sw/` | `xunaro.net/software//` | | `/art/` | `xunaro.net/art//` | | `/wiki/` | `xunaro.net/wiki//` | | `/music/` | `xunaro.net/music//` | | `/coffee/` | `xunaro.net/coffee//` | | `/pizza/` | `xunaro.net/pizza//` | | `/@username` | Xunaro account shorthand | The redirector rejects traversal/control-character style paths and keeps every shortcut inside its fixed Xunaro destination family. --- ## 34. External links Xunaro has an external-link/move flow rather than assuming every external destination is trusted. The codebase contains account-specific external URL permission storage and a `/move/` route. The design intention is to distinguish internal Xunaro navigation from leaving Xunaro, and to allow a user's explicit trust/permission choice to be remembered where supported. --- ## 35. Guest mode The source contains a guest-mode/guest-project system for trying project creation/editing without turning a guest session into an ordinary permanent project automatically. Guest projects have their own Studio guest routes and session-oriented state. Guest projects are not addressed as normal UUID project overviews and are kept in Studio-specific routes. --- ## 36. Backups and export Xunaro contains project backup/export code and project-specific backup storage. Project export logic gathers project data into portable exports while treating optional datasets defensively. The Status page also checks whether project-backup storage is available/writable without exposing private server details. --- ## 37. Status and operational checks `https://xunaro.net/status/` performs lightweight checks of core services such as: - website/PHP execution; - database connectivity; - uploads storage; - project backup storage. A JSON form is available through the status page's `format=json` option. The page deliberately reports service health without exposing private server configuration. --- ## 38. Mobile/responsive behavior Xunaro's mobile layout is an adaptation of the same visual system, not a completely different rounded/mobile-only design. Current responsive work includes: - wrapped/grid Studio tabs instead of mandatory horizontal tab scrolling; - two-up compact project cards on phones where practical; - one-up fallback on very narrow screens; - three project cards per row on the main Studio dashboard at desktop widths; - responsive project previews with the MORE action kept visible; - header/tab spacing derived from real rendered heights rather than hard-coded overlap assumptions; - mobile Work/Server controls sized to remain usable without squeezing buttons into unreadable widths. The visual language remains Xunaro's dark, mint-accented, mostly square-edged design. --- ## 39. Security model Xunaro's security model is based on separating first-party platform code from creator/project content and re-validating important actions on the server. Important patterns in the current source include: ### Session and CSRF protection Authenticated forms use server-side session identity and CSRF verification for state-changing Studio/account operations. ### Permission checks Project ownership/collaborator permissions are re-checked server-side. Hiding a button in the browser is not treated as authorization. ### Public/private identifier separation Public UUIDs are separate from internal numeric database IDs. API public IDs are separate from private backend keys. ### Host separation Authentication, accounts, Studio, project overview and product hosts have explicit canonical hosts and redirect rules. Product hosts do not become independent auth systems. ### Project sandboxing Creator custom HTML is isolated from Xunaro-owned UI through the project runtime/sandbox. Creator code gets scoped bridges/APIs rather than direct access to Xunaro's PHP session/database. ### Storage isolation Project browser storage is namespaced by project. Project files/pages are checked against project ownership and quota. ### Page-management capability signing Runtime page-management capabilities use server-side HMACs and source fingerprints, with short lifetimes for editor capabilities and source-bound validation for project-account capabilities. ### Rate limiting Sensitive/public APIs contain rate limits for operations such as runtime page mutation, public reports, login/backend use and other abuse-prone actions. ### Output escaping and route validation First-party PHP templates escape untrusted display values. Public routes validate identifier/path formats instead of concatenating arbitrary input into filesystem or redirect paths. ### Upload/file controls Public artwork and site/project files are served through validating handlers. Direct listing of internal directories is disabled. ### No secrets in public docs Private credentials must never be placed in this handbook, downloadable API guides, creator pages, client-side JavaScript, URLs, logs, or screenshots. --- ## 40. Apache/routing model Each major host has its own `.htaccess`/front-controller boundary. Key behavior: - directory listing is disabled; - sensitive config/database/backup-style file extensions are denied; - product hosts route unknown non-file URLs through one front controller rather than long rewrite chains; - `project.xunaro.net` sends non-file routes to the UUID-aware project controller; - canonical login/signup/recovery/account/settings/Studio links are redirected to the correct host; - shared Xunaro assets on satellite hosts resolve back to the primary asset host; - unknown main-domain API routes retain machine-readable API 404 behavior; - ordinary missing main-domain browser routes go through Xunaro's missing-route/404 behavior. This routing structure is specifically intended to avoid Apache rewrite loops that previously caused valid custom project URLs to fall into server-level 404/ErrorDocument failures. --- ## 41. Data model overview Xunaro uses multiple schema helpers/migrations rather than one giant static schema file. Major table families visible in the source include: ### Global accounts/auth `users`, pending signups, reset codes, follows, login tokens and account preference/safety-related data. ### Projects projects and project collaborators, pages, page versions/design, project verification/published URL records, templates/template uses, project transfers, backups, files/folders, web files/site roots, GitHub sources/files, analytics, and short redirects. ### Project-local users/social project users/accounts, sessions, saves, presence, friend requests/friendships, parties/invites/members, and runtime page ownership. ### Project interactive primitives public counters, rooms/players, arena queue/presence/scores/matches/limits. ### Advertising ad videos, placements, campaigns, impressions, views, clicks and balances. ### Login/Server APIs login applications, backend-key records, callback URLs, login requests/tokens/rate limits, API-project bindings, hosted server keys/files and backend-usage alerts. ### Servers project server/VPS records and associated host/controller state. The exact schema can evolve while the feature contract stays stable; callers should use Xunaro APIs rather than depending on internal table layouts. --- ## 42. Source tree map The current site source is split by deployment surface. ```text Site/ ├─ www/ primary xunaro.net document root and shared PHP includes/APIs ├─ studio/ studio.xunaro.net document root ├─ project/ project.xunaro.net UUID overview/runtime host ├─ account/ account.xunaro.net ├─ settings/ settings.xunaro.net ├─ game/ game.xunaro.net ├─ app/ app.xunaro.net ├─ tool/ tool.xunaro.net ├─ store/ store.xunaro.net ├─ blog/ blog.xunaro.net ├─ community/ community.xunaro.net ├─ ai/ ai.xunaro.net ├─ ro/ xuna.ro short-link router ├─ assets/ shared source assets mirrored/served by xunaro.net ├─ docs/ internal/developer documentation shipped with the source ├─ bin/ scheduled/CLI maintenance helpers ├─ uploads/ upload storage area (served through validating handlers) ├─ private/ private infrastructure material; never public web content └─ deploy/ deployment/support bundles; feature edits are made to source, not by modifying deploy artifacts ``` `www/includes/` contains shared platform modules such as auth/bootstrap, project verification, project accounts, templates, analytics, ads, backups, public IDs, project storage, site files/deployment, runtime pages, server/VPS helpers, project cards, collaboration, social and global interface components. --- ## 43. Main public API/endpoint families This is a route-family map, not a promise that every endpoint is open to anonymous callers. ```text /api/login/... Login API start/token/me /api/server/... Server/file backend routes /api/server/backend/... Hosted Server API operations /api/project-pages/ Secure runtime project page mutation/list /api/project-account/ Project-local account operations /api/project-counter/ Project public counters /api/project-room/ Project rooms /api/project-arena/ Arena/match primitives /api/project-ad/ Project ad runtime /api/project-analytics/ Project analytics event handling /api/recommendations/ Recommendation data on supported hosts /api/search/ Global search /api/site-visit/ Site visit accounting /api/signup-username/ Signup username checks ``` Several endpoints require signed-in sessions, project-specific tokens/capabilities, private backend authentication, bearer tokens, or project ownership. The existence of an endpoint does not mean anonymous write access. --- ## 44. Project route examples ### UUID overview ```text https://project.xunaro.net/PaB3dE5fG7hJ9kL2mN4pQ6rS8tU1vW3xY5z/ ``` ### Published Game ```text https://game.xunaro.net/publictransportmanager/ https://game.xunaro.net/publictransportmanager/play/ ``` ### Published Study project ```text https://xunaro.net/study/grade6-math/ https://xunaro.net/study/grade6-math/fractions/ ``` ### Find owning project by public URL ```text https://game.xunaro.net/uuid/publictransportmanager/play ``` The final example redirects to the UUID overview for the project that owns the Game URL `publictransportmanager`. --- ## 45. Search/discovery URL behavior Public search and project preview cards do **not** use the editable Studio slug as the public project overview identity. The stable overview destination is always the `P...` project UUID. The readable URL is a publishing address and may represent a Game/App/Tool/etc. site. This lets creators change publishing details without changing the project's canonical public identity. --- ## 46. Page/site fallback behavior For a published project: - if custom main content/site files exist and the selected design mode uses them, Xunaro serves the creator content; - if no custom main document is active, Xunaro can render the normal project overview/content mode in the selected published namespace; - nested page paths are routed through the same safe project page runtime; - project links are rewritten to stay inside the active verified/published namespace where appropriate; - invalid page paths are rejected rather than interpreted as arbitrary files. --- ## 47. Project design philosophy in the current source The platform design consistently follows several implementation principles: - creator content and Xunaro platform UI are separate; - permanent project identity is not tied to an editable readable URL; - dangerous actions must be server-authorized, not browser-authorized; - public URLs should fail predictably instead of guessing the wrong project; - project cards distinguish “open the site” from “learn more about the project”; - project content should remain usable on mobile without replacing the desktop visual language with an unrelated mobile theme; - new public projects must contain actual content before they receive public publishing privileges; - developer/API integrations distinguish public IDs from private credentials. --- ## 48. Known implementation notes / transitional areas Xunaro is actively developed, so some source surfaces contain transitional compatibility behavior. Examples in this snapshot include: - compatibility fallbacks for older projects whose published URL field may not yet be populated separately from their old internal slug; - old Studio/API route aliases retained for bookmarks; - older root paths redirected to newer canonical subdomains; - some Server API UI elements marked Coming Soon even though supporting backend code exists; - older projects can be migrated/backfilled with public UUIDs when first accessed; - old project status names normalize to the current public stages. Compatibility code should not be mistaken for the preferred new URL format. --- ## 49. Things that are deliberately not public knowledge A complete platform handbook should explain systems, not disclose secrets. The following values must remain outside this file: - database usernames/passwords/connection secrets; - application/session signing secrets; - password pepper/encryption keys; - private Login API backend keys; - bearer/access tokens; - recovery/signup codes; - private server/VPS controller credentials; - TLS/private keys; - SSH credentials; - private infrastructure addresses when not meant to be public; - user passwords; - private project/account data; - moderation-only or security-abuse data that would weaken protections if published. If any of those values ever appear in a public copy of this handbook, that is a security bug, not “more complete documentation.” --- ## 50. Quick glossary **Account UUID** — `U` + 14 alphanumeric characters. Public stable account identifier. **Project UUID** — `P` + 34 alphanumeric characters. Canonical normal-project public identity. **API UUID** — `API` + 7 alphanumeric characters. Public API/server application identifier, not a secret. **Studio slug** — Internal/readable project-management slug used in Studio routes. Not the canonical public UUID. **Published URL name** — Readable name chosen for a public publishing destination such as Game/App/Study. **Project overview** — Xunaro-owned page at `project.xunaro.net/P.../`. **Project site** — Creator content published at a Game/App/Tool/Store/Blog/path-based destination. **MORE →** — Opens the project overview from a project preview card. **Main card click** — Opens the published project site when one exists; otherwise opens the overview. **Project-local account** — Account stored inside one project for that project's users. **Xunaro Connect** — Flow that connects/signs a project experience in using a global Xunaro identity. **Project template** — Reusable project content/configuration, separate from an ordinary project. **Visibility** — Private, Unlisted or Public project exposure plus associated analytics controls. **Runtime page** — Page created/deleted through the secure project page-management runtime rather than only through Studio UI. --- ## 51. If you are building something on Xunaro Use this mental model: 1. Create/manage the project in Studio. 2. Treat its `P...` UUID as its permanent public identity. 3. Build the project content in Main/Pages/Files. 4. Complete the publishing checklist. 5. Choose the project kind and readable public URL if you want a dedicated site address. 6. Link people to the published site when you want them to use the project. 7. Link people to `project.xunaro.net/P.../` when you want them to see the Xunaro project overview. 8. Use project runtime APIs for project-scoped interactive features; never try to access Xunaro's internal database directly. 9. Use public API IDs in clients, but keep every private backend key/secret on a trusted backend. 10. Use Studio permissions/collaboration instead of sharing credentials. --- ## 52. Final one-paragraph model Xunaro is a multi-surface creator platform where a global Xunaro account owns/collaborates on projects in Studio; each normal project receives an immutable-style `P` + 34-character public UUID for its Xunaro overview, while optional readable publishing names place the actual creator site into a Game/App/Tool/Store/Blog or path-based namespace; project pages run through a sandboxed, project-scoped runtime with storage/accounts/multiplayer/social/page APIs; discovery cards open the site while MORE opens the UUID overview; Studio controls content, team, planning, visibility, APIs and project servers; public IDs are never private keys; server-side permission, CSRF, HMAC/capability, route validation, rate limiting and host separation protect privileged actions; global messaging/community/support/moderation surround the creator system; and `xuna.ro` provides fixed safe shortcuts back into those canonical Xunaro surfaces. --- ## 53. Keeping this handbook correct This file describes the source snapshot dated at the top. When routing, UUID formats, publishing rules, Studio navigation, API contracts, project runtimes, or supported project kinds change, **update this handbook in the same release**. The goal of `xunaro.net/info` is that one downloaded `XUNARO.md` is enough to understand the whole public platform without reading the PHP source.