review Visibility internal Owner erik@uvilo.com Approver _ Created 2026-06-24 Updated 2026-06-24

LibreChat Removal Plan 2

Scope: Rewrite the six Forge Knowledge files identified in Spec §2 so they describe the current uvilo-mono / forgentic architecture and contain no residual references to the former stack. This Plan covers Knowledge files only. Do not update Skills, archive MongoDB, remove obsolete files, or run the final all-published-file grep in this Plan; those are covered by Plans 1 and 3.

Shared edit rule for every task: Preserve frontmatter and current document purpose where possible, but remove or replace every reference to the former runtime, librechat.yaml, forge-spawn, former agent definitions, former chat history, former Docker images, and /workspace/librechat. After editing each file, run a file-local grep for librechat, LibreChat, forge-spawn, and librechat.yaml; the grep must return no hits for that file before continuing.

Task 1 — Update Forge/README.md

Spec §2: Forge/README.md has no LibreChat references.

Edit Forge/README.md in this order:

Read the whole file once and note the current section order.
Replace the entire section ## 1. How to Access LibreChat with a new ## 1. How to Access Forge Chat section.
1. Keep the section procedural and user-facing.
2. Describe access through the current Forge Chat / Bot interface.
3. Do not mention the former chat product, former model picker, or former runtime.
In ## 3. Where Files Go, replace the Forge/Configs/ bullet.
1. Remove the phrase that says the folder contains former runtime config.
2. Replace it with content that says this folder contains current service configuration, MCP server configuration, and infrastructure references.
In ## 6. What to Do When You're Stuck, replace the urgent-infrastructure sentence.
1. Remove the parenthetical example that names the former runtime as the thing that is down.
2. Replace it with a current example such as forgentic, uvilo-mono, Railway, or deployment health being broken.
Run grep -niE 'librechat|forge-spawn|librechat\.yaml' Forge/README.md.
If the grep returns any hits, repeat the targeted replacement steps above until it returns no hits.
Build to verify after the file is clean.

Task 2 — Rewrite Forge/Forge_Setup.md

Spec §2: Forge_Setup.md describes deploying uvilo-mono (bot-craft) on Railway, not LibreChat.

This is the largest Knowledge rewrite. Edit Forge/Forge_Setup.md in this order:

Read the whole file and keep the frontmatter, title, and broad setup/rebuild purpose.
Replace ## Execution Contexts.
1. Replace the row that says the agent runs inside the former Railway container.
2. The replacement row should say the Forge agent operates in the current forgentic / uvilo-mono Railway environment and invokes shell work through forge-bash__run and tool work through attached MCP tools.
Rewrite ## Part A: Disaster Recovery — What to Back Up before editing the rebuild steps.
1. Replace ### 1. MongoDB Data with a current application-data backup section for the uvilo-mono / bot-craft runtime. Do not preserve MongoDB as a required Forge runtime backup unless another current source proves it is still active.
2. Keep ### 2. Typesense Index only as a Typesense backup/reindex section; replace any wording that says indexing scripts run inside the former container with wording that says they run through the current repo tooling or forge-bash__run.
3. Replace ### 3. Railway Persistent Volume (/workspace) with a current workspace/runtime persistence section. Delete the rows for /workspace/librechat/.secrets and /workspace/librechat/librechat.yaml; replace them with environment-variable and current service configuration notes.
4. Replace ### 4. Docker Image with a uvilo-mono / bot-craft Railway service build/deploy section. Delete the former image name, former Dockerfile path, and former startup script path.
5. Replace ### 5. Railway Environment Variables so it describes environment variables on the forgentic container as the source of credentials and configuration.
6. Replace the DNS row for the former chat subdomain with current domains that remain active, such as the OS/docs site and current service domains.
7. Replace ### 8. Railway Backup Summary so it lists only current Railway services and current backup responsibilities.
Rewrite ## Part B: Step-by-Step Environment Rebuild after Part A is current.
1. Keep ### Prerequisites and ### Step 1: Railway Project Setup **[Agent]**, but remove any prerequisite that points to former runtime config or former secrets files.
2. Delete ### Step 2: MongoDB Service **[Agent]** if it only supports the former stack. If a current database is required, replace the section with the current database service and its environment variables.
3. Replace the entire section ### Step 3: LibreChat Service (Custom Image) with ### Step 3: uvilo-mono / bot-craft Service **[Agent]**.
  1. Delete #### 3a. Build and Push the Docker Image **[Operator]** and its GHCR commands for the former image.
  2. Replace #### 3b. Create the Railway Service **[Agent]** with steps for the current Railway service, current source image/build source, current start command, and current public/internal URLs.
  3. Keep the TypeScript build concept from #### 3b½. TypeScript Build (Automatic) **[Agent]**, but update it so it references current MCP/server TypeScript build needs and not former bundled servers.
  4. Replace #### 3c. Set Environment Variables **[Agent]** with current uvilo-mono / forgentic environment variables and remove CONFIG_PATH, former auth encryption variables, and former config-path examples unless they are still current under new names.
  5. Delete #### 3d. Seed .secrets **[Agent]**; replace it with a short step explaining that credentials are supplied through Railway environment variables on the forgentic container.
  6. Delete #### 3e. Seed Deployed Config **[Agent]**; replace it with current Bot/MCP configuration deployment steps and no YAML-copy procedure.
  7. Keep ### Step 3f: Set GitHub Repository Secrets **[Operator]** only if the listed secrets are still needed; otherwise replace the list with current GitHub Actions and deployment secrets.
4. In ### Step 4: Typesense Service **[Agent]**, replace the bullet that says indexing scripts run inside the former container with current repo tooling or forge-bash__run wording.
5. In ### Step 5: Playwright MCP Service **[Agent]**, keep the current service instructions but remove any coupling to the former runtime or former credential file.
6. Replace ### Step 6: Admin Panel Service **[Agent]** if it describes the former admin panel. Either delete it or replace it with current admin/operator access for uvilo-mono / bot-craft.
7. In ### Step 7: DNS Configuration **[Operator]**, delete the former chat subdomain row and keep only current DNS entries.
8. In ### Step 9: Create User Account **[Agent]**, replace former account creation with current Bot/user access setup or delete the section if account creation is no longer an infrastructure rebuild step.
Rewrite ## Part C: Operational Gotchas after the rebuild procedure is current.
1. Keep generic Railway gotchas that remain true.
2. Delete or replace each former-runtime-specific gotcha in this order: Railway Volume Mount Hides Image Contents, Dockerfile USER node Breaks Volume Write Access, node:22-slim Missing ca-certificates, Docker Build Platform Must Match Railway, Railway Internal Networking May Be Refused Between Containers, Seed MongoDB via PyMongo, Not mongodump/mongorestore, and Railway Env Vars NOT in os.environ.
3. For the environment-variable gotcha, replace it with current guidance for reading variables from the forgentic Railway environment when needed.
Rewrite ## Part D: Post-Setup Verification Checklist last.
1. Replace ### LibreChat Application with a uvilo-mono / bot-craft runtime health section.
2. Replace former Admin Panel checks with current admin/operator checks or delete them if no current admin panel exists.
3. Replace MCP server checks so they verify current attached/deferred MCP tools rather than former chat MCP status.
4. Replace environment-variable checks so they verify current Railway environment variables, not former counts, former files, or former credential keys.
5. Replace backup checks so they list only current services.
Run grep -niE 'librechat|forge-spawn|librechat\.yaml|/workspace/librechat' Forge/Forge_Setup.md.
If the grep returns any hits, edit the named sections again until it returns no hits.
Build to verify after the file is clean.

Task 3 — Rewrite Forge/Forge_Infrastructure.md

Spec §2: Forge_Infrastructure.md shows the current service architecture with uvilo-mono as the runtime, not LibreChat.

Edit Forge/Forge_Infrastructure.md in this order:

Read the whole file and keep the frontmatter, title, and purpose as the current infrastructure reference.
Replace ## Architecture completely.
1. Remove the former runtime service, former config path, former secrets path, former RAG image, former admin panel image, former API links, former chat history, and former sub-agent launcher.
2. Replace the tree with the current architecture: Railway project, forgentic / uvilo-mono runtime, Bot execution, orchestrator Hono service, current MCP tool attachment/deferred-tool model, Typesense, Playwright MCP, Vercel docs site, and current data stores.
Replace the explanatory paragraphs immediately after ## Architecture.
1. Delete former Docker registry examples that use former images.
2. Replace the config deployment model with Bot/MCP configuration and environment-variable configuration.
3. Replace the startup model with the current forgentic / uvilo-mono Railway startup model.
Update ## Railway IDs.
1. Delete the row for the former service ID.
2. Add or keep only rows for current services that can be verified from the current infrastructure state.
3. If a current service ID cannot be verified, omit that row instead of preserving obsolete data.
Replace ## Environment Variables and ## Secrets File.
1. Keep current guidance for reading Railway environment variables.
2. Delete the former secrets-file path and former credential-key list.
3. Replace them with current environment-variable names and tool-specific credential access guidance.
Replace ## Manual Operations.
1. Delete ### Updating LibreChat to a New Version and every former image build step underneath it.
2. Add current deployment/update steps for uvilo-mono / bot-craft and current Railway services.
3. Keep SSH/Railway access instructions only after removing former service names and former filesystem paths from examples.
Replace ## Common Operations.
1. Delete the second ### Updating LibreChat to a New Version section.
2. Replace ### Deploying Config Changes so it describes current Bot/MCP/environment-variable deployment and current Railway redeploy behavior.
3. Update ### User Management to current user/Bot access if it is still needed.
Replace ## Admin Panel if it documents the former admin panel.
1. Delete former image, URL, env vars, and former auth model.
2. Add current admin/operator surface if one exists; otherwise remove the section.
In ## Vercel — Documentation Site, replace any bypass-token source that points to the former secrets file with environment-variable-based access.
In ## Typesense, replace former container/env-var wording with current forge-bash__run or indexing-script wording.
In ## MCP Server Details, keep current MCP server names but remove former transport/container wording.
Replace ## MCP Development Notes.
1. Keep generic schema compatibility guidance.
2. Replace ### LibreChat Runtime Behavior with a current ### forgentic Runtime Behavior section.
3. Delete former config-validation and ModelSpecs notes.
Replace the later infrastructure-reference sections in this order: ## Persistent Volume Structure, ## Docker Image Build, ## Environment Variable Locations, ## Image Details, ## Debian-slim Container Notes, and ## Lessons Learned.
1. Delete former image names, former Dockerfile path, former startup script path, former volume path, former YAML/env substitution model, and former lessons.
2. Replace them with current uvilo-mono / forgentic equivalents.
Run grep -niE 'librechat|forge-spawn|librechat\.yaml|/workspace/librechat|Ralph Wiggum|ModelSpecs' Forge/Forge_Infrastructure.md.
If the grep returns any hits, edit the named sections again until it returns no hits.
Build to verify after the file is clean.

Task 4 — Rewrite Forge/Forge_Agent_Architecture.md

Spec §2: Forge_Agent_Architecture.md describes the Bot model, not LibreChat agent definitions, ModelSpecs, or sync scripts.

Edit Forge/Forge_Agent_Architecture.md in this order:

Read the whole file and keep the frontmatter, title, and purpose as an architecture reference for Forge agents.
Replace ## Three-Layer Prompt Pipeline.
1. Remove the former memory-injection layer.
2. Replace the pipeline with the current Bot prompt model: Bot configuration, modular Prompt and ChildPrompt composition, model selection, tool access, and runtime context.
Replace ## Forge_Chat_Prompt.md as Inlined Agent Instructions.
1. Delete the former deployment sentence that says a skill copies prompt text into former agent instructions.
2. Replace it with current Bot prompt/version management and Bot system prompt configuration.
Rewrite ## Memory Architecture.
1. Keep ### File-Based Memory (Shared / Team-Scoped) if still current.
2. Replace ### LibreChat Per-User Memory with a current section about user/conversation context in uvilo-mono.
3. Keep the rule that project state belongs in project files, Skills, Knowledge, and durable reports rather than ephemeral chat memory.
Replace the entire ## Agent Sync Architecture section with ## Bot Configuration Architecture.
1. Delete ### Overview, ### Key Files, ### How It Works, ### Multi-Family Agent Sync, ### Master + Clone Pattern, ### Agent CRUD API Gap, and ### ACL Requirement if they depend on former agent definitions, sync scripts, or former REST API gaps.
2. Replace them with procedural Bot configuration concepts: Bot identity, prompt tree, model selection, tool attachments, access control, and deployment/update flow.
Update ### SRP Agent Architecture.
1. Replace invocation through the former sub-agent launcher with invocation through the current spawnAgent tool and orchestrator.
2. Keep the single-responsibility and least-privilege principles.
Update ### Adding a New Model.
1. Delete the step to add a ModelSpecs entry to the former YAML file.
2. Replace it with current model availability and Bot configuration steps.
Update ### Adding a New SRP Agent.
1. Delete the step to add a ModelSpecs entry to the former YAML file.
2. Replace it with steps to create or update the Bot, assign prompt text/ChildPrompts, assign tools, and test via spawnAgent or direct chat.
Update ## Artifact Instructions.
1. Replace any row that names a former artifact-instructions field.
2. Replace it with the current artifact tool/instruction mechanism.
Run grep -niE 'librechat|forge-spawn|librechat\.yaml|ModelSpec|ModelSpecs|Ralph Wiggum' Forge/Forge_Agent_Architecture.md.
If the grep returns any hits, edit the named sections again until it returns no hits.
Build to verify after the file is clean.

Task 5 — Rewrite Forge/Forge_Agent_Orchestration.md

Spec §2: Forge_Agent_Orchestration.md describes the orchestrator → uvilo-mono execution path, not forge-spawn or LibreChat conversation transcripts.

Edit Forge/Forge_Agent_Orchestration.md in this order:

Read the whole file and keep the frontmatter, title, and purpose as the orchestration reference.
Replace ## Requirements Summary.
1. Replace the cron row with Inngest schedules → orchestrator → uvilo-mono / Bot execution.
2. Replace the sub-agent row with spawnAgent.
3. Replace the monitor row with current AgentJob status, async completion, checkAgentJob, abortAgent, and any current reaper behavior.
Replace ## Execution Layer — LibreChat UI Chat API with ## Execution Layer — uvilo-mono Bot API.
1. Replace ### Invocation Protocol with current API-key-authenticated conversation creation and chat execution.
2. Replace ### Support Endpoints with current uvilo-mono endpoints or tooling used by the orchestrator.
3. Replace ### Persistence so conversations and AgentJobs point to current uvilo-mono persistence, not former chat history.
4. Replace ### SSE Event Types and ### Auth Lifecycle with current streaming/status and API-key auth behavior.
5. Keep parameter-control guidance only after updating it for current model override and Bot execution.
6. Delete ### Why Not the OpenAI-Compatible API if it is only about the former runtime; replace it only if there is a current reason to document.
Update ## Orchestrator Service — Dispatcher.
1. Keep the TypeScript/Hono Railway service concept.
2. Replace every former-runtime authentication step with API-key auth to uvilo-mono.
3. Replace ### JWT Auth Manager with a current API-key or service-auth section.
4. Replace ### Hybrid Migration Path with a current-state note that the migration to uvilo-mono is complete.
Update ## Discovery MCP Server.
1. Replace configuration through the former YAML file with current Bot/tool attachment or deferred-tool configuration.
2. Replace former-container transport wording with current tool execution wording.
Replace ## Sub-Agent Spawning — forge-spawn MCP with ## Sub-Agent Spawning — spawnAgent Tool.
1. Replace the description with the current spawnAgent behavior: sync mode waits for a result, async mode creates an AgentJob, model overrides are supported, and completionEvent can trigger workflows.
2. Replace ### Spawn Tool Parameters with current spawnAgent parameters.
3. Replace ### Transcript Review with current conversation/AgentJob review links and durable project reports.
Replace ## Ralph Wiggum Monitor.
1. Delete the former monitor name and former restart behavior.
2. Add current async job monitoring, checkAgentJob, abortAgent, timeout/reaper, and restart/continuation behavior if available.
Update ## Agent Types, ## Agent Handoffs, ## Cron Scheduling, and ## Data Storage.
1. Replace former sub-agent launcher references with spawnAgent.
2. Replace former handoff mechanism with current Bot handoff/routing behavior.
3. Replace MongoDB conversation-history wording with current uvilo-mono conversation persistence.
4. Keep filesystem, Postgres, Typesense, and durable report guidance if current.
Replace or delete ## Agent CRUD API Notes if it only documents former API gaps.
Run grep -niE 'librechat|forge-spawn|librechat\.yaml|Ralph Wiggum|MongoDB \(Conversation History\)' Forge/Forge_Agent_Orchestration.md.
If the grep returns any hits, edit the named sections again until it returns no hits.
Build to verify after the file is clean.

Task 6 — Rewrite Forge/Forge_Agents_User_Guide.md

Spec §2: Forge_Agents_User_Guide.md references the current Bot system and tooling, not forge-spawn, librechat.yaml, or LibreChat chat history.

Edit Forge/Forge_Agents_User_Guide.md in this order:

Read the whole file and keep the frontmatter, title, and human-facing guide purpose.
In ## Current Workflows, update ### Project Workflow.
1. Replace the step that says the runner spawns an agent through the former launcher.
2. The replacement step should say the runner spawns or hands off to Bots through the current spawnAgent / orchestrator path.
In ## Agent Reference, update ### Spawning an Agent Directly.
1. Replace the former tool name and former MCP label with the current spawnAgent tool name.
2. Replace disconnect/monitor examples with current sync and async examples.
3. Replace the former monitor example with current async job monitoring using checkAgentJob.
Update ### Checking Job Status and ### Aborting a Job.
1. Replace former conversation-status wording with current AgentJob and uvilo-mono conversation status.
2. Replace former abort wording with current abortAgent behavior.
In ## Creating New Workflows, update ### 2. Choose the Agent.
1. Delete the step to add a ModelSpecs entry to the former YAML file.
2. Replace it with current Bot creation/update, prompt configuration, model selection, and tool assignment.
In ## Scheduling Agent Execution, update ### Monitoring and Troubleshooting.
1. Replace stuck-job cleanup tied to the former runtime with current AgentJob/reaper behavior.
2. Replace former transcript viewing with current conversation/AgentJob review and persisted project reports.
In ## Architectural Notes, replace ### Hybrid Migration Path.
1. Remove roadmap wording that assumes the former runtime is still the execution layer.
2. Replace it with a current-state note that orchestration targets uvilo-mono / Bots.
Run grep -niE 'librechat|forge-spawn|librechat\.yaml|Ralph Wiggum|ModelSpecs' Forge/Forge_Agents_User_Guide.md.
If the grep returns any hits, edit the named sections again until it returns no hits.
Build to verify after the file is clean.