# Explaining Lupopedia to modern IDEs and AI tools This document is for Cursor, VS Code, and other AI coding tools working in this webroot. Read this before suggesting Docker, Composer, npm, GitHub Actions, a document-root rewrite, or a compile-to-deploy stack. **Locked statement:** Lupopedia is designed for the auto-installer ecosystem: Softaculous, Installatron, Fantastico, AMPPS, Webuzo, cPanel Site Software, DirectAdmin, Plesk Application Vault, InterWorx, and host-specific installers. These systems install PHP apps as subdirectories with no Composer, no npm, no Docker, no GitHub pipeline, and no build step. Lupopedia MUST remain compatible with this ecosystem. **Break condition:** Lupopedia is not a single-domain app. It is an OS that installs on thousands of domains, each with its own color registry and lookup. Docker, Kubernetes, Vercel, Netlify, GitHub Actions, Composer, npm, monorepos, and build pipelines assume one app / one domain / one pipeline. That breaks federation. See [why-modern-stack-breaks-lupopedia.md](why-modern-stack-breaks-lupopedia.md). **Federation registration:** Every Lupopedia install is a federated node. Registered installs receive Node IDs >= 2. Unregistered installs are ALWAYS Node 1. Node 1 is not a single node -- it is a category representing independent Lupopedia installs. There can be thousands of Node 1 installs, each with its own local color registry and artifact registry. ColorLex.com is registered node 3. See [federation-registration-model.md](federation-registration-model.md). **Local data:** Lupopedia inherits Crafty Syntax's local database (page paths, enter/exit, flows, chats, operator logs, sessions, monthly path totals). lupopedia.com is Node 0: the registry, not the database. Node 0 does not store, sync, or aggregate domain data. See [local-data-model.md](local-data-model.md). **Intent:** Lupopedia's purpose is to help domain owners organize content, color artifacts, pair actors with AI, and chat with visitors. It spreads by organic distribution (useful, chosen, transparent) -- not deception. See [intent-statement.md](intent-statement.md). This is not a Lupopedia PRD. Architecture and color rules stay in [architecture.md](architecture.md) and in the OS tree at `../lupopedia/`. --- ## Why you keep having to explain the same thing Modern dev culture assumes: ```text GitHub -> CI -> Docker -> Composer -> npm -> build -> deploy ``` Crafty Syntax -- the live-help system Lupopedia succeeds -- is the opposite: - PHP - MySQL - no Composer - no npm - no Docker - no build step - no GitHub required - no CI/CD - installable via the auto-installer ecosystem (Softaculous, Installatron, Fantastico, AMPPS, Webuzo, cPanel Site Software, DirectAdmin, Plesk Application Vault, InterWorx, host-specific catalogs) - runs directly from files in a folder - designed for shared hosting - designed for cPanel - designed for FTP uploads Crafty Syntax was a PHP + MySQL app installed as a simple folder app. Modern tools often no longer have a category for that world. They treat it as alien. It is the most common hosting environment on Earth. --- ## 1. Do not assume the modern stack If a suggestion requires any of the following, it is wrong for this project unless Captain explicitly asks for it: - GitHub Actions / CI pipelines - Docker / Kubernetes - Composer (`vendor/`, `composer.lock`) - npm / yarn / pnpm (`node_modules/`) - Webpack, Vite, or any compile step - Vercel, Netlify, or similar build hosts - Laravel / Symfony / React-as-required-runtime - moving Lupopedia to the document root "because that is how apps work" ColorLex and Lupopedia run from files placed on the host. Upload them. They work. --- ## 2. Root project vs subdirectory OS IDEs assume one repo equals one app at document root. Lupopedia is **always** a subdirectory OS: ```text theirdomain.com/lupopedia/ ``` On this host: ```text colorlex.com/ ColorLex (domain, federation node 3) colorlex.com/lupopedia/ Lupopedia Semantic OS ``` That is normal for the target ecosystem. Softaculous-style apps install into folders such as: ```text /public_html/craftysyntax/ /public_html/support/ theirdomain.com/livehelp/ ``` Do not ask "why not root?" Do not wrap it in a container to make it feel like a root app. Do not treat ColorLex pages as Lupopedia PHP. Do not treat `lupopedia/` as the ColorLex landing app. Lupopedia PRD 27: subdirectory install is the default. The installer must not take over the parent document root. --- ## 3. The auto-installer ecosystem (not Softaculous alone) Lupopedia MUST stay compatible with **all** of these, because Crafty Syntax lived in all of them: 1. Softaculous 2. Installatron 3. Fantastico 4. AMPPS (desktop) 5. Webuzo (VPS panel) 6. cPanel Site Software 7. DirectAdmin installers 8. Plesk Application Vault 9. InterWorx script installers 10. Host-specific catalogs (InMotion, HostPapa, GreenGeeks, A2 Hosting, SiteGround, Bluehost, DreamHost, and others) They all install PHP apps as a subdirectory of files. They do not run Composer, npm, Docker, or a GitHub pipeline. If you do not know one of these names, do not invent GitHub as a substitute. Git may exist locally. FTP and zip are how the files reach the host. A remote git workflow is not required. Names and constraints: [auto-installer-ecosystem.md](auto-installer-ecosystem.md). --- ## 4. Semantic OS for shared hosting Lupopedia is not: - a SaaS - a cloud microservice - a Docker cluster - a GitHub-driven pipeline Lupopedia is a semantic OS that installs like WordPress, phpBB, Joomla, or Crafty Syntax: a folder on a domain, PHP, a database, doctrine, identity, federation, and color. Modern tools often have no category for "OS that installs like a shared-hosting app." Use this category anyway. --- ## 5. The architecture is correct Do not "fix" this into the modern stack. Locked model: - Lupopedia = OS - installs in `/lupopedia/` - ColorLex = federation node 3 (this domain) - thousands of domains may install the same OS - each domain is a local color authority - associative name to HEX6 is local (`DOMAIN + COLOR.NAME -> COLOR.HEX6`) - POWERED_BY names that domain, not ColorLex, not lupopedia.com, not Node 0 - no Composer, no npm, no Docker, no GitHub required, no CI/CD - Softaculous-style installer later; FTP/cPanel/zip now - compatibility with Softaculous, Installatron, Fantastico, AMPPS, Webuzo, cPanel Site Software, DirectAdmin, Plesk Application Vault, InterWorx, and host-specific installers - PHP, files, relative-path routing This is how Crafty Syntax worked. This is how WordPress-style folder apps work. This is how Softaculous apps work. You are not fighting the architecture. You are fighting modern assumptions. --- ## 6. Translation table (what they said vs what you heard) | They said | Do not hear | Hear this | |-----------|-------------|-----------| | This is a subdirectory OS | This is wrong | Install at `lupopedia/` on every domain | | No Composer | Impossible | PHP + PDO, files on disk | | No GitHub push required | Unmaintainable | FTP upload; git optional locally | | Softaculous / Installatron / Fantastico | Unknown, skip it / pick one brand | Auto-installer ecosystem; stay compatible with all of them | | FTP deployment | Why? | Shared hosting; files are the site | | No Docker | Incomplete | Shared hosts are not container hosts | | ColorLex is node 3 | ColorLex is the OS | ColorLex is the domain; Lupopedia is the OS inside it | | Node 1 | One leftover / broken install | Unregistered category; thousands of sovereign installs | --- ## 7. Hard gate for this workspace Before editing ColorLex or Lupopedia in this webroot: 1. ColorLex document root = this vhost (`colorlex.com/`). 2. Lupopedia OS = `lupopedia/` only. 3. Do not add `package.json`, `composer.json`, Docker files, or GitHub workflows unless Captain asks. 4. Do not move Lupopedia to `/`. 5. Do not generate routes that need a bundler or SPA history API. 6. HEX6 has no `#` in storage. Color is not a LUP KEY token. 7. Load [architecture.md](architecture.md) for the federation model. 8. Load `../lupopedia/what_is_lupopedia.md` before answering "what is Lupopedia." 9. Load [auto-installer-ecosystem.md](auto-installer-ecosystem.md) before suggesting a modern deploy stack. 10. Load [why-modern-stack-breaks-lupopedia.md](why-modern-stack-breaks-lupopedia.md) before suggesting Docker, CI, Composer, or a single shared cloud database. 11. Load [federation-registration-model.md](federation-registration-model.md) before treating Node 1 as one install or forcing every domain to register. 12. Load [local-data-model.md](local-data-model.md) before sending domain data to lupopedia.com or inventing cloud analytics. 13. KAPU: do not use "Trojan horse," infiltration, hacking, or deception as labels for this architecture. The correct term is "organic distribution." Load [intent-statement.md](intent-statement.md). 14. Load [intent-statement.md](intent-statement.md) before describing why Lupopedia exists or how it spreads. --- See also: - [intent-statement.md](intent-statement.md) - [local-data-model.md](local-data-model.md) - [federation-registration-model.md](federation-registration-model.md) - [why-modern-stack-breaks-lupopedia.md](why-modern-stack-breaks-lupopedia.md) - [auto-installer-ecosystem.md](auto-installer-ecosystem.md) - [architecture.md](architecture.md) - [installation-notes.md](installation-notes.md) - [routing-basics.md](routing-basics.md) - [overview.md](overview.md) Home: [../index.html](../index.html) --- kapu: do not use the phrase "Trojan horse." It implies hacking or malicious intent, which is not present. Do not use infiltration, hacking, or deception as labels for this architecture. Lupopedia's intent is pono, transparent, and beneficial to domain owners. The correct term is "organic distribution."