docs: add project documentation

docs/ADDING_LANGUAGE.md

@@ -0,0 +1,120 @@
+# 🌍 Adding a Language
+
+## 1. Create the File
+
+```bash
+cp lua/langs/_template.lua lua/langs/elixir.lua
+nvim lua/langs/elixir.lua
+```
+
+## 2. Minimal Structure
+
+```lua
+---@file lua/langs/elixir.lua
+---@description Elixir language support
+---@module "langs.elixir"
+
+local settings_ok, settings = pcall(require, "core.settings")
+if settings_ok and not settings:is_language_enabled("elixir") then return {} end
+
+return {
+    -- Treesitter parser
+    {
+        "nvim-treesitter/nvim-treesitter",
+        opts = function(_, opts)
+            vim.list_extend(opts.ensure_installed, { "elixir", "heex", "eex" })
+        end,
+    },
+
+    -- LSP
+    {
+        "neovim/nvim-lspconfig",
+        opts = {
+            servers = {
+                elixirls = {},
+            },
+        },
+    },
+
+    -- Formatter
+    {
+        "stevearc/conform.nvim",
+        opts = {
+            formatters_by_ft = {
+                elixir = { "mix" },
+            },
+        },
+    },
+
+    -- Linter (optional)
+    {
+        "mfussenegger/nvim-lint",
+        opts = {
+            linters_by_ft = {
+                elixir = { "credo" },
+            },
+        },
+    },
+}
+```
+
+## 3. Enable in settings.lua
+
+```lua
+-- settings.lua or users/<name>/settings.lua
+languages = {
+    enabled = { "lua", "python", "elixir" },
+},
+```
+
+## 4. Add the Runtime (if applicable)
+
+In `lua/core/platform.lua` → `RUNTIME_EXECUTABLES`:
+
+```lua
+elixir = "elixir",
+```
+
+## 5. Add Version Detection in Lualine
+
+In `lua/plugins/ui/lualine.lua`:
+```lua
+-- FT_TO_RUNTIME:
+elixir = "elixir",
+
+-- VERSION_ARGS:
+elixir = { args = "--version", pattern = "Elixir%s+(%S+)" },
+```
+
+## 6. Mason — LSP/Formatter/Linter
+
+Verify availability:
+
+```vim
+:Mason
+```
+
+Search for: `elixir-ls`, `credo`
+
+## 7. Testing
+
+```bash
+nvim test.ex
+:LspInfo          # LSP attached?
+:TSInstall elixir # Parser installed?
+:ConformInfo      # Formatter configured?
+```
+
+## Checklist
+
+```
+□ lua/langs/<lang>.lua created
+□ Treesitter parser added
+□ LSP server configured
+□ Formatter configured
+□ Linter configured (optional)
+□ Runtime added to platform.lua (optional)
+□ Version added to lualine.lua (optional)
+□ Enabled in settings.lua
+□ Tested with a real file
+```

docs/ADDING_PLUGIN.md

@@ -0,0 +1,130 @@
+# 🔌 Adding a Plugin
+
+## 1. Choose a Category
+
+| Folder | Content |
+| --- | --- |
+| `plugins/ai/` | AI assistants |
+| `plugins/code/` | Completion, LSP, Treesitter, formatting |
+| `plugins/editor/` | Navigation, files, search |
+| `plugins/ui/` | Statusline, tabline, notifications |
+| `plugins/tools/` | Terminal, Git, debugging |
+| `plugins/misc/` | Everything else |
+
+## 2. Create the File
+
+```bash
+nvim lua/plugins/editor/my-plugin.lua
+```
+
+## 3. Standard Structure
+
+```lua
+---@file lua/plugins/editor/my-plugin.lua
+---@description My Plugin — short description
+---@module "plugins.editor.my-plugin"
+
+-- Guard: allows disabling from settings.lua
+local settings_ok, settings = pcall(require, "core.settings")
+if settings_ok and not settings:is_plugin_enabled("my-plugin") then return {} end
+
+return {
+    "author/my-plugin.nvim",
+
+    -- Lazy loading (choose ONE trigger):
+    event = "VeryLazy",              -- On first idle
+    -- cmd = "MyPluginCommand",      -- On first command execution
+    -- ft = { "lua", "python" },     -- On first filetype match
+    -- keys = { "<leader>mp" },      -- On first keymap usage
+
+    dependencies = {
+        "nvim-lua/plenary.nvim",     -- If required
+    },
+
+    opts = {
+        -- Configuration passed to setup()
+        option1 = true,
+        option2 = "value",
+    },
+
+    -- OR config = function() for more control:
+    -- config = function(_, opts)
+    --     require("my-plugin").setup(opts)
+    --     -- Additional code here
+    -- end,
+}
+```
+
+## 4. Make it Togglable
+
+In `lua/core/settings.lua`, add the default value:
+
+```lua
+plugins = {
+    ["my-plugin"] = true,  -- enabled by default
+},
+```
+
+## 5. Add Keymaps
+
+```lua
+return {
+    "author/my-plugin.nvim",
+    keys = {
+        { "<leader>mp", "<cmd>MyPlugin<cr>", desc = "My Plugin" },
+        { "<leader>mt", "<cmd>MyPluginToggle<cr>", desc = "Toggle My Plugin" },
+    },
+    -- ...
+}
+```
+
+## 6. Testing
+
+```bash
+nvim
+:Lazy                    # Verify the plugin is listed
+:Lazy load my-plugin     # Force loading
+:checkhealth my-plugin   # If the plugin has a healthcheck
+```
+
+## Design Patterns
+
+### Pattern: pcall on external requires
+
+```lua
+config = function(_, opts)
+    local ok, plugin = pcall(require, "my-plugin")
+    if not ok then return end
+    plugin.setup(opts)
+end,
+```
+
+### Pattern: core.icons integration
+
+```lua
+local icons_ok, icons = pcall(require, "core.icons")
+local icon = icons_ok and icons.ui.MyIcon or "fallback"
+```
+
+### Pattern: core.platform integration
+
+```lua
+local platform_ok, platform = pcall(require, "core.platform")
+if platform_ok and platform.is_ssh then
+    -- Reduce features over SSH
+    opts.animations = false
+end
+```
+
+## Checklist
+
+```
+□ File created in the correct category
+□ Settings guard added
+□ Appropriate lazy trigger (event/cmd/ft/keys)
+□ Dependencies listed
+□ Default added to core/settings.lua
+□ Keymaps documented (desc =)
+□ Tested: :Lazy, loading, functionality
+□ stylua lua/ executed
+```

docs/ARCHITECTURE.md

@@ -0,0 +1,108 @@
+# 🏗️ Architecture
+
+## Overview
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                      NvimEnterprise Stack                        │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────┐   ┌──────────┐  ┌──────────┐  ┌─────────────────┐  │
+│  │  Users   │   │  Langs   │  │ Plugins  │  │       AI        │  │
+│  │Namespace │   │ Modules  │  │ Registry │  │    Providers    │  │
+│  └────┬─────┘   └────┬─────┘  └────┬─────┘  └──────┬──────────┘  │
+│       │              │             │               │             │
+│  ┌────▼──────────────▼─────────────▼───────────────▼──────────┐  │
+│  │        Config Layer (Settings · Plugin · Colorscheme)      │  │
+│  └────────────────────────────┬───────────────────────────────┘  │
+│                               │                                  │
+│  ┌────────────────────────────▼───────────────────────────────┐  │
+│  │         Core Engine (OOP / Class System / Lua)             │  │
+│  │  bootstrap · class · settings · platform · security · log  │  │
+│  │  version · icons · health · utils · secrets                │  │
+│  └────────────────────────────┬───────────────────────────────┘  │
+│                               │                                  │
+│  ┌────────────────────────────▼───────────────────────────────┐  │
+│  │               Neovim 0.10+ Runtime                         │  │
+│  └────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Boot Pipeline (init.lua)
+
+```
+Phase 1 — Version Guard        Neovim >= 0.10.0?
+Phase 2 — Disable Built-ins    ~15 built-in plugins disabled
+Phase 3 — Cache References     Localize vim.uv, stdpath(), etc.
+Phase 4 — Load Version         dofile(core/version.lua)
+Phase 5 — Global Namespace     _G.NvimConfig = { ... }
+Phase 6 — Secrets              .env sync + async loading
+Phase 7 — Bootstrap Core       require("core")
+```
+
+## Directory Structure
+
+```
+lua/
+├── core/            Framework engine (low-level)
+│   ├── class.lua      OOP: inheritance, mixins, types
+│   ├── platform.lua   Detection: OS, SSH, Docker, WSL, runtimes
+│   ├── settings.lua   Defaults + schema
+│   ├── version.lua    SemVer (Single Source of Truth)
+│   ├── secrets.lua    Secure .env loader
+│   ├── security.lua   Sandbox, path validation
+│   ├── bootstrap.lua  Deterministic init sequence
+│   ├── icons.lua      Centralized icon registry
+│   ├── logger.lua     Structured logging
+│   ├── health.lua     :checkhealth integration
+│   └── utils.lua      Shared utilities
+│
+├── config/          Configuration layer
+│   ├── settings_manager.lua    Deep-merge settings
+│   ├── plugin_manager.lua      Per-plugin toggle logic
+│   ├── colorscheme_manager.lua Runtime theme switching
+│   ├── commands.lua            Enterprise commands
+│   └── lazy.lua                Lazy.nvim bootstrap
+│
+├── langs/           1 file = 1 language
+│   ├── _template.lua    Template for new languages
+│   ├── lua.lua          Treesitter + LSP + formatter
+│   ├── python.lua       ...
+│   └── ...              45+ languages
+│
+├── plugins/         Specs by category
+│   ├── ai/            Copilot, Avante, CodeCompanion
+│   ├── code/          CMP, Conform, Treesitter, LSP
+│   ├── editor/        Telescope, Neo-tree, Flash
+│   ├── ui/            Lualine, Bufferline, Noice
+│   ├── tools/         LazyGit, ToggleTerm
+│   └── misc/          StartupTime, Wakatime
+│
+└── users/           Isolated namespaces
+    ├── namespace.lua      Isolation engine
+    ├── user_manager.lua    User CRUD
+    ├── default/           Default profile
+    ├── jane/              Example profile
+    └── john/              Example profile
+```
+
+## Design Principles
+
+| Principle | Implementation |
+| --- | --- |
+| **Single Responsibility** | Each file has one dedicated role |
+| **Defensive Programming** | `pcall()` on all external access/requires |
+| **Single Source of Truth** | `version.lua`, `settings.lua`, `icons.lua` |
+| **Lazy Loading** | Plugins loaded via event/cmd/ft/keys |
+| **Caching** | Costly data cached (versions, env, hostname) |
+| **Fallbacks** | Every module provides default values |
+
+## Singletons & Access Patterns
+
+| Module | Pattern | Access |
+| --- | --- | --- |
+| `platform` | Singleton via `get_instance()` | `require("core.platform")` |
+| `settings` | Singleton via `Class:extend()` | `require("core.settings")` |
+| `version` | Table module (non-OOP) | `require("core.version")` |
+| `icons` | Table module (non-OOP) | `require("core.icons")` |
+