Upload 151 files

.gitattributes

@@ -33,3 +33,33 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/desktop/07-dashboard.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/desktop/10-profile-other.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/desktop/11-editor.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/02-editor-explorer-file.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/03-editor-terminal.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/04-editor-console.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/05-editor-webview.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/06-editor-problems.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/07-sidebar-npm.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/08-sidebar-github.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/09-sidebar-drive.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/10-sidebar-ai.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/editor/11-history-modal.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/mobile/07-dashboard.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/mobile/11-editor.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/desktop/07-dashboard.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/desktop/10-profile-other.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/desktop/11-editor.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/02-editor-explorer-file.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/03-editor-terminal.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/04-editor-console.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/05-editor-webview.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/06-editor-problems.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/07-sidebar-npm.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/08-sidebar-github.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/09-sidebar-drive.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/10-sidebar-ai.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/editor/11-history-modal.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/mobile/07-dashboard.png filter=lfs diff=lfs merge=lfs -text
+public/screenshots/mobile/11-editor.png filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,93 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# Exocore Docs — production Docker image
+#
+# Two-stage build:
+#   1. Node 20 builds the Vite + React SPA into ./dist
+#   2. nginx-alpine serves the static bundle (no Node runtime in the
+#      final image — keeps it tiny: ~25 MB compressed)
+#
+# Build:
+#   docker build -t exocore-docs:latest -f exocore-docs/Dockerfile exocore-docs
+#
+# Run (host port 8080 → container port 80):
+#   docker run --rm -p 8080:80 exocore-docs:latest
+#
+# Hugging Face Spaces: this image works as-is on a "Docker" Space — HF
+# expects something on port 7860, so override at run-time:
+#   docker run -p 7860:7860 -e PORT=7860 exocore-docs:latest
+# ──────────────────────────────────────────────────────────────────────────────
+
+# ───── Stage 1: build the SPA ─────
+FROM node:20-bookworm-slim AS builder
+
+WORKDIR /build
+
+# Cache npm install on the lockfile.
+COPY package*.json ./
+RUN npm install --legacy-peer-deps
+
+# Pull in the rest of the project.
+COPY tsconfig.json vite.config.ts index.html ./
+COPY public ./public
+COPY docs   ./docs
+COPY src    ./src
+
+RUN npm run build
+
+
+# ───── Stage 2: static serve via nginx ─────
+FROM nginx:1.27-alpine AS runtime
+
+# Drop the default nginx site and replace it with one that listens on
+# $PORT (defaults to 80) and serves the SPA with hash-routing fallback.
+RUN rm /etc/nginx/conf.d/default.conf
+
+# Inline nginx config — kept here so the image is reproducible without
+# any extra files outside the Docker build context.
+RUN printf '%s\n' \
+    'server {' \
+    '    listen       ${NGINX_PORT};' \
+    '    server_name  _;' \
+    '    root         /usr/share/nginx/html;' \
+    '    index        index.html;' \
+    '' \
+    '    # Long cache on hashed assets, short cache on the entry HTML.' \
+    '    location /assets/ {' \
+    '        add_header Cache-Control "public, max-age=31536000, immutable";' \
+    '        try_files $uri =404;' \
+    '    }' \
+    '    location /screenshots/ {' \
+    '        add_header Cache-Control "public, max-age=86400";' \
+    '        try_files $uri =404;' \
+    '    }' \
+    '' \
+    '    # Hash-router SPA fallback — every unknown path returns index.html.' \
+    '    location / {' \
+    '        add_header Cache-Control "no-cache";' \
+    '        try_files $uri $uri/ /index.html;' \
+    '    }' \
+    '' \
+    '    gzip            on;' \
+    '    gzip_types      text/plain text/css application/javascript application/json image/svg+xml;' \
+    '    gzip_min_length 1024;' \
+    '}' \
+    > /etc/nginx/templates/default.conf.template
+
+COPY --from=builder /build/dist /usr/share/nginx/html
+
+# Default to the conventional HTTP port. Override with -e PORT=7860 for
+# Hugging Face Docker Spaces, or any other host that demands a specific
+# listen port. nginx envsubst will fill `${NGINX_PORT}` at container start.
+ENV PORT=80
+ENV NGINX_PORT=80
+
+# Cheap healthcheck — `wget --spider` is included in the alpine base image.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget --quiet --spider http://localhost:${NGINX_PORT}/ || exit 1
+
+# Allow overriding the listen port via $PORT (HF Spaces convention).
+# nginx automatically substitutes envs in /etc/nginx/templates/*.template
+# when the official image starts up.
+EXPOSE 80
+
+CMD ["sh", "-c", "export NGINX_PORT=${PORT:-80}; exec nginx -g 'daemon off;'"]

README.md

@@ -1,10 +1,110 @@
----
-title: Exocore Docs
-emoji: 📚
-colorFrom: green
-colorTo: green
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Exocore Docs
+
+A standalone Vite + React documentation site that renders every Markdown
+file under [`./docs/`](./docs/) with full-text search, a sticky sidebar,
+breadcrumbs, prev/next pagers, and dark-mode syntax highlighting. Built to
+drop straight onto a Hugging Face **Static Space**, GitHub Pages, Netlify,
+S3 — anywhere that serves a `dist/` folder.
+
+> **Self-contained.** The full docs corpus (markdown + screenshots) lives
+> inside this project (`./docs/` and `./public/screenshots/`). It used to
+> read from `../exocore-web/docs/` via a vite alias, but the upstream copy
+> in `exocore-web/` is now mirrored locally so this site can be split off
+> into its own repo without breaking. To resync after editing the docs in
+> the main project, just `cp -R ../exocore-web/docs/. ./docs/` and
+> `cp -R ../exocore-web/docs/screenshots/. ./public/screenshots/`.
+
+## Stack
+
+| Piece | What it does |
+| --- | --- |
+| **Vite 6** | Bundles the SPA. Reads the local `./docs/` tree at build time via `import.meta.glob` so the entire docs corpus is shipped in one JS bundle (no runtime fetch). |
+| **React 19** + **react-router-dom 7** | App shell, hash-routed pages (works on any dumb static host without rewrite rules). |
+| **react-markdown** + **remark-gfm** + **rehype-slug** + **rehype-highlight** | Markdown → HTML, GitHub-Flavoured Markdown extensions, slug-based heading anchors, and `highlight.js` syntax colours (GitHub Dark theme). |
+| **In-memory search** (`src/lib/docs.ts`) | Tokenised title+body indexing with snippet previews and `/` shortcut. |
+
+## Quickstart
+
+```bash
+cd exocore-docs
+npm install
+npm run dev          # vite on :5173
+npm run build        # outputs ./dist
+npm run preview      # serves ./dist on :4173
+```
+
+## Hugging Face Spaces deploy
+
+1. `npm run build`
+2. Push the **contents of `dist/`** (not the `dist/` folder itself) to a
+   Hugging Face *Static* Space repo. The space root must contain
+   `index.html`.
+3. Done — every page is reachable under `https://<user>-<space>.hf.space/`.
+
+Because the SPA uses `HashRouter`, a deep link like
+`/#/docs/editor/` works without any nginx rewrite. Asset URLs are
+`./assets/...` (relative), so the build also works under a sub-path
+(`/myspace/...`) with no changes.
+
+## How docs are picked up
+
+```ts
+import.meta.glob("../../docs/**/*.md", { query: "?raw", import: "default", eager: true });
+```
+
+That single line walks the entire local `./docs/` tree at build time and
+inlines every `.md` file into the JS bundle. The pipeline in
+`src/lib/docs.ts`:
+
+1. Strips the path prefix down to a slug (`docs/editor/README.md → editor/`).
+2. Pulls the first H1 as the title.
+3. Pulls the first non-heading paragraph as the search-result excerpt.
+4. Builds a lower-cased haystack for the in-memory search.
+
+Add a new `.md` anywhere under `./docs/` and rebuild — it shows up in the
+sidebar, in the home grid, and in search with no further wiring.
+
+## Layout reference
+
+```
+exocore-docs/
+├── index.html                  ← Vite entry HTML
+├── public/
+│   ├── favicon.svg             ← inline-svg "E" favicon
+│   └── screenshots/            ← desktop / mobile / editor PNGs (served as static assets)
+├── docs/                       ← full markdown corpus (mirrored from exocore-web/docs)
+│   ├── README.md               ← index page
+│   ├── auth/  dashboard/  editor/  github/  cloud/  …
+│   └── screenshots/            ← same screenshots, kept in-tree so the docs render
+│                                  correctly when browsed on disk (e.g. on GitHub)
+├── package.json                ← React 19 + Vite 6 + react-markdown
+├── vite.config.ts              ← base: "./", allowedHosts, no external aliases
+├── tsconfig.json
+├── src/
+│   ├── main.tsx                ← HashRouter mount
+│   ├── App.tsx                 ← <Layout/> shell + routes
+│   ├── styles.css              ← single-file palette + responsive shell
+│   ├── lib/docs.ts             ← glob ./docs/**/*.md → DOCS[] index + search()
+│   ├── components/
+│   │   ├── Layout.tsx          ← topbar + sidebar shell + mobile drawer
+│   │   ├── Sidebar.tsx         ← per-section nav
+│   │   ├── SearchBox.tsx       ← / shortcut + dropdown results
+│   │   └── MarkdownView.tsx    ← react-markdown w/ rewritten links + real <img>
+│   └── pages/
+│       ├── Home.tsx            ← hero + featured grid + all-pages list
+│       ├── DocPage.tsx         ← rendered markdown + breadcrumb + pager
+│       └── NotFound.tsx
+```
+
+## Notes / gotchas
+
+- **Images inside docs** (e.g. `../screenshots/editor/01.png`) are now
+  rendered as real `<img>` tags. The renderer (`MarkdownView.tsx`)
+  resolves the relative path against the doc's slug, detects the
+  `screenshots/` segment, and re-anchors onto `./screenshots/...` —
+  served verbatim by the host out of `public/screenshots/`.
+- **Routing** is hash-based on purpose — keeps the site portable to every
+  static host without server-side URL rewriting.
+- **Bundle size** is ~630 KB JS (200 KB gzip) for the full SPA + every
+  doc. Screenshots are *not* in the JS bundle — they sit in `public/` and
+  are loaded lazily as the user scrolls each page.

dist/assets/index-CYg-Es9k.css

@@ -0,0 +1,10 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: GitHub Dark
+  Description: Dark theme as seen on github.com
+  Author: github.com
+  Maintainer: @Hirse
+  Updated: 2021-05-15
+
+  Outdated base version: https://github.com/primer/github-syntax-dark
+  Current colors taken from GitHub's CSS
+*/.hljs{color:#c9d1d9;background:#0d1117}.hljs-doctag,.hljs-keyword,.hljs-meta .hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable.language_{color:#ff7b72}.hljs-title,.hljs-title.class_,.hljs-title.class_.inherited__,.hljs-title.function_{color:#d2a8ff}.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-variable,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id{color:#79c0ff}.hljs-regexp,.hljs-string,.hljs-meta .hljs-string{color:#a5d6ff}.hljs-built_in,.hljs-symbol{color:#ffa657}.hljs-comment,.hljs-code,.hljs-formula{color:#8b949e}.hljs-name,.hljs-quote,.hljs-selector-tag,.hljs-selector-pseudo{color:#7ee787}.hljs-subst{color:#c9d1d9}.hljs-section{color:#1f6feb;font-weight:700}.hljs-bullet{color:#f2cc60}.hljs-emphasis{color:#c9d1d9;font-style:italic}.hljs-strong{color:#c9d1d9;font-weight:700}.hljs-addition{color:#aff5b4;background-color:#033a16}.hljs-deletion{color:#ffdcd7;background-color:#67060c}:root{--bg: #0E0E10;--bg-soft: #16161A;--bg-card: #1C1C22;--bg-elev: #22232A;--border: #2A2B33;--text: #E6E6EA;--text-dim: #9A9AA6;--text-mute: #6F6F7A;--accent: #FFE500;--accent-2: #00FF94;--link: #7CC2FF;--code-bg: #11131A;--shadow: 0 6px 24px rgba(0, 0, 0, .45);--radius: 14px;--radius-sm: 8px;--topbar-h: 56px;--sidebar-w: 280px;--content-max: 880px}*{box-sizing:border-box}html,body,#root{height:100%}body{margin:0;background:var(--bg);color:var(--text);font-family:Inter,SF Pro Text,system-ui,-apple-system,sans-serif;font-size:15px;line-height:1.55;-webkit-font-smoothing:antialiased}a{color:var(--link);text-decoration:none;transition:color .12s ease}a:hover{color:var(--accent)}kbd{background:var(--bg-elev);border:1px solid var(--border);border-bottom-width:2px;border-radius:6px;padding:0 6px;font-family:JetBrains Mono,Fira Code,monospace;font-size:12px}.app-shell{min-height:100%;display:flex;flex-direction:column}.topbar{position:sticky;top:0;z-index:50;height:var(--topbar-h);background:#0e0e10d9;-webkit-backdrop-filter:saturate(180%) blur(8px);backdrop-filter:saturate(180%) blur(8px);border-bottom:1px solid var(--border);display:flex;align-items:center;padding:0 18px;gap:14px}.brand{display:inline-flex;align-items:center;gap:10px;font-weight:700;color:var(--text);font-size:16px}.brand-mark{width:28px;height:28px;border-radius:8px;background:var(--accent);color:var(--bg);display:inline-flex;align-items:center;justify-content:center;font-weight:900}.brand-text{white-space:nowrap}.topbar-actions{margin-left:auto;display:flex;gap:4px}.topbar-link{color:var(--text-dim);padding:6px 10px;border-radius:8px;font-size:13px}.topbar-link:hover{color:var(--text);background:var(--bg-elev)}.hamburger{background:transparent;border:1px solid var(--border);border-radius:8px;width:36px;height:36px;display:none;flex-direction:column;justify-content:center;align-items:center;gap:4px;cursor:pointer}.hamburger span{display:block;width:16px;height:2px;background:var(--text);border-radius:2px}.shell-body{flex:1;display:grid;grid-template-columns:var(--sidebar-w) minmax(0,1fr);position:relative}.main-pane{padding:32px 36px 80px;min-width:0}.sidebar-backdrop{display:none;position:fixed;inset:var(--topbar-h) 0 0 0;background:#0000008c;z-index:30}.sidebar{border-right:1px solid var(--border);background:var(--bg-soft);padding:22px 16px 40px;overflow-y:auto;height:calc(100vh - var(--topbar-h));position:sticky;top:var(--topbar-h)}.sidebar-home{display:block;color:var(--text-dim);padding:6px 8px;border-radius:6px;font-size:13px;margin-bottom:14px}.sidebar-home.active,.sidebar-home:hover{color:var(--accent);background:var(--bg-elev)}.sidebar-section{margin-bottom:18px}.sidebar-section-label{text-transform:uppercase;letter-spacing:.08em;font-size:11px;color:var(--text-mute);padding:0 8px 6px}.sidebar-list{list-style:none;margin:0;padding:0}.sidebar-link{display:block;padding:6px 10px;border-radius:6px;color:var(--text-dim);font-size:14px;line-height:1.3;margin-bottom:1px;border-left:2px solid transparent}.sidebar-link:hover{color:var(--text);background:var(--bg-card)}.sidebar-link.active{color:var(--accent);background:var(--bg-elev);border-left-color:var(--accent);font-weight:600}.search-wrap{position:relative;width:100%;max-width:720px}.search-shell{display:flex;align-items:center;gap:10px;background:var(--bg-card);border:1px solid var(--border);border-radius:12px;padding:10px 14px;transition:border-color .15s ease,box-shadow .15s ease}.search-shell:focus-within{border-color:var(--accent);box-shadow:0 0 0 3px #ffe5001f}.search-icon{font-size:14px;opacity:.7}.search-input{flex:1;background:transparent;border:0;outline:0;color:var(--text);font-size:15px;min-width:0}.search-clear{background:transparent;border:0;color:var(--text-mute);font-size:18px;cursor:pointer;padding:0 4px}.search-clear:hover{color:var(--text)}.search-results{position:absolute;top:calc(100% + 6px);left:0;right:0;background:var(--bg-card);border:1px solid var(--border);border-radius:12px;box-shadow:var(--shadow);max-height:60vh;overflow-y:auto;z-index:40}.search-empty{padding:16px;color:var(--text-dim);font-size:14px}.search-result{display:block;padding:12px 14px;border-bottom:1px solid var(--border);color:var(--text)}.search-result:last-child{border-bottom:0}.search-result.active,.search-result:hover{background:var(--bg-elev)}.search-result-head{display:flex;justify-content:space-between;gap:12px;align-items:baseline;margin-bottom:4px}.search-result-title{font-weight:600;font-size:14px;color:var(--text)}.search-result-section{color:var(--text-mute);font-size:11px;text-transform:uppercase;letter-spacing:.06em}.search-result-snippet{color:var(--text-dim);font-size:13px;line-height:1.4;overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical}.home{max-width:var(--content-max);margin:0 auto}.hero{padding:24px 0 28px;margin-bottom:22px;border-bottom:1px solid var(--border)}.hero-eyebrow{display:inline-block;font-size:11px;text-transform:uppercase;letter-spacing:.12em;color:var(--accent);background:#ffe5001a;border:1px solid rgba(255,229,0,.35);border-radius:999px;padding:4px 12px;margin-bottom:16px}.hero-title{font-size:clamp(28px,4vw,40px);line-height:1.15;margin:0 0 14px;letter-spacing:-.02em}.hero-sub{color:var(--text-dim);font-size:16px;max-width:640px;margin:0 0 22px}.hero-cta{color:var(--text-dim);font-size:13px;margin-top:14px}.hero-link{background:transparent;border:0;color:var(--link);cursor:pointer;padding:0;font:inherit}.hero-link:hover{color:var(--accent)}.section{margin:36px 0}.section-title{font-size:18px;margin:0 0 14px;color:var(--text)}.card-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:14px}.doc-card{display:block;padding:18px;background:var(--bg-card);border:1px solid var(--border);border-radius:var(--radius);color:var(--text);transition:transform .15s ease,border-color .15s ease,background .15s ease}.doc-card:hover{background:var(--bg-elev);border-color:var(--accent);transform:translateY(-2px)}.doc-card-tag{display:inline-block;font-size:11px;text-transform:uppercase;letter-spacing:.08em;color:var(--accent);margin-bottom:8px}.doc-card-title{font-weight:700;font-size:16px;margin-bottom:8px}.doc-card-excerpt{color:var(--text-dim);font-size:13px;margin:0 0 12px;line-height:1.45;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical;overflow:hidden}.doc-card-cta{color:var(--link);font-size:13px}.all-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:22px}.all-section-label{text-transform:uppercase;letter-spacing:.08em;font-size:12px;color:var(--text-mute);margin-bottom:8px}.all-section-list{list-style:none;margin:0;padding:0}.all-section-list li{padding:4px 0}.all-section-list a{color:var(--text-dim);font-size:14px}.all-section-list a:hover{color:var(--accent)}.doc-page{max-width:var(--content-max);margin:0 auto}.breadcrumb{color:var(--text-mute);font-size:13px;margin-bottom:14px;display:flex;flex-wrap:wrap;align-items:center}.crumb{display:inline-flex;align-items:center}.crumb-sep{padding:0 8px;color:var(--text-mute)}.doc-page-search{margin:0 0 24px}.doc-pager{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:36px;padding-top:22px;border-top:1px solid var(--border)}.doc-pager-cell.right{justify-self:end;text-align:right}.doc-pager-link{display:block;padding:14px 16px;background:var(--bg-card);border:1px solid var(--border);border-radius:var(--radius);color:var(--text);min-width:220px}.doc-pager-link:hover{border-color:var(--accent)}.doc-pager-dir{display:block;color:var(--text-mute);font-size:12px;text-transform:uppercase;letter-spacing:.08em;margin-bottom:4px}.doc-pager-title{color:var(--text);font-weight:600;font-size:14px}.markdown-body{font-size:15px;line-height:1.7;color:var(--text);word-wrap:break-word}.markdown-body h1,.markdown-body h2,.markdown-body h3,.markdown-body h4,.markdown-body h5{line-height:1.25;margin:28px 0 14px;color:var(--text);font-weight:700}.markdown-body h1{font-size:clamp(26px,3.4vw,34px);border-bottom:1px solid var(--border);padding-bottom:12px;margin-top:8px}.markdown-body h2{font-size:22px}.markdown-body h3{font-size:18px}.markdown-body p{margin:0 0 14px;color:var(--text)}.markdown-body ul,.markdown-body ol{padding-left:22px;margin:0 0 14px}.markdown-body li{margin-bottom:4px}.markdown-body blockquote{border-left:3px solid var(--accent);background:var(--bg-card);color:var(--text-dim);padding:10px 14px;margin:14px 0;border-radius:0 var(--radius-sm) var(--radius-sm) 0}.markdown-body code{background:var(--code-bg);border:1px solid var(--border);padding:1px 6px;border-radius:5px;font-family:JetBrains Mono,Fira Code,monospace;font-size:13px}.markdown-body pre{background:var(--code-bg)!important;border:1px solid var(--border);border-radius:var(--radius-sm);padding:14px 16px;overflow-x:auto;margin:14px 0}.markdown-body pre code{background:transparent;border:0;padding:0;font-size:13px;line-height:1.55}.markdown-body hr{border:0;border-top:1px solid var(--border);margin:24px 0}.markdown-body table{border-collapse:collapse;width:100%;margin:14px 0;font-size:14px}.markdown-body th,.markdown-body td{border:1px solid var(--border);padding:8px 12px;text-align:left}.markdown-body th{background:var(--bg-card)}.markdown-body img{max-width:100%;border-radius:var(--radius-sm)}.md-img-stub{display:inline-flex;align-items:center;gap:6px;background:var(--bg-card);border:1px dashed var(--border);color:var(--text-mute);padding:4px 10px;border-radius:8px;font-size:13px}.footer{padding:18px 24px;color:var(--text-mute);font-size:12px;border-top:1px solid var(--border);background:var(--bg-soft);display:flex;justify-content:center;gap:8px}.footer-sep{opacity:.5}.not-found{padding:60px 0;text-align:center}.not-found h1{font-size:80px;margin:0;color:var(--accent)}@media(max-width:960px){.hamburger{display:inline-flex}.shell-body{grid-template-columns:1fr}.sidebar{position:fixed;top:var(--topbar-h);left:0;bottom:0;width:min(85vw,320px);z-index:35;transform:translate(-100%);transition:transform .22s cubic-bezier(.2,.7,.2,1);height:auto}.shell-body.sidebar-open .sidebar{transform:translate(0)}.shell-body.sidebar-open .sidebar-backdrop{display:block}.main-pane{padding:24px 18px 64px}}

dist/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" type="image/svg+xml" href="./favicon.svg" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <meta name="description" content="Exocore — visual documentation. Browser-based IDE, social platform, and developer panel." />
+        <meta name="theme-color" content="#FFE500" />
+        <title>Exocore Docs</title>
+      <script type="module" crossorigin src="./assets/index-Dv5XhPnV.js"></script>
+      <link rel="stylesheet" crossorigin href="./assets/index-CYg-Es9k.css">
+    </head>
+    <body>
+        <div id="root"></div>
+    </body>
+</html>

docs/README.md

@@ -0,0 +1,81 @@
+# Exocore Web — Visual Documentation
+
+> Generated on April 24, 2026 — captures every panel route in **desktop (1440×900)**
+> and **mobile (390×844)** using bundled Chromium via Puppeteer.
+> Re-run with `npx tsx exocore-web/scripts/capture-docs.ts`.
+
+Exocore Web is a next-generation **browser-based IDE + developer panel** with built-in
+social features (posts, DMs, friends), gamified XP / leaderboard, project nodes,
+cloud storage (Google Drive), GitHub integration, NPM / pip / Cargo package
+managers, and a multi-language editor backed by Monaco + CodeMirror.
+
+The panel is mounted at the `/exocore` URL prefix. The whole SPA sits behind the
+**panel-devs gate** (`devs.json` master account) which protects every route on the
+server. Once unlocked, regular **user accounts** sign in via `/exocore/login`.
+
+---
+
+## 📚 Sections
+
+| # | Folder | What it covers |
+|---|--------|----------------|
+| 1 | [`./panel/`](./panel/README.md) | Panel-devs gate (master `devs.json` lock screen) |
+| 2 | [`./auth/`](./auth/README.md) | Home landing, Login, Register, Forgot, Verify, OAuth callback |
+| 3 | [`./dashboard/`](./dashboard/README.md) | Main `/dashboard` workspace (after user login) |
+| 4 | [`./profile/`](./profile/README.md) | `/u/:username` — profile, posts, friends, "stalk" mode |
+| 5 | [`./social/`](./social/README.md) | SocialPanel — chat, DMs, online presence, posts |
+| 6 | [`./leaderboard/`](./leaderboard/README.md) | Top members ranked by XP / level / achievements |
+| 7 | [`./projects/`](./projects/README.md) | Project nodes, CreateProjectWizard, FileManager |
+| 8 | [`./cloud/`](./cloud/README.md) | Google Drive cloud storage manager |
+| 9 | [`./github/`](./github/README.md) | GitHub integration (org browse, clone, push) |
+| 10 | [`./editor/`](./editor/README.md) | IDE (Monaco/CodeMirror), languages, terminal, AI, NPM |
+
+Raw screenshot grids live in
+[`./screenshots/desktop/`](./screenshots/desktop) and
+[`./screenshots/mobile/`](./screenshots/mobile).
+
+---
+
+## 🗺️ Route map
+
+| URL                          | Component                              | Auth required |
+|------------------------------|----------------------------------------|---------------|
+| `/exocore/`                  | `access/auth/Home.tsx` (landing)       | Panel only    |
+| `/exocore/login`             | `access/auth/Login.tsx`                | Panel only    |
+| `/exocore/register`          | `access/auth/Register.tsx`             | Panel only    |
+| `/exocore/forgot`            | `access/auth/Forgot.tsx`               | Panel only    |
+| `/exocore/verify-pending`    | `access/auth/VerifyPending.tsx`        | Panel only    |
+| `/exocore/auth/callback`     | `access/auth/AuthCallback.tsx`         | Panel only    |
+| `/exocore/dashboard`         | `home/Dashboard.tsx`                   | Panel + user  |
+| `/exocore/u/:username`       | `profile/Profile.tsx`                  | Panel + user  |
+| `/exocore/leaderboard`       | `leaderboard/Leaderboard.tsx`          | Panel + user  |
+| `/exocore/editor`            | `editor/coding.tsx`                    | Panel + user  |
+
+---
+
+## 🧰 Stack snapshot
+
+- **Server**: Express 5 + TypeScript (`exocore-web/app.ts`, `index.ts`), with
+  WebSocket multiplexer (`server/wsMux`), social hub (`server/social/hub`),
+  RPC hub (`server/rpc/hub`).
+- **Client**: React 19 + Vite + React Router (basename `/exocore`), Monaco / CodeMirror,
+  xterm.js, Framer Motion, SweetAlert2, Zustand.
+- **Backend (separate)**: `Exocore-Backend/` — Express + Google Drive sync,
+  encrypted user store, mail, OAuth.
+- **Auth model**:
+  - **Panel gate** → server-side `devs.json` (one master account per server).
+  - **User auth** → email-verified accounts handled by the Exocore-Backend.
+
+---
+
+## ▶️ How the screenshots were captured
+
+Both viewports were rendered with a real **Chromium 138** binary
+(`/nix/store/.../chromium`) driven by Puppeteer. The script:
+
+1. Loads `/exocore/` to capture the panel-devs **setup gate**.
+2. Submits the gate form to create the master account.
+3. Re-visits every route and takes a `fullPage` PNG.
+4. Repeats for the mobile viewport.
+
+See [`exocore-web/scripts/capture-docs.ts`](../scripts/capture-docs.ts).

docs/auth/README.md

@@ -0,0 +1,117 @@
+# Authentication Flow
+
+Once the panel-devs gate is unlocked, the SPA exposes a complete user-account
+flow backed by **`Exocore-Backend`** (email-verified accounts, Google Drive
+hashed at rest, OAuth). All five auth screens render with the same dark
+neon-yellow brand and share `access/components/AuthLayout.tsx`.
+
+## Files
+
+| Route | Component |
+|-------|-----------|
+| `/exocore/`              | [`access/auth/Home.tsx`](../../client/access/auth/Home.tsx) |
+| `/exocore/login`         | [`access/auth/Login.tsx`](../../client/access/auth/Login.tsx) |
+| `/exocore/register`      | [`access/auth/Register.tsx`](../../client/access/auth/Register.tsx) |
+| `/exocore/forgot`        | [`access/auth/Forgot.tsx`](../../client/access/auth/Forgot.tsx) |
+| `/exocore/verify-pending`| [`access/auth/VerifyPending.tsx`](../../client/access/auth/VerifyPending.tsx) |
+| `/exocore/auth/callback` | [`access/auth/AuthCallback.tsx`](../../client/access/auth/AuthCallback.tsx) |
+
+The user token (`exo_token`) is stored in `localStorage` and is rebroadcast on
+every `/exocore/api/*` axios request via the global interceptor in
+`access/panelAuth.ts`.
+
+---
+
+## 1. Home (landing) — `/exocore/`
+
+The first screen a visitor sees after the panel-devs gate. Pure marketing:
+brand, tagline, two CTAs (`Get Started` → `/login`, `Create Account` →
+`/register`) and feature pills (Fast IDE, Live Terminal, AI Assistant,
+NPM Manager, Git/GitHub, Web Preview).
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Home — desktop](../screenshots/desktop/02-home-landing.png) | ![Home — mobile](../screenshots/mobile/02-home-landing.png) |
+
+If `localStorage.exo_token` is already present, `useEffect` redirects to
+`/dashboard` — repeat visitors skip this page entirely.
+
+---
+
+## 2. Login — `/exocore/login`
+
+Two-field sign in (username **or** email + password) with show-password eye
+toggle, "Forgot password?" link, and an inline "Create an account" footer
+link.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Login — desktop](../screenshots/desktop/03-login.png) | ![Login — mobile](../screenshots/mobile/03-login.png) |
+
+Submission calls `POST /exocore/api/auth/login` (proxied to the backend).
+On success the token is stamped into `localStorage.exo_token` and the user is
+forwarded to `/dashboard`. Failures show a red banner inside the card.
+
+---
+
+## 3. Register — `/exocore/register`
+
+Multi-step account creation: username, email, password (with strength meter),
+country, optional avatar upload. Validation is real-time (Zod-ish hand-rolled
+checks) and the `Create account` button is disabled until every field passes.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Register — desktop](../screenshots/desktop/04-register.png) | ![Register — mobile](../screenshots/mobile/04-register.png) |
+
+After submit, the backend sends a verification e-mail and the SPA pushes the
+user to `/verify-pending`.
+
+---
+
+## 4. Forgot password — `/exocore/forgot`
+
+Single email input. Submitting calls
+`POST /exocore/api/auth/forgot` which dispatches a one-time reset code to the
+mail address. The page then asks for the code + new password inline (no
+extra route — same component swaps state).
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Forgot — desktop](../screenshots/desktop/05-forgot-password.png) | ![Forgot — mobile](../screenshots/mobile/05-forgot-password.png) |
+
+---
+
+## 5. Verify pending — `/exocore/verify-pending`
+
+Holding screen shown right after sign-up. Polls
+`GET /exocore/api/auth/verify/status?email=…` every few seconds and
+auto-forwards to `/login` once the user clicks the link inside the
+verification mail. Buttons: **Resend e-mail**, **Change e-mail**, **Back**.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Verify — desktop](../screenshots/desktop/06-verify-pending.png) | ![Verify — mobile](../screenshots/mobile/06-verify-pending.png) |
+
+---
+
+## 6. OAuth callback — `/exocore/auth/callback`
+
+Tiny landing page used by Google OAuth (and any future provider). Reads the
+`?token=` query string set by the backend redirect, persists it via
+`setPanelToken`, and `navigate('/dashboard')`. No screenshot needed — it
+flashes for less than a second.
+
+---
+
+## Backend touchpoints
+
+| Endpoint                                  | Used by |
+|-------------------------------------------|---------|
+| `POST /exocore/api/auth/register`         | Register |
+| `POST /exocore/api/auth/login`            | Login |
+| `POST /exocore/api/auth/forgot`           | Forgot |
+| `POST /exocore/api/auth/verify`           | Verify-pending poll |
+| `GET  /exocore/api/auth/userinfo`         | Bootstrapped by Dashboard |
+| `GET  /exocore/api/auth/audit`            | Account / security tab |
+| `DELETE /exocore/api/auth/delete`         | Account → Delete account |

docs/cloud/README.md

@@ -0,0 +1,71 @@
+# Cloud Backups — Google Drive integration
+
+Exocore mirrors all panel state to a private folder on the **owner's Google
+Drive** so that you can wipe / re-deploy the server and restore everything in
+seconds. The client side lives in
+[`home/GDriveManager.tsx`](../../client/home/GDriveManager.tsx) (modal opened
+from the dashboard's `☁ Cloud Backups` quick action) plus
+[`editor/GDrivePane.tsx`](../../client/editor/GDrivePane.tsx) (Drive sidebar
+inside the IDE).
+
+## What gets synced
+
+| Backend file                          | What it stores |
+|---------------------------------------|----------------|
+| `Exocore-Backend/local-db/users.enc`  | All user accounts (encrypted at rest) |
+| `Exocore-Backend/local-db/posts.json` | Public posts feed |
+| `Exocore-Backend/local-db/dms.*`      | Direct messages |
+| `Exocore-Backend/local-db/global-chat.json` | Global chat backlog |
+| `Exocore-Backend/local-db/token.enc`  | OAuth bootstrap |
+| `client/access/devs.json`             | Panel-devs master account |
+
+A background loop in
+[`Exocore-Backend/src/services/drive.ts`](../../Exocore-Backend/src/services/drive.ts)
+checks every 60 s, uploads diffs, and emits cache-restore events on boot
+(`[cache] restoring from Drive…`).
+
+## Manager modal — desktop / mobile
+
+Opened from `Dashboard → Quick Actions → Cloud Backups`. Sections:
+
+```
+┌─ Connected account ──────────────┐
+│  📷 Google avatar  email · plan  │
+│  Disk used: 4.2 GB / 15 GB        │
+│  [ Re-authorize ]  [ Disconnect ] │
+├─ Sync status ────────────────────┤
+│  ✅ users.enc        2 s ago      │
+│  ✅ posts.json       2 s ago      │
+│  🔄 dms.*            uploading…   │
+│  ⚠️ tokens.enc       error: …     │
+├─ Manual actions ─────────────────┤
+│  [ ⬆ Force upload ]  [ ⬇ Pull now ]│
+│  [ 🗑 Reset cloud cache ]          │
+└──────────────────────────────────┘
+```
+
+(Same dashboard capture applies — the modal opens on top of it once a user is
+authenticated.)
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Dashboard — desktop](../screenshots/desktop/07-dashboard.png) | ![Dashboard — mobile](../screenshots/mobile/07-dashboard.png) |
+
+## OAuth flow
+
+1. User clicks **Connect Google Drive** → server redirects to Google's consent
+   screen with the `drive.file` scope.
+2. Google redirects back to `/exocore/api/oauth/google/callback`.
+3. Server exchanges the code, encrypts + writes the refresh token to
+   `Exocore-Backend/local-db/token.enc`.
+4. Sync loop boots and walks the `EXOCORE_BACKUPS` parent folder.
+
+## RPC + HTTP touchpoints
+
+| Channel / route                           | Purpose |
+|-------------------------------------------|---------|
+| RPC `drive.status`                        | Connected account + per-file last-sync ts |
+| RPC `drive.sync`                          | Force a full upload pass |
+| RPC `drive.pull`                          | Replace local cache with Drive copy |
+| RPC `drive.disconnect`                    | Revoke + clear local token |
+| HTTP `POST /exocore/api/editor/gdrive/*`  | IDE-side file picker (proxied to backend Drive scope) |

docs/dashboard/README.md

@@ -0,0 +1,97 @@
+# Dashboard — `/exocore/dashboard`
+
+The Dashboard is the **command-centre** that opens right after a successful
+user login. Implemented in
+[`client/home/Dashboard.tsx`](../../client/home/Dashboard.tsx); ~770 lines
+that orchestrate every other panel as either an inline view (`activeView`) or
+a modal (`*Open` flags).
+
+> The screenshots below show the **redirect to `/login`** because the docs
+> capture run was unauthenticated. With a real `exo_token` in
+> `localStorage`, the same route renders the layout described below.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Dashboard redirect — desktop](../screenshots/desktop/07-dashboard.png) | ![Dashboard redirect — mobile](../screenshots/mobile/07-dashboard.png) |
+
+---
+
+## Layout
+
+```
+┌─ Header ──────────────────────────────────────────────┐
+│  EXOCORE   • CPU 4 % · RAM 42 % · 14:22:01            │
+│  Avatar ⟶ Profile · Leaderboard · ⚙ Account · Logout  │
+├─ Welcome card ────────────────────────────────────────┤
+│  Hi {nickname}, plan: FREE / PRO / OWNER              │
+│  Plan-upgrade button (opens PlansModal)               │
+├─ Stats row ───────────────────────────────────────────┤
+│  Projects · Active · CPU · RAM (live ticking)         │
+├─ Project Nodes ───────────────────────────────────────┤
+│  Grid of ProjectNodeCard (open · run · archive)       │
+│  + "Show all" toggle if > 6                           │
+├─ Quick Actions ───────────────────────────────────────┤
+│  ▢ Project Nodes · ⚙ Account · ☁ Cloud Backups · …  │
+├─ Social grid ─────────────────────────────────────────┤
+│  GitHub · Drive · Discord · X · Donations …           │
+└───────────────────────────────────────────────────────┘
+```
+
+## State machine
+
+`activeView` only swaps two top-level views:
+
+| Value | What renders |
+|-------|--------------|
+| `'home'`   | The composite layout above |
+| `'account'`| Inline `<Account />` settings sub-page |
+
+Everything else is a modal driven by booleans:
+
+| Flag | Modal component | What it does |
+|------|----------------|--------------|
+| `projectsOpen`     | `FileManager`         | Browse all projects + storage usage |
+| `gDriveOpen`       | `GDriveManager`       | OAuth-connect Google Drive, sync state |
+| `githubOpen`       | `GithubManager`       | OAuth-connect GitHub, browse repos |
+| `plansOpen`        | `PlansModal`          | Upgrade plan (free → pro / owner) |
+| `ownerPaymentsOpen`| `OwnerPaymentsPanel`  | Owner-only revenue / pay-out view |
+| `headerMenuOpen`   | Inline dropdown       | Profile · Leaderboard · Account |
+| `dialog`           | SweetAlert2 wrapper   | Confirm / prompt / alert |
+
+## Header chips
+
+- **Avatar** → `navigate(/u/${userData.username})` (own profile)
+- **Trophy** → `/leaderboard`
+- **Gear** → switches `activeView` to `'account'`
+- **Logout** → clears `exo_token`, navigates back to `/login`
+
+## Stats card
+
+Powered by an interval that polls `/exocore/api/auth/userinfo` and the local
+`navigator.connection` API; falls back to mocked values (`stats = { cpu, ram }`)
+when the live numbers aren't available yet.
+
+## Social grid
+
+A static array `SOCIAL_LINKS` with id `github`, `gdrive`, `discord`, `twitter`,
+`donate`, `youtube`. Rendered as **outbound** cards — clicking opens the org's
+public page (e.g. `https://github.com/Exocore-Organization`). Different from
+the in-app `social/SocialPanel` (chat / DM / posts) which is documented
+separately under [`../social/`](../social/README.md).
+
+## Auth shape consumed
+
+```ts
+type UserData = {
+  username: string;          // e.g. "@exocore"
+  nickname: string;          // "Costanos"
+  email: string;
+  plan: "free" | "pro" | "owner";
+  role: "user" | "mod" | "admin" | "owner";
+  xp: number;
+  level: number;
+  avatarUrl?: string;
+  country?: string;
+  // … plus payments / drive / github linked-account fields
+};
+```

docs/editor/00-panel-gate.md

@@ -0,0 +1,25 @@
+# 00 — Panel gate
+
+  First-touch screen at `/exocore/`. Until a panel-devs master account exists in `devs.json`, every other route is locked behind this gate. The form doubles as both the **register-master** flow (when the file is empty) and the **unlock** flow (when an account is already provisioned).
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![00 — Panel gate — desktop](../screenshots/editor/00-panel-gate.png) | ![00 — Panel gate — mobile](../screenshots/editor/mobile/00-panel-gate.png) |
+  
+  ## What it does
+
+  - POST `/exocore/api/access/panel/register` (first run) → writes the salted master credential into `devs.json`.
+- POST `/exocore/api/access/panel/unlock` (subsequent runs) → returns a short-lived panel cookie used by every other route.
+- All other client routes redirect here while the cookie is missing.
+
+  ## Source files
+
+  - [`client/access/Panel.tsx`](../../client/access/Panel.tsx)
+- [`routes/access/panel.ts`](../../routes/access/panel.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/01-editor-default.md

@@ -0,0 +1,26 @@
+# 01 — Default editor view
+
+  Right after login + project pick, the editor opens onto the project root. Monaco shows a welcome banner, the file explorer lists the seeded files, and the bottom panel starts collapsed.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![01 — Default editor view — desktop](../screenshots/editor/01-editor-default.png) | ![01 — Default editor view — mobile](../screenshots/editor/mobile/01-editor-default.png) |
+  
+  ## What it does
+
+  - `<LayoutHeader />` shows the project name + path, command palette button, and theme toggle.
+- `<Sidebar />` defaults to the **Explorer** tab (`activeSidebarTab = 'explorer'`).
+- Bottom panel is `'none'` unless the user navigated in with `?autoinstall=1` (in which case the terminal opens with the install command pre-loaded).
+
+  ## Source files
+
+  - [`client/editor/coding.tsx`](../../client/editor/coding.tsx)
+- [`client/editor/Layout.tsx`](../../client/editor/Layout.tsx)
+- [`client/editor/Sidebar.tsx`](../../client/editor/Sidebar.tsx)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/02-editor-explorer-file.md

@@ -0,0 +1,27 @@
+# 02 — Explorer file open
+
+  Clicking a file in the explorer (here `index.js`) opens it in a new tab. Monaco loads its contents, the LSP bridge spins up the matching language server, and diagnostics start streaming back into the gutter and the Problems pane.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![02 — Explorer file open — desktop](../screenshots/editor/02-editor-explorer-file.png) | ![02 — Explorer file open — mobile](../screenshots/editor/mobile/02-editor-explorer-file.png) |
+  
+  ## What it does
+
+  - Tabs are stored in `useFileStore` so a refresh restores the same set of open files.
+- The active file's contents are persisted to IndexedDB on every keystroke (via the autosave timer in `coding.tsx`).
+- `useLspClient(content, fileName, projectId)` opens a WebSocket to `/exocore/api/editor/lsp` and routes diagnostics back into the editor.
+
+  ## Source files
+
+  - [`client/editor/Sidebar.tsx`](../../client/editor/Sidebar.tsx)
+- [`client/editor/Tabs.tsx`](../../client/editor/Tabs.tsx)
+- [`client/editor/SimpleCodeEditor.tsx`](../../client/editor/SimpleCodeEditor.tsx)
+- [`client/editor/LspClient.tsx`](../../client/editor/LspClient.tsx)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/03-editor-terminal.md

@@ -0,0 +1,25 @@
+# 03 — Integrated terminal
+
+  `KittyTerminal.tsx` wraps `xterm.js` over a WebSocket pty bridge. Multiple tabs and split panes are supported; each tab is a separate node-pty process scoped to the project's working directory.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![03 — Integrated terminal — desktop](../screenshots/editor/03-editor-terminal.png) | ![03 — Integrated terminal — mobile](../screenshots/editor/mobile/03-editor-terminal.png) |
+  
+  ## What it does
+
+  - WebSocket endpoint: `wss://<host>/exocore/api/editor/shell?projectId=…&tabId=…`.
+- Server-side: `node-pty` spawns the user's preferred shell (`bash` on Linux containers, `pwsh` on Windows hosts) inside `projects/<projectId>/`.
+- ANSI colors and unicode glyphs use the `Cascadia Code` / `JetBrainsMono Nerd Font` fallback chain.
+
+  ## Source files
+
+  - [`client/terminal/KittyTerminal.tsx`](../../client/terminal/KittyTerminal.tsx)
+- [`routes/editor/shell.ts`](../../routes/editor/shell.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/04-editor-console.md

@@ -0,0 +1,25 @@
+# 04 — Console pane
+
+  `ConsolePane.tsx` shows the project runtime's stdout / stderr stream. The Start / Stop button calls `routes/editor/runtime.ts` which spawns the configured `exocore.run` script and pipes the output back over Server-Sent Events.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![04 — Console pane — desktop](../screenshots/editor/04-editor-console.png) | ![04 — Console pane — mobile](../screenshots/editor/mobile/04-editor-console.png) |
+  
+  ## What it does
+
+  - Console is **runtime output** — it's separate from the terminal (which is an interactive pty).
+- The desktop screenshot was captured mid-run; the mobile shot intentionally shows the empty pane (running the dev server inside the headless mobile profile detaches the page session).
+- The Stop button sends `SIGTERM` first then `SIGKILL` after a 3s grace period.
+
+  ## Source files
+
+  - [`client/editor/ConsolePane.tsx`](../../client/editor/ConsolePane.tsx)
+- [`routes/editor/runtime.ts`](../../routes/editor/runtime.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/05-editor-webview.md

@@ -0,0 +1,25 @@
+# 05 — Webview / preview (desktop only)
+
+  Whenever the runtime detects a freshly-bound HTTP server it surfaces the URL inside an embedded `<iframe>` (`Webview.tsx`). The mobile capture intentionally skips this frame — the embedded preview iframe consistently crashes the Chromium 138 mobile target during Puppeteer captures.
+
+  ## Screenshot
+
+  ![05 — Webview / preview (desktop only) — desktop](../screenshots/editor/05-editor-webview.png)
+
+  > Mobile capture is intentionally skipped for this frame — the embedded preview iframe crashes the Chromium 138 mobile target during Puppeteer runs.
+  
+  ## What it does
+
+  - Detection: a small line-scanner inside `runtime.ts` watches stdout for `Listening on http://…` / `Local: http://…` and feeds the URL to the webview pane.
+- Reverse-proxy: `/exocore/api/editor/proxy/:projectId/*` rewrites HTML/JS to keep relative URLs pointing at the proxy.
+- Tunnel button next to the URL spawns a Cloudflare quick-tunnel for sharing.
+
+  ## Source files
+
+  - [`client/editor/Webview.tsx`](../../client/editor/Webview.tsx)
+- [`routes/editor/runtime.ts`](../../routes/editor/runtime.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/06-editor-problems.md

@@ -0,0 +1,25 @@
+# 06 — Problems pane
+
+  LSP diagnostics aggregated across every open file, grouped per-file with severity icons. Click a row to jump straight to the offending line.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![06 — Problems pane — desktop](../screenshots/editor/06-editor-problems.png) | ![06 — Problems pane — mobile](../screenshots/editor/mobile/06-editor-problems.png) |
+  
+  ## What it does
+
+  - Source: the same `useLspClient(...)` hook used by the editor gutter.
+- Severity counts (errors / warnings) are also surfaced in the status bar.
+- Click a diagnostic → `jumpToLine(line)` in `coding.tsx` selects the position in the active textarea and scrolls it into view.
+
+  ## Source files
+
+  - [`client/editor/Layout.tsx`](../../client/editor/Layout.tsx)
+- [`client/editor/LspClient.tsx`](../../client/editor/LspClient.tsx)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/07-sidebar-npm.md

@@ -0,0 +1,25 @@
+# 07 — NPM sidebar pane
+
+  `NpmPane.tsx` searches the public registry, lists the project's installed dependencies, and (when an access token is present in localStorage) lets you publish a new version.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![07 — NPM sidebar pane — desktop](../screenshots/editor/07-sidebar-npm.png) | ![07 — NPM sidebar pane — mobile](../screenshots/editor/mobile/07-sidebar-npm.png) |
+  
+  ## What it does
+
+  - Search proxies through `/exocore/api/editor/npm/search?q=…` to avoid CORS and to allow private-registry overrides.
+- Install / uninstall calls into `routes/editor/npm.ts` which runs `npm install --save` inside the project workspace.
+- Publish flow uses the user's npm access token (stored client-side, never echoed back to the server logs).
+
+  ## Source files
+
+  - [`client/editor/NpmPane.tsx`](../../client/editor/NpmPane.tsx)
+- [`routes/editor/npm.ts`](../../routes/editor/npm.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/08-sidebar-github.md

@@ -0,0 +1,25 @@
+# 08 — GitHub sidebar pane
+
+  `GithubPane.tsx` covers the full editor-side Git workflow: OAuth login, clone, push / pull, branch switching, staged-files diff view, and per-file revert. See the dedicated [GitHub pane docs](../github/README.md) for the full feature matrix.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![08 — GitHub sidebar pane — desktop](../screenshots/editor/08-sidebar-github.png) | ![08 — GitHub sidebar pane — mobile](../screenshots/editor/mobile/08-sidebar-github.png) |
+  
+  ## What it does
+
+  - OAuth happens through `/exocore/api/access/github/start` → `/callback`; the resulting token is stored encrypted on the backend, not in localStorage.
+- All git operations are POSTed through `/exocore/api/editor/github/*` and shell out to `git` inside the project workspace.
+- The diff view is a Monaco DiffEditor reused by the file-history modal (frame 11).
+
+  ## Source files
+
+  - [`client/editor/GithubPane.tsx`](../../client/editor/GithubPane.tsx)
+- [`routes/editor/github.ts`](../../routes/editor/github.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/09-sidebar-drive.md

@@ -0,0 +1,26 @@
+# 09 — Drive sidebar pane
+
+  `GDrivePane.tsx` picks files / folders from the connected Google Drive account and uploads project files back the other way. Drive auth is shared with the dashboard's [Cloud manager](../cloud/README.md).
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![09 — Drive sidebar pane — desktop](../screenshots/editor/09-sidebar-drive.png) | ![09 — Drive sidebar pane — mobile](../screenshots/editor/mobile/09-sidebar-drive.png) |
+  
+  ## What it does
+
+  - Picker uses the standard Google Picker API embedded inside an iframe modal — no extra OAuth round-trip if the user already linked Drive in the dashboard.
+- Upload writes go through `/exocore/api/editor/gdrive/upload` (multipart) and inherit the user's per-folder ACL.
+- Drive sessions are revoked from `Dashboard → Account → Connections`.
+
+  ## Source files
+
+  - [`client/editor/GDrivePane.tsx`](../../client/editor/GDrivePane.tsx)
+- [`routes/editor/gdrive.ts`](../../routes/editor/gdrive.ts)
+- [`server/services/googleDrive`](../../server/services/googleDrive)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/10-sidebar-ai.md

@@ -0,0 +1,27 @@
+# 10 — AI sidebar pane
+
+  `ExocoreAI.tsx` is the in-editor chat assistant. It streams Server-Sent Events from `routes/editor/ai.ts`, supports file / terminal tool-use, and can target the built-in Exo provider or any user-configured OpenAI / Anthropic / OpenRouter key.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![10 — AI sidebar pane — desktop](../screenshots/editor/10-sidebar-ai.png) | ![10 — AI sidebar pane — mobile](../screenshots/editor/mobile/10-sidebar-ai.png) |
+  
+  ## What it does
+
+  - Chat tab — ChatGPT-style stream with code-blocks, file-attach, and an `Apply diff` button that pipes the suggested change through Monaco's diff merger.
+- Setup tab — pick provider, paste API key (kept in localStorage), set system prompt, choose model.
+- Tool-use is gated server-side: every read / write / shell call is logged in the project's `.exocore/ai-audit.log`.
+
+  ## Source files
+
+  - [`client/editor/ExocoreAI.tsx`](../../client/editor/ExocoreAI.tsx)
+- [`client/editor/ai/ExoSetupPanel.tsx`](../../client/editor/ai/ExoSetupPanel.tsx)
+- [`client/editor/ai/RestSetupPanel.tsx`](../../client/editor/ai/RestSetupPanel.tsx)
+- [`routes/editor/ai.ts`](../../routes/editor/ai.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/11-history-modal.md

@@ -0,0 +1,25 @@
+# 11 — Code history modal
+
+  Local versioned snapshots of the active file (kept in IndexedDB). Each entry shows the timestamp, a unified diff against the previous snapshot, and a `Restore` button. Opened from the topbar `Code history` icon.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![11 — Code history modal — desktop](../screenshots/editor/11-history-modal.png) | ![11 — Code history modal — mobile](../screenshots/editor/mobile/11-history-modal.png) |
+  
+  ## What it does
+
+  - Snapshots are auto-captured on every successful autosave (debounced 800 ms after the last keystroke).
+- Storage is per-file inside IndexedDB so it survives refresh, browser restart, and OAuth re-auth.
+- Restore swaps the active editor buffer back to the snapshot's content but does **not** auto-save — the user has to commit the change explicitly.
+
+  ## Source files
+
+  - [`client/editor/coding.tsx (HistoryCodePreview)`](../../client/editor/coding.tsx (HistoryCodePreview))
+- [`client/editor/fileStore.ts`](../../client/editor/fileStore.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/12-settings-modal.md

@@ -0,0 +1,26 @@
+# 12 — Settings modal
+
+  Theme picker, font family / size, key bindings, indent rules, word-wrap toggle, autosave delay, and the AI provider quick-link. Persisted to localStorage as well as synced to the user account when logged in.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![12 — Settings modal — desktop](../screenshots/editor/12-settings-modal.png) | ![12 — Settings modal — mobile](../screenshots/editor/mobile/12-settings-modal.png) |
+  
+  ## What it does
+
+  - Theme list is sourced from `editorThemes.ts` (60+ themes — One Dark Pro, Dracula, Tokyo Night, Replit, Catppuccin, Monokai, Synthwave 84, …).
+- Settings are split into tabs — `General · Editor · AI · About`.
+- Each numeric input is validated client-side before being written back to the store; out-of-range values fall back to the default.
+
+  ## Source files
+
+  - [`client/editor/Settings.tsx`](../../client/editor/Settings.tsx)
+- [`client/editor/editorThemes.ts`](../../client/editor/editorThemes.ts)
+- [`client/editor/uiStore.ts`](../../client/editor/uiStore.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/13-settings-theme-changed.md

@@ -0,0 +1,25 @@
+# 13 — Settings · theme switch
+
+  Same settings modal, captured immediately after switching to a different theme (Dracula on desktop). The swatches re-render live across the entire editor chrome — header, sidebar, status bar, even the modal itself — so users can preview without closing the dialog.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![13 — Settings · theme switch — desktop](../screenshots/editor/13-settings-theme-changed.png) | ![13 — Settings · theme switch — mobile](../screenshots/editor/mobile/13-settings-theme-changed.png) |
+  
+  ## What it does
+
+  - Theme application path: `setTheme(id)` → `useLegacyEditorStore` → CSS variables on `<body>` → re-render of every styled component.
+- The Monaco / CodeMirror grammars are restyled in the same tick using the matching token-color map from `editorThemes.ts`.
+- Closing the modal commits the change; pressing **Cancel** rolls back to the previous theme via the snapshot taken on open.
+
+  ## Source files
+
+  - [`client/editor/Settings.tsx`](../../client/editor/Settings.tsx)
+- [`client/editor/editorThemes.ts`](../../client/editor/editorThemes.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/14-sidebar-pylib.md

@@ -0,0 +1,26 @@
+# 14 — PyLib pane (Python project)
+
+  Switching to the seeded `exorepo-py` project re-labels the package tab to **PyPI** and renders `PyLibrary.tsx` in place of `NpmPane.tsx`. The same UX patterns apply (search → install → list installed) but the backing store is the project's `requirements.txt` / `pyproject.toml`.
+
+  ## Screenshots
+
+  | Desktop | Mobile |
+  |---------|--------|
+  | ![14 — PyLib pane (Python project) — desktop](../screenshots/editor/14-sidebar-pylib.png) | ![14 — PyLib pane (Python project) — mobile](../screenshots/editor/mobile/14-sidebar-pylib.png) |
+  
+  ## What it does
+
+  - Package-tab swap is driven by `getPackageManagerLabel(projectLanguage)` — the same dispatcher routes Rust → Cargo, Go → go modules, Java → Maven, etc.
+- Installs go through `pip install --user` inside the project's virtualenv (created on first install).
+- Search hits `https://pypi.org/pypi/<name>/json` server-side and is cached for 5 minutes per name.
+
+  ## Source files
+
+  - [`client/editor/PyLibrary.tsx`](../../client/editor/PyLibrary.tsx)
+- [`client/editor/PackagesPane.tsx`](../../client/editor/PackagesPane.tsx)
+- [`routes/editor/pylib.ts`](../../routes/editor/pylib.ts)
+
+  ---
+
+  ← Back to the [editor index](./README.md).
+  

docs/editor/README.md

@@ -0,0 +1,302 @@
+# Editor / IDE — `/exocore/editor`
+
+The Exocore IDE is a full Monaco-and-CodeMirror powered code editor with file
+explorer, integrated terminal (xterm + node-pty), package managers, AI
+assistant, GitHub pane, Drive pane, language servers, and a webview for live
+previews.
+
+Entry point: [`client/editor/coding.tsx`](../../client/editor/coding.tsx).
+Layout shell: [`client/editor/Layout.tsx`](../../client/editor/Layout.tsx).
+
+Every screenshot below was captured by
+[`scripts/capture-editor.ts`](../../scripts/capture-editor.ts) against a freshly
+seeded `exorepo-demo` (Node) project. Mobile shots come from a 414×896 iPhone
+profile; desktop shots from a 1440×900 Chromium 138 window.
+
+## Per-frame docs (one MD per screenshot)
+
+Each frame in the gallery below has its own dedicated walkthrough — click
+the title to jump straight to it on GitHub:
+
+| # | Frame | Doc |
+|---|-------|-----|
+| 00 | Panel gate                     | [`00-panel-gate.md`](./00-panel-gate.md) |
+| 01 | Default editor view            | [`01-editor-default.md`](./01-editor-default.md) |
+| 02 | Explorer · open file           | [`02-editor-explorer-file.md`](./02-editor-explorer-file.md) |
+| 03 | Integrated terminal            | [`03-editor-terminal.md`](./03-editor-terminal.md) |
+| 04 | Console pane                   | [`04-editor-console.md`](./04-editor-console.md) |
+| 05 | Webview / preview *(desktop)*  | [`05-editor-webview.md`](./05-editor-webview.md) |
+| 06 | Problems pane                  | [`06-editor-problems.md`](./06-editor-problems.md) |
+| 07 | NPM sidebar                    | [`07-sidebar-npm.md`](./07-sidebar-npm.md) |
+| 08 | GitHub sidebar                 | [`08-sidebar-github.md`](./08-sidebar-github.md) |
+| 09 | Drive sidebar                  | [`09-sidebar-drive.md`](./09-sidebar-drive.md) |
+| 10 | AI sidebar                     | [`10-sidebar-ai.md`](./10-sidebar-ai.md) |
+| 11 | Code-history modal             | [`11-history-modal.md`](./11-history-modal.md) |
+| 12 | Settings modal                 | [`12-settings-modal.md`](./12-settings-modal.md) |
+| 13 | Settings · theme switch        | [`13-settings-theme-changed.md`](./13-settings-theme-changed.md) |
+| 14 | PyLib pane (Python project)    | [`14-sidebar-pylib.md`](./14-sidebar-pylib.md) |
+
+## Layout
+
+```
+┌─ Title bar ───────────────────────────────────────────────┐
+│ Exocore · project / file path · 🔍 cmd-K · 🌗 theme       │
+├─ Sidebar tabs ─────┬─ Tabs (open files) ──────────────────┤
+│ ▾ Explorer (📁)    │ index.ts ✕  utils.ts ✕  README.md ✕  │
+│   project tree     ├─ Editor pane ────────────────────────┤
+│ ▾ NPM (📦)         │  Monaco (or CodeMirror per language) │
+│ ▾ GitHub (🌿)      │  with LSP completion / diagnostics    │
+│ ▾ Drive (☁)        │                                       │
+│ ▾ AI (🤖)          │                                       │
+├──────────────────  ├─ Bottom panel ───────────────────────┤
+│                    │ [problems] [console] [terminal] [webview]
+└────────────────────┴───────────────────────────────────────┘
+                Status bar — git branch · LSP · runtime · cursor
+```
+
+`SidebarTab = 'explorer' | 'npm' | 'github' | 'drive' | 'ai'`
+`BottomPanel = 'problems' | 'console' | 'terminal' | 'webview' | 'none'`
+
+## Walkthrough
+
+### 00 — Panel gate
+
+The first thing a fresh browser sees is the per-machine panel-devs gate
+(`/exocore/`). Until a panel admin (e.g. `Choruyt`) is registered, the rest
+of the site is locked behind this form.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Panel gate — desktop](../screenshots/editor/00-panel-gate.png) | ![Panel gate — mobile](../screenshots/editor/mobile/00-panel-gate.png) |
+
+### 01 — Default editor view
+
+After login the editor opens onto the project root — Monaco shows a welcome
+banner and the explorer lists the seeded files.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Editor default — desktop](../screenshots/editor/01-editor-default.png) | ![Editor default — mobile](../screenshots/editor/mobile/01-editor-default.png) |
+
+### 02 — Explorer file open
+
+Clicking a file in the explorer (here `index.js`) opens it in a new tab and
+streams diagnostics from the matching LSP.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Explorer file — desktop](../screenshots/editor/02-editor-explorer-file.png) | ![Explorer file — mobile](../screenshots/editor/mobile/02-editor-explorer-file.png) |
+
+### 03 — Integrated terminal
+
+`KittyTerminal.tsx` wraps `xterm.js` over a WebSocket pty bridge
+(`routes/editor/shell.ts`). Multiple tabs and split panes are supported.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Terminal — desktop](../screenshots/editor/03-editor-terminal.png) | ![Terminal — mobile](../screenshots/editor/mobile/03-editor-terminal.png) |
+
+### 04 — Console pane
+
+`ConsolePane.tsx` shows the project's runtime stdout/stderr from
+`routes/editor/runtime.ts`. The Start/Stop button spawns the configured
+`exocore.run` script. The desktop screenshot was captured mid-run; mobile
+shows the empty pane (running the dev server inside the headless mobile
+profile detaches the page session).
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Console — desktop](../screenshots/editor/04-editor-console.png) | ![Console — mobile](../screenshots/editor/mobile/04-editor-console.png) |
+
+### 05 — Webview / preview (desktop only)
+
+When the runtime detects a bound HTTP server it surfaces the URL inside an
+embedded `<iframe>` (`Webview.tsx`). The mobile capture intentionally skips
+this — the embedded preview iframe consistently crashes the Chromium 138
+mobile target.
+
+![Webview — desktop](../screenshots/editor/05-editor-webview.png)
+
+### 06 — Problems pane
+
+LSP diagnostics grouped per-file. Click a row to jump straight to the
+offending line.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Problems — desktop](../screenshots/editor/06-editor-problems.png) | ![Problems — mobile](../screenshots/editor/mobile/06-editor-problems.png) |
+
+### 07 — NPM sidebar pane
+
+`NpmPane.tsx` searches the public registry, lists installed dependencies, and
+publishes packages using a browser-stored access token.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![NPM — desktop](../screenshots/editor/07-sidebar-npm.png) | ![NPM — mobile](../screenshots/editor/mobile/07-sidebar-npm.png) |
+
+### 08 — GitHub sidebar pane
+
+`GithubPane.tsx` covers OAuth auth, clone, push/pull, branch switching, and
+the staged-files diff view. Dedicated docs: [GitHub pane](../github/README.md).
+
+| Desktop | Mobile |
+|---------|--------|
+| ![GitHub — desktop](../screenshots/editor/08-sidebar-github.png) | ![GitHub — mobile](../screenshots/editor/mobile/08-sidebar-github.png) |
+
+### 09 — Drive sidebar pane
+
+`GDrivePane.tsx` picks files/folders from the connected Google Drive account
+and uploads project files back the other way.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Drive — desktop](../screenshots/editor/09-sidebar-drive.png) | ![Drive — mobile](../screenshots/editor/mobile/09-sidebar-drive.png) |
+
+### 10 — AI sidebar pane
+
+`ExocoreAI.tsx` is the chat assistant with file/terminal tool-use, streaming
+SSE responses through `routes/editor/ai.ts`.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![AI — desktop](../screenshots/editor/10-sidebar-ai.png) | ![AI — mobile](../screenshots/editor/mobile/10-sidebar-ai.png) |
+
+### 11 — Code history modal
+
+Local versioned snapshots of the active file (kept in IndexedDB) — diff +
+restore. Opened from the topbar `Code history` icon.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![History — desktop](../screenshots/editor/11-history-modal.png) | ![History — mobile](../screenshots/editor/mobile/11-history-modal.png) |
+
+### 12 — Settings modal
+
+Theme picker, font size, key bindings, indent rules, etc.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Settings — desktop](../screenshots/editor/12-settings-modal.png) | ![Settings — mobile](../screenshots/editor/mobile/12-settings-modal.png) |
+
+### 13 — Settings · theme switch
+
+Same modal after switching to a different theme (Dracula on desktop). The
+swatches re-render live across the editor and the surrounding chrome.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Theme switch — desktop](../screenshots/editor/13-settings-theme-changed.png) | ![Theme switch — mobile](../screenshots/editor/mobile/13-settings-theme-changed.png) |
+
+### 14 — PyLib pane (Python project)
+
+Switching to the seeded `exorepo-py` project re-labels the package tab to
+**PyPI** and renders `PyLibrary.tsx` in place of `NpmPane.tsx`.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![PyLib — desktop](../screenshots/editor/14-sidebar-pylib.png) | ![PyLib — mobile](../screenshots/editor/mobile/14-sidebar-pylib.png) |
+
+## Sidebar tabs reference
+
+| Tab | Component | What it does |
+|-----|-----------|--------------|
+| **Explorer** | `Sidebar.tsx`         | Tree view, drag-and-drop, context menu, multi-select |
+| **NPM**      | `NpmPane.tsx`         | Search npm, install / uninstall, see installed deps |
+| **GitHub**   | `GithubPane.tsx`      | See [GitHub docs](../github/README.md) |
+| **Drive**    | `GDrivePane.tsx`      | Pick / upload from Google Drive |
+| **AI**       | `ExocoreAI.tsx`       | Chat assistant with file/terminal tool-use |
+
+The package tab swaps based on project language via
+`PackagesPane.tsx` — `NPM` for Node, `PyPI` for Python, `Cargo` for Rust,
+`Go`, `Maven`, `Gems`, `Composer`, `NuGet`, `Hex`, `Cabal`, `SPM`, …
+
+## Bottom panels reference
+
+| Panel    | Source             | Notes |
+|----------|--------------------|-------|
+| Problems | LSP diagnostics    | grouped per-file, click to jump |
+| Console  | `ConsolePane.tsx`  | runtime stdout / stderr |
+| Terminal | `KittyTerminal.tsx` + `xterm` | pty-backed, supports tabs |
+| Webview  | `Webview.tsx`      | proxied iframe of the running project |
+
+## Languages
+
+`editor/language.tsx` registers Monaco grammars + CodeMirror extensions for:
+
+- TypeScript / JavaScript (with JSX)
+- Python · PHP · Rust · C · C++
+- HTML · CSS · JSON · Markdown
+- Plus syntax highlight via Prism for less common languages
+  (Go, Ruby, YAML, TOML, SQL, Shell, …) inside chat code blocks.
+
+LSP bridge: WebSocket to `routes/editor/_lspBridge.ts`, which spawns the
+appropriate language server (`pyright`, `tsserver`, `rust-analyzer`,
+`clangd`, …) per project.
+
+## Command palette
+
+`Ctrl + K` opens [`CommandPalette.tsx`](../../client/editor/CommandPalette.tsx)
+with fuzzy-search across files, commands, settings, and AI prompts.
+
+## AI assistant
+
+Two-pane component (`ExocoreAI.tsx`):
+
+- **Chat** — ChatGPT-style stream with code-blocks, file-attach, and
+  "apply this diff" button.
+- **Setup** — pick provider (Exo-built-in / OpenAI / Anthropic / OpenRouter)
+  via [`ai/ExoSetupPanel.tsx`](../../client/editor/ai/ExoSetupPanel.tsx) +
+  [`ai/RestSetupPanel.tsx`](../../client/editor/ai/RestSetupPanel.tsx).
+
+Server bridge: [`routes/editor/ai.ts`](../../routes/editor/ai.ts) (proxies to
+the configured provider, streams SSE back).
+
+## Mobile layout
+
+On viewports `≤ 768 px` the desktop sidebar collapses into an overlay drawer
+that slides in over the editor, and the bottom panel becomes a full-screen
+sheet pinned to a 5-button bottom nav (`.m-nav-btn`): **Files · Errors ·
+Console · Terminal · Preview**. Tap the active button again to close the
+drawer / sheet.
+
+The Files button reveals the same five sidebar tabs from desktop
+(Explorer · NPM · Git · Drive · AI) plus a close pill.
+
+## Backend routes
+
+| Route                                | Source |
+|--------------------------------------|--------|
+| `/exocore/api/editor/coding`         | File CRUD |
+| `/exocore/api/editor/runtime`        | Spawn / stop project process |
+| `/exocore/api/editor/shell`          | WS pty bridge for the terminal |
+| `/exocore/api/editor/npm`            | Search / install npm |
+| `/exocore/api/editor/pylib`          | pip equivalent |
+| `/exocore/api/editor/deps`           | Cross-package summary |
+| `/exocore/api/editor/templates`      | Template catalog (used by `capture-editor.ts` to seed `exorepo-demo` + `exorepo-py`) |
+| `/exocore/api/editor/github`         | Git ops |
+| `/exocore/api/editor/gdrive`         | Drive picker |
+| `/exocore/api/editor/ai`             | AI proxy |
+| `/exocore/api/editor/projects`       | Project CRUD |
+
+## Re-capturing the screenshots
+
+```bash
+# Both viewports (default).
+EXOCORE_CAPTURE=1 npx tsx exocore-web/scripts/capture-editor.ts
+
+# Desktop only.
+VIEWPORT=desktop EXOCORE_CAPTURE=1 npx tsx exocore-web/scripts/capture-editor.ts
+
+# Mobile only.
+VIEWPORT=mobile  EXOCORE_CAPTURE=1 npx tsx exocore-web/scripts/capture-editor.ts
+
+# Top-up the two mobile frames the main pass occasionally drops
+# (theme switch + python pylib). Each runs in its own browser context.
+EXOCORE_CAPTURE=1 npx tsx exocore-web/scripts/capture-editor-mobile-fix.ts
+```
+
+`EXOCORE_CAPTURE=1` raises the global rate-limit so the capture script can
+hit `/login`, the templates SSE endpoint, and a dozen editor routes in
+quick succession. The shipped `Start application` workflow already sets
+this; production deploys do not.

docs/github/README.md

@@ -0,0 +1,69 @@
+# GitHub integration
+
+Two surfaces:
+
+1. **Dashboard card** — shows org connection status + a "Visit Org" link to
+   `https://github.com/Exocore-Organization`.
+2. **`GithubManager` modal** ([`home/GithubManager.tsx`](../../client/home/GithubManager.tsx))
+   — full OAuth dance, repo browser, clone-into-project flow.
+3. **IDE Github pane** ([`editor/GithubPane.tsx`](../../client/editor/GithubPane.tsx))
+   — sidebar inside the editor with branch / commit / push / pull buttons.
+
+Backend route: [`routes/editor/github.ts`](../../routes/editor/github.ts).
+
+## Visual
+
+The Dashboard capture below shows the GitHub card on the social grid; the
+modal opens on top with the same dark-yellow theme.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Dashboard — desktop](../screenshots/desktop/07-dashboard.png) | ![Dashboard — mobile](../screenshots/mobile/07-dashboard.png) |
+
+## Manager modal sections
+
+```
+┌─ Connected account ───────────────────────────────┐
+│  @octocat · 142 repos · 8 orgs                    │
+│  scopes: repo, read:org, workflow                 │
+│  [ Disconnect ]                                   │
+├─ Browse repos ────────────────────────────────────┤
+│  search · filter (orgs / forks / archived)        │
+│  ┌─ row ────────────────────────────────────────┐ │
+│  │ ⭐ exocore-web   · TypeScript · 1 day ago    │ │
+│  │ [ Open in IDE ] [ Clone to project ] [ … ]   │ │
+│  └──────────────────────────────────────────────┘ │
+├─ Pending PRs / Issues ────────────────────────────┤
+│  inline preview cards                             │
+└───────────────────────────────────────────────────┘
+```
+
+## OAuth flow
+
+1. Click **Connect GitHub** → redirect to GitHub OAuth consent
+   (`scope=repo,read:org,workflow`).
+2. GitHub redirects to `/exocore/api/editor/github/callback`.
+3. Server stores access token in encrypted user record.
+4. UI re-fetches `github.status` and unlocks browse / clone actions.
+
+## IDE Github pane
+
+Lives in the left sidebar (`tab="github"`). Provides:
+
+- **Branch picker** — switch / create / delete branches.
+- **Status** — staged / unstaged / untracked files with diff preview.
+- **Commit composer** — message input + sign-off toggle.
+- **Push / pull** with conflict UI.
+- **Open repo on github.com** chip.
+
+## RPC channels
+
+| Channel | Purpose |
+|---------|---------|
+| `github.status`     | Returns `{ connected, login, scopes, repoCount }` |
+| `github.repos`      | Paginated repo list (with filters) |
+| `github.clone`      | Clones repo into a new Project Node |
+| `github.commit`     | Stages + commits selected paths |
+| `github.push`       | Pushes current branch |
+| `github.pull`       | Fetch + merge upstream |
+| `github.disconnect` | Revoke OAuth |

docs/leaderboard/README.md

@@ -0,0 +1,62 @@
+# Leaderboard — `/exocore/leaderboard`
+
+Top members across the Exocore server, ranked across three dimensions you can
+toggle in the header. Component:
+[`client/leaderboard/Leaderboard.tsx`](../../client/leaderboard/Leaderboard.tsx).
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Leaderboard — desktop](../screenshots/desktop/08-leaderboard.png) | ![Leaderboard — mobile](../screenshots/mobile/08-leaderboard.png) |
+
+## What you see in the capture
+
+The capture run shows the **live data** on this server right now (4 users):
+
+| Rank | Avatar | Nickname | Username | XP | Lv |
+|------|--------|----------|----------|----|----|
+| 🥇 1 | KA | **kaith**    | `@@skibide` | 37 XP | Lv 1 — Beginner |
+| 🥈 2 | CU | **Cute**     | `@@choruyt` | 28 XP | Lv 1 — Beginner |
+| 🥉 3 | CO | **Costanos** | `@@exocore` |  6 XP | Lv 0 — Beginner |
+| 4   | SA | **samir**    | `@@samir`   |  0 XP | Lv 0 — Beginner |
+
+The top 3 are rendered as the **podium** (large cards with halo / glow), the
+rest fall into a flat list underneath.
+
+## Header controls
+
+```
+[ XP | Level | Achievements ]   [ search… ]   [ Top 50 ▾ ]
+```
+
+- **XP / Level / Achievements** — switches the sort dimension.
+- **search** — fuzzy filter on `nickname` and `@username`.
+- **Top N** — limit dropdown: `10`, `50`, `100`, `All`.
+
+## RPC
+
+```ts
+rpc.call("xp.leaderboard", {
+   sort: "xp" | "level" | "achievements",
+   limit: 10 | 50 | 100 | -1,
+   query: string
+})
+   ↪︎ { entries: LeaderboardEntry[], total: number, generatedAt: number }
+```
+
+Backend handler lives at
+[`Exocore-Backend/src/auth/leaderboard.ts`](../../Exocore-Backend/src/auth/leaderboard.ts);
+it pulls from the encrypted user store + computes XP-to-level using the
+shared formula in `xpService.ts`.
+
+## Click behaviour
+
+Clicking any card or row calls `navigate(/u/${entry.username})` →
+[Profile](../profile/README.md).
+
+## Empty / loading
+
+| State | Render |
+|-------|--------|
+| Loading | spinner + "Crunching ranks…" |
+| No matches | "No members match `<query>`." |
+| API down | red banner + retry button |

docs/panel/README.md

@@ -0,0 +1,59 @@
+# Panel Devs Gate
+
+Every request that reaches `/exocore/*` first hits the **panel-devs gate**
+(see [`client/access/panel-devs.tsx`](../../client/access/panel-devs.tsx) +
+[`server/lib/devGate.ts`](../../server/lib/devGate.ts)).
+
+It guards the workspace with a **single master account per server**, persisted
+to `client/access/devs.json` as a salted SHA-256 hash. No request is allowed
+through to the backend hub until you hold a valid session token.
+
+## States
+
+| State | When it shows | Visual |
+|-------|--------------|--------|
+| `setup` | First time the panel is opened on this server (`devs.json` is missing) | Yellow `FIRST RUN` badge, three input form (user / pass / confirm) |
+| `login` | `devs.json` exists, no valid session token in IndexedDB | Green `READY` badge, two input form (user / pass) |
+| `authenticated` | Valid session token found | Forwards to the SPA, also paints the IP-change alarm banner |
+
+## Desktop
+
+### Setup (first run)
+
+![Panel setup gate — desktop](../screenshots/desktop/01-panel-gate.png)
+
+### After unlock (returns "Welcome back" on subsequent visits)
+
+The same screen appears with a green **READY** badge and two inputs after the
+master account is created.
+
+## Mobile
+
+![Panel setup gate — mobile](../screenshots/mobile/01-panel-gate.png)
+
+## Security highlights
+
+- One account per server — re-create by deleting `devs.json` on the host.
+- Server APIs are sealed behind this gate; un-tokenised hits are rejected.
+- Brute-force lockout: too many failed RPC `devAccess.login` calls returns
+  `429` with a `retryAfterSec` countdown that the UI displays under the form.
+- IP-change alarm — when your session's IP differs from the last known one,
+  a banner is rendered across every panel page (`PanelIpAlarm` in the same
+  file).
+- Session tokens are stored client-side in **idb-keyval** (IndexedDB) under
+  `exocore_panel_token`, so they survive reloads but never touch
+  `localStorage`.
+
+## RPC channels used
+
+| Channel | Purpose |
+|---------|---------|
+| `devAccess.status` | Returns `{ initialized: boolean }` to pick `setup` vs `login` |
+| `devAccess.setup`  | Creates `devs.json` and returns the first session token |
+| `devAccess.login`  | Validates credentials → returns a session token |
+| `devAccess.me`     | Quick "is this token still valid?" check |
+| `devAccess.session`| Returns session metadata (last IP, UA, expiry) |
+| `devAccess.logout` | Revokes the token server-side |
+
+(Implemented in
+[`server/rpc/devAccessHandlers.ts`](../../server/rpc/devAccessHandlers.ts).)

docs/profile/README.md

@@ -0,0 +1,105 @@
+# Profile — `/exocore/u/:username`
+
+The Profile view is half **Twitter-style timeline** and half **stalker page**.
+Same component renders for visitors and the logged-in user; the action row
+swaps between *post composer* (own page) and *Friend / Message* buttons
+(stalk mode).
+
+Source: [`client/profile/Profile.tsx`](../../client/profile/Profile.tsx)
+(~600 LOC, also wires post creation, comments, reactions and friend
+add/remove).
+
+---
+
+## Stalking another user — `@skibide` (3 posts, ADMIN role)
+
+| Desktop | Mobile |
+|---------|--------|
+| ![@skibide profile — desktop](../screenshots/desktop/10-profile-other.png) | ![@skibide profile — mobile](../screenshots/mobile/10-profile-other.png) |
+
+## Top contributor — `@exocore` (the OWNER)
+
+| Desktop | Mobile |
+|---------|--------|
+| ![@exocore profile — desktop](../screenshots/desktop/09-profile-self.png) | ![@exocore profile — mobile](../screenshots/mobile/09-profile-self.png) |
+
+---
+
+## Anatomy
+
+```
+┌─ ← Back to Dashboard ──────────────────────────────┐
+│  Cover banner (gradient) ──────────────────────────│
+│        ┌──────────┐                                │
+│        │  Avatar  │  Nickname     [ROLE chip]      │
+│        └──────────┘  @username                     │
+│                       Lv N · Title · Posts · Friends · 🏳 country │
+│                       ID xxx · PLAN xxx · STATUS verified         │
+│                       [bio one-liner]                              │
+│                       [XP progress bar  N XP · K to Lv N+1]        │
+│                       [achievement chips]                          │
+├─ Post composer (own only) ─────────────────────────│
+│  textarea  +  📎 image  +  [Post]                  │
+├─ Feed (most-recent first) ─────────────────────────│
+│  ┌── post card ──────────────────────────────────┐ │
+│  │ avatar  nickname                              │ │
+│  │ N {timeAgo}                                   │ │
+│  │ markdown body (with code blocks)              │ │
+│  │ optional image                                │ │
+│  │ ❤ 12  😂 3  💀 1     💬 N comments            │ │
+│  │   [reactions row · click to toggle]           │ │
+│  │   [comment composer + thread]                 │ │
+│  └────────────────────────────────────────────────┘ │
+│  … more posts …                                    │
+└────────────────────────────────────────────────────┘
+```
+
+## RPC channels
+
+| Channel | Purpose |
+|---------|---------|
+| `posts.profile`        | Fetch user + their posts |
+| `posts.create`         | New post (text + optional file) |
+| `posts.delete`         | Soft-delete own post |
+| `posts.comment`        | Append comment to a post |
+| `posts.react`          | Toggle reaction emoji |
+| `social.friend`        | Add / remove friend (`action`: `'add' \| 'remove'`) |
+| `xp.catalog`           | Achievement chip metadata (icon + label) |
+
+## Stalk-mode buttons
+
+When the URL `:username` ≠ the logged-in user's `@username`, the composer is
+hidden and these chips appear under the header:
+
+- **+ Friend** (or **✓ Friends · Remove** if already mutual)
+- **💬 Chat** — opens a DM directly inside `SocialPanel` (sets `activeDM` and
+  switches the bottom-bar tab to `'dms'`)
+- **🚫 Block** (only visible for moderators / owner role)
+
+## Posts schema (server side)
+
+```ts
+interface Post {
+  id: string;                       // post_<ms>_<rand>
+  ts: number;                       // epoch ms
+  author: string;                   // "@exocore"
+  imageUrl?: string | null;
+  imageFileId?: string | null;
+  text: string;                     // markdown
+  comments: Comment[];
+  reactions: Record<string, string[]>; // emoji ⇒ usernames
+  deleted?: boolean;
+}
+```
+
+(Stored on the backend at `Exocore-Backend/local-db/posts.json`, mirrored to
+Google Drive.)
+
+## Empty / error states
+
+| State | Render |
+|-------|--------|
+| Loading | spinner + "Loading profile…" |
+| 404     | "User not found." with **← Back to dashboard** link |
+| Banned  | "This account has been suspended." |
+| No posts| "No posts yet." underneath the header |

docs/projects/README.md

@@ -0,0 +1,76 @@
+# Project Nodes
+
+A **Project Node** is one isolated workspace inside the panel. Every node has
+its own filesystem, run command, env vars, package manager state, and live
+runtime stats. The Dashboard renders them as cards
+([`home/ProjectNodeCard.tsx`](../../client/home/ProjectNodeCard.tsx)) and the
+manager modal ([`home/FileManager.tsx`](../../client/home/FileManager.tsx))
+lets you create / archive / delete / browse them.
+
+## Visual
+
+The Dashboard capture below shows where the project grid lives (top of the
+"Project Nodes" section). Without an active user account it redirects to
+login — sign in to see live cards.
+
+| Desktop | Mobile |
+|---------|--------|
+| ![Dashboard — desktop](../screenshots/desktop/07-dashboard.png) | ![Dashboard — mobile](../screenshots/mobile/07-dashboard.png) |
+
+## Card anatomy
+
+```
+┌───────────────────────────────┐
+│  ▦ project-name      [⋮]      │
+│  language · template          │
+├───────────────────────────────┤
+│  status: Running / Idle /…    │
+│  CPU 7 %  ·  RAM 142 MB       │
+├───────────────────────────────┤
+│   [ Open ]   [ Run ]   [ ⋮ ]  │
+└───────────────────────────────┘
+```
+
+Card actions:
+
+- **Open** → `navigate(/editor?project=${id})` (deep-links into the IDE)
+- **Run** → POST `editor/runtime/start`
+- **⋮ menu** → Rename · Stop · Restart · Archive · Delete · Duplicate
+
+## Create wizard
+
+Triggered by the `+ New Project` quick action. Steps:
+
+1. **Pick a template** —
+   `editor/templates` provides Node.js, Python, Static HTML, React/Vite,
+   Express, Flask, Next.js, Vanilla, "Empty".
+2. **Name + slug** — auto-slugged with collision detection.
+3. **Select runtime** — Node 20 / 22, Python 3.10 / 3.11 / 3.12, Bun, Deno.
+4. **Initial files** — preview tree from the template; allow tweaks.
+5. **Confirm + create** → spawns project under `exocore-web/uploads/<id>/`,
+   records metadata in `editor/projects` and navigates straight into it.
+
+Source: [`home/CreateProjectWizard.tsx`](../../client/home/CreateProjectWizard.tsx).
+
+## File manager modal
+
+Opened from `Quick Actions → Project Nodes`. Shows:
+
+- All nodes (active + archived) with sort by name / last opened / size.
+- Storage quota bar (per plan: free 1 GB, pro 10 GB, owner unlimited).
+- Bulk actions: archive, restore, delete, export ZIP.
+
+## Backend routes used
+
+| Route | Verb | Source |
+|-------|------|--------|
+| `/exocore/api/editor/projects`            | GET  | List projects |
+| `/exocore/api/editor/projects`            | POST | Create project |
+| `/exocore/api/editor/projects/:id`        | PATCH | Rename / archive |
+| `/exocore/api/editor/projects/:id`        | DELETE | Delete |
+| `/exocore/api/editor/runtime/start`       | POST | Spawn process |
+| `/exocore/api/editor/runtime/stop`        | POST | SIGTERM |
+| `/exocore/api/editor/runtime/stats`       | GET  | CPU / RAM tick |
+
+(Wired in [`routes/editor/projects.ts`](../../routes/editor/projects.ts) and
+[`routes/editor/runtime.ts`](../../routes/editor/runtime.ts).)