Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Uvilo OS State

Status

Complete

Output Summary

  • Uvilo_OS_Requirements.md — requirements document
  • Uvilo_OS_Research.md — architecture research, platform decisions, and agentic execution research
  • Uvilo_OS_Spec.md — full design spec (15 sections)
  • Uvilo_OS_Plan_Infrastructure.md — Railway deployment plan (volumes, MCP servers, LibreChat config)
  • Uvilo_OS_Typesense_Research.md — Typesense semantic search research and implementation plan
  • Uvilo_OS_TinaCMS_Research.md — TinaCMS implementation research
  • Uvilo_OS_Playwright_MCP_Research.md — Playwright MCP browser research and deployment decision
  • Uvilo_OS_Plan_Trash_MCP.md — uvilo-trash MCP server design plan (safe delete via .trash/)
  • Uvilo_OS_Plan_Shell.md — uvilo-shell MCP server design plan (bash execution, two-layer architecture, permissions system)
  • Uvilo_OS_SurveyMonkey_MCP_Research.md — SurveyMonkey MCP research, Composio decision, configuration, and migration plan
  • Playwright MCP sidecar service on Railway (headless Chromium, serverless, private network)
  • Config deployment model: /workspace/librechat/ (deployed) separated from git working copy
  • MCP filesystem expanded to full /workspace volume access
  • GitHub repo live at https://github.com/ErikDakoda/uvilo-os (private)
  • Full folder restructure of uvilo-os/ completed and committed
  • Custom Docker image ghcr.io/erikdakoda/librechat-git:latest — LibreChat + git
  • MCP infrastructure validated end-to-end (branch → edit → stage → commit → push)
  • Astro Starlight site in .internal/ — deployed to Vercel
    • Preview: os.uvilo.com (dev branch, every push triggers deploy)
    • Production domain removed (free-tier Standard Protection covers previews only)
    • Vercel Authentication enabled (Uvilo team members only)
    • Uvilo logo (light/dark), brand colors, Pagefind search
  • GitHub Actions: CI/CD deploy to GitHub Pages on merge to main + stale branch cleanup (weekly)
  • Branch protection on main (PRs required, no direct pushes)

Todo

Repository structure

  • Define department structure (Architecture, Content, Design, Finance, etc.)
  • Define naming conventions (Title_Case, project-prefix, schema/script/prompt rules)
  • Define project folder layout (Requirements, Research, Spec, State, subfolders)
  • Define State document standard
  • Define frontmatter standard (including optional version field)
  • Execute full folder restructure
  • Run compliance check and fix all violations
  • Commit to GitHub (github.com/ErikDakoda/uvilo-os)

Assistant infrastructure

  • Migrate Knowledge/, Skills/, Lessons.md to uvilo-os/Assistant/
  • Update instructions.md — split Dropbox (Jobs/Archive) vs GDrive (Knowledge/Skills/Lessons)
  • Delete redundant Dropbox copies of Knowledge/, Skills/, lessons.md
  • Add Create_New_Version skill

Infrastructure — editing (see Plan Infrastructure)

  • Install and authenticate Railway CLI
  • Inspect current LibreChat Railway setup (services, variables, config)
  • Write infrastructure implementation plan
  • Verify container: Alpine 3.23, node 20.20.1, npx 10.8.2, python3 3.12, uvx ✓
  • Create Railway persistent volume (/workspace, 5GB)
  • Configure git clone at startup (/workspace/startup.sh)
  • Custom Docker image (ghcr.io/erikdakoda/librechat-git:latest) — LibreChat + git
  • MCP filesystem server: 14 tools (read, write, edit, list, search, etc.)
  • MCP git server (mcp-server-git via uvx): 12 tools
  • MCP git-remote server (uvilo-git-push.py): 4 tools (push, push_new_branch, pull, fetch)
  • Update CONFIG_PATH to /workspace/librechat/librechat.yaml (separated from git working copy)
  • Validate end-to-end: branch → edit → stage → commit → push via LibreChat ✅

Infrastructure — publishing

  • Astro Starlight in .internal/ (glob loader from parent dir, custom Uvilo frontmatter schema)
  • Sidebar with organized Architecture groups + all 11 department sections
  • Landing page with hero
  • Uvilo logo (light/dark variants), brand accent colors, favicon
  • Pagefind full-text search
  • GitHub Actions: deploy to GitHub Pages on merge to main (withastro/action@v5)
  • GitHub Actions: stale branch cleanup (weekly cron, 30-day threshold)
  • Branch protection on main (require PR, no direct pushes)
  • Vercel project: framework Astro, root directory .internal/, include files outside root
  • Vercel Authentication enabled (Standard Protection — team members only)
  • dev branch created as daily working branch
  • Custom domain os.uvilo.com pointed to dev branch preview deployments
  • DNS: CNAME os → Vercel — Done
  • Starlight plugins installed and configured:
    • starlight-theme-nova (modern theme — colors TBD via Starlight color editor)
    • starlight-llms-txt (generates /llms.txt, /llms-full.txt, /llms-small.txt)
    • starlight-auto-sidebar (sidebar group customization)
    • starlight-giscus (GitHub Discussions comments — working, custom Pagination override to coexist with Nova theme)
    • astro-vtbot/viewTransitions (browser-native cross-document view transitions)
    • astro-mermaid (mermaid diagram rendering in markdown code blocks)
  • Custom markdown plugins in .internal/src/plugins/:
    • remark-resolve-relative-links.mjs — rewrites relative .md links to Starlight route URLs at build time
    • rehype-external-links.mjs — adds target="_blank" rel="noopener noreferrer" to external links
  • Astro 5.18.0, Starlight 0.37.7 — all dependencies pinned to exact versions (no caret ranges)
  • GitHub Discussions enabled on uvilo-os repo
  • Install giscus GitHub App on uvilo-os repo
  • Sidebar groups collapsed by default
  • Department home pages added for all 11 departments (renamed from index.md to .md)
  • Removed starlight-plugin-icons + UnoCSS (icons only work on page links, not sidebar groups)
  • Removed starlight-site-graph (ships micromatch to browser client bundle; Node.js builtins cause runtime errors)
  • Fixed astro dev errors (glob loader base: '..' caused Vite watcher issues; added exclusion patterns)
  • Solve broken links between pages (custom remark plugin: remark-resolve-relative-links.mjs)
  • External links open in new tab (custom rehype plugin: rehype-external-links.mjs)
  • Address failed generation

Agentic execution system (see Spec §12, Research §Agentic)

  • Define project state file conventions (State.md with [STARTED]/[BLOCKED] prefixes)
  • Define session log format (session_log.md with compressed session summaries)
  • Define working log format (working_log.md as running scratchpad)
  • Update Requirements, Research, Spec, and State docs with new architecture
  • Update instructions.md to support project-based execution alongside job-based
  • Create session_log.md and working_log.md for Uvilo_OS_Architecture as pilot project
  • Add [STARTED]/[BLOCKED] prefixes to existing State documents as needed

LibreChat configuration

  • Update instructions.md to use tools available in Railway cloud environment
  • Browser usage on Railway instance — Playwright MCP sidecar deployed and verified working (navigate, snapshot, screenshot, click, form fill, authenticated login to uvilo.ai via .secrets file). See Research
  • User creation — documented in Setup doc (railway ssh + npm run create-user)
  • LibreChat MCP configuration
    • Linear — @touchlab/linear-mcp-integration (env LINEAR_ACCESS_TOKEN) — verified: searched issues, returned UVI-121/127/128
    • Neon — @neondatabase/mcp-server-neon (API key as CLI arg) — verified: listed uvilo project
    • Vercel — working (API key as CLI arg, teamId=uvilo in server instructions)
    • Context7 — @upstash/context7-mcp (no auth required) — verified: resolved library IDs
    • GitHub — @modelcontextprotocol/server-github (env GITHUB_PERSONAL_ACCESS_TOKEN) — verified: listed commits
    • Notion — @notionhq/notion-mcp-server (env NOTION_TOKEN) — verified: tools loaded
    • SurveyMonkey MCP via Composio Platform — 5 tools loaded (GET_GROUPS, GET_BULK_CONTACTS, LIST_BENCHMARK_BUNDLES, CREATE_SURVEY_FOLDER, DELETE_SURVEY), all returning HTTP 200 ✅. See Research
    • Railway MCP — @jasontanswe/railway-mcp (note: no hyphens in npm scope), RAILWAY_API_TOKEN env var — verified: listed uvilo-libre-chat project + all 6 services ✅
    • PostHog MCP — official remote SSE via mcp-remote proxy, POSTHOG_API_KEY env var — verified working ✅
    • SuprSend MCP — root cause found and fixed: SuprSend CLI v0.2.19 / mcp-go v0.44.1 has a bug in list_workflows where workspace is defined twice with Required(), producing required: ["workspace", "limit", "mode", "workspace"]. JSON Schema 2020-12 §6.5.3 mandates unique items → Claude’s API rejects it. Fixed in suprsend-mcp-proxy.py by adding required array deduplication to _fix(). Verified: 22 tools loaded via tool_search with no crash ✅
  • uvilo-trash MCP server — safe file/directory deletion via .trash/ (see Trash MCP Plan)
    • Implement uvilo-trash.py (6 tools: trash_file, trash_directory, untrash_file, untrash_directory, list_trash, empty_trash)
    • Add uvilo-trash to librechat.yaml and deploy config
    • Verify 5/6 tools in new conversation: trash_file, trash_directory, untrash_file, untrash_directory, list_trash — all working ✅
    • Verify empty_trash(older_than_days=0) — fix confirmed working; wiped 10 items ✅
    • Empty current .trash/ — verified empty ✅
    • Update instructions.md with trash server documentation
  • uvilo-shell MCP server — bash execution with two-layer architecture and permissions (see Shell Plan)
    • Implement uvilo-shell.py (single run(command, grant?) tool, chain parser, Layer 1/2 architecture, permissions system)
    • Create Assistant/Configs/shell-permissions.yaml (initial allowed list)
    • Add uvilo-shell to librechat.yaml and deploy config
    • Update instructions.md with uvilo-shell tool docs and session procedures (start check, end-session steps)
    • Verify in new conversation: run simple command, test permission request, test Session and Always grants
  • Back up custom uvilo-git-remote FastMCP server script
  • /preview command — iframe artifact with header bar (branch, status, GitHub/Vercel links)
  • Embed mode (?embed=1 + cookie) — suppresses giscus in iframes to avoid CSP errors
  • /preview wait for build — polls Vercel deployment until READY before rendering (max 6 polls)
  • /preview CSS extraction — moved inline styles to external stylesheet (os.uvilo.com/preview-bar.css)
  • Recursion limit increased to 100 (was 50) — endpoints.agents.recursionLimit in librechat.yaml
  • Deferred MCP tools — researched and configured: 10 core tools always loaded, ~70+ deferred via ToolSearch

Artifact dashboard system (see Skills/Git_Status/)

  • Build /git-status React artifact with dark mode toggle
  • Test dark mode detection in CodeSandbox iframe (prefers-color-scheme only)
  • Discover shadcn/Tailwind dark: doesn’t work in artifact iframe — switch to inline styles
  • Identify streaming performance problem (~400 lines = 1-2 min to render)
  • Design hosted approach: Astro page + base64 hash data + tiny iframe artifact
  • Test iframe embedding (X-Frame-Options blocks, bypass token works)
  • Store Vercel protection bypass token in .secrets
  • Build hosted dashboard page (.internal/src/pages/artifacts/git-status.astro)
  • Update vercel.json with frame-ancestors for /artifacts/*
  • Create tiny iframe template (template.html)
  • Merge to dev — os.uvilo.com serves /artifacts/git-status
  • Test full /git-status command end-to-end (iframe artifact → hosted page) ✅
  • Fix Astro CSS scoping (<style is:inline> required for dynamic HTML)
  • Dark mode toggle works on hosted page (CSS custom properties + data-theme)
  • --commits N / -c N option (default 0, section hidden when empty)
  • GitHub Diff link (compare branch vs dev, or show HEAD commit on dev)
  • Vercel button styling fixed (secondary style with visible border)
  • Added 7 missing pages to sidebar (Uvilo OS: History, WIP, 3 research docs; Assistant: instructions.md, README.md)
  • Added frontmatter to Assistant/instructions.md and Assistant/README.md
  • Updated content.config.ts glob patterns for new Assistant files