archived Visibility internal Owner erik@uvilo.com Approver _ Created 2026-04-14 Updated _

Forge Skills 2 Spec

Implementation specification based on decisions in Forge_Skills_2_Research.md. Tasks are ordered by dependency and grouped into phases.

Phase 1: FORGE.md Quick Fixes

Low-risk changes to FORGE.md that address the most impactful problems immediately.

1.1 Add Deferred Tools List (R1)

File: Forge/Assets/FORGE.md (or Forge/FORGE.md if restructuring not yet done)

Replace the current ToolSearch line in ENVIRONMENT & AUTHORITY with:

- **Deferred tools / ToolSearch**: Most MCP tools are deferred (not loaded into context).
  Use the `ToolSearch` tool to discover and load them on demand; once loaded, they're
  available for the rest of the conversation. Available deferred tools include:
  context7 (up-to-date docs for libraries), github, notion, playwright, railway.
  Before installing any package, check this list first — the capability likely already exists.

Uvilo-specific tools (linear, neon, posthog, suprsend) are listed in Uvilo/AGENTS.md, not here — FORGE.md is general-purpose and should not mention tools only used by one department.

1.2 Add Escalation Rule (R6)

File: Forge/FORGE.md — add to EXECUTION RULES section, after the existing rules:

**ESCALATION RULE:** After 2 failed attempts on infrastructure/deployment tasks
(installing services, configuring databases, setting up MCP servers, modifying
Railway/Vercel settings), STOP and ask the user to intervene. Do not try a third
approach without user guidance.

1.3 Add Permission Rule (R7)

File: Forge/FORGE.md — add to AUTONOMY & PERMISSIONS section:

- Never auto-grant shell permissions. When a permission check fires, present it to
  the user. The user decides: once, session, or always.
- Always use uvilo-trash for file deletion — never `rm`.

1.4 Fix End-of-Session Protocol (R7)

File: Forge/FORGE.md — change step 3 of “Ending a project session” from:

3. Clear session grants: delete `/tmp/uvilo-shell-session.yaml` if it exists.
   **Do NOT grant `rm` permanently** — use uvilo-trash for file deletion instead.

To:

3. Clear session grants: `truncate -s 0 /tmp/uvilo-shell-session.yaml` if it exists.
   Never use `rm` — always use uvilo-trash for file deletion.

1.5 Add Summarize Rule and Move Post-Action Checklist to Skill (R9)

File: Forge/FORGE.md — add to EXECUTION RULES section:

**SUMMARIZE** — After completing a task, briefly state what you did.
Examples: "Created file and matching sidebar menu entry."
"Committed and pushed to dev." "Deployed config and triggered redeploy."

The POST-ACTION CHECKLIST does not belong in FORGE.md — it is not general-purpose; it applies specifically to creating, renaming, or deleting pages/files. It belongs in the Create_Page skill (and eventually in a specialized sub-agent for page management once multi-agent orchestration is available). Add to Forge/Skills/Create_Page/SKILL.md:

**POST-ACTION CHECKLIST** — verify after creating/renaming/deleting any file:
□ Sidebar entry added/updated in .internal/astro.config.mjs
□ Frontmatter title matches heading 1
□ File committed together with sidebar change

1.6 Update Uvilo/AGENTS.md (R1)

File: Uvilo/AGENTS.md — expand to clarify organizational context:

---
title: "Uvilo AGENTS"
visibility: internal
---

# Uvilo AGENTS

Uvilo Inc. is the organization this instance of Forge serves. **Product** is Uvilo AI,
Uvilo Inc.'s flagship personal growth platform. All department folders except Forge
(Product, Technology, Marketing, Planning, Operations, Finance, Investors) belong to
Uvilo Inc.

## Uvilo-Specific MCP Tools

These deferred tools are used primarily by Uvilo Inc.:
- **linear** — Issue tracking for Uvilo
- **neon** — Fully managed PostgreSQL used by Uvilo
- **posthog** — Analytics for Uvilo
- **suprsend** — Email, SMS, push notifications from Uvilo

## Projects

Projects live in `Uvilo/Projects/`.

## Cross-references

- [Forge/Knowledge/Constants](/forge/knowledge/constants) — Path constants and Railway IDs

1.7 Move COMMANDS Table Out of FORGE.md

File: Forge/FORGE.md — replace the COMMANDS table with a pointer that explains when to consult it:

## COMMANDS

Slash commands start with `/` (e.g., `/deploy-config`, `/redeploy`). When you encounter
or need a slash command, read `Forge/Knowledge/Commands_Reference.md` for the full table.

Create Forge/Knowledge/Commands_Reference.md with the current COMMANDS table content.

Word savings: ~80 words, making room for Phase 1 additions.

Phase 2: Knowledge Updates

Update existing knowledge files with new information. These are independent of the restructuring in Phase 3.

2.1 Vercel: Full Docs to Infrastructure, Procedure to Skill (R3)

Vercel knowledge is split into two destinations:

A. Full documentation → Forge_Infrastructure.md (after restructuring)

Add a “Vercel” section to Forge_Infrastructure.md containing the complete declarative description of the Vercel setup: API key handling, preview URLs, deployment protection bypass mechanism, DNS configuration, and site features. This is reference knowledge — what the system is and how it’s configured.

## Vercel

### API Key

The `vercel-mcp` npm package reads the API key from a CLI argument
(`VERCEL_API_KEY=<key>`), NOT from `process.env`. LibreChat's `env` field sets
environment variables, but vercel-mcp ignores those. Pass the key as an arg:
`args: ["-y", "vercel-mcp", "VERCEL_API_KEY=<key>"]`.

### Preview URLs

Always use `os.uvilo.com` to check deployments — it always shows the latest preview.
Do not use unique per-deployment URLs (`uvilo-xxx-uvilo.vercel.app`).

### Deployment Protection Bypass

Vercel Standard Protection requires authentication for preview deployments.
Bypass for automation is enabled on the `uvilo-os` project.

**Bypass method:** Query parameter on first navigation:

https://os.uvilo.com?x-vercel-protection-bypass=


The bypass secret is stored in `/workspace/librechat/.secrets` under the
`vercel.protection_bypass` key. The query parameter sets a bypass cookie
on the first request, so subsequent navigations within the same browser
session don't need the parameter.

B. Procedural steps → Forge/Skills/Vercel_MCP/SKILL.md (new skill)

Create a skill named Vercel_MCP (per the <Tool>_MCP naming convention for MCP-server-accessed tools) with the minimal procedural steps an agent needs to use the Vercel MCP server. See Task 3.3 for the full mapping and naming principle.

This split reflects the updated Skills vs Knowledge definition:

Knowledge = declarative description of the system (what it is, how it’s configured)
Skills = minimal, atomic, procedural instructions for accomplishing tasks (how to use it)

2.2 Update Railway Knowledge (R4)

File: Forge/Knowledge/Tools/Railway.md

Add section:

## Reading Environment Variables

Railway env vars are NOT available via `os.environ` or `echo $VAR` in the
LibreChat container. To read them:

**Shell:** `cat /proc/1/environ | tr '\0' '\n' | grep VAR_NAME`
**Python:** `open('/proc/1/environ').read().split('\0')`

Do NOT use: `os.environ`, `echo $VAR`, `os.getenv()` — these are unreliable
in the Railway container environment.

2.3 Create Secrets Inventory (R4)

File: Forge/Knowledge/Secrets.md (or a section in Forge_Infrastructure.md after restructuring)

---
title: "Secrets"
visibility: internal
---

# Secrets

Reference inventory of available secrets and environment variables.
This file is rarely loaded — usage directions for specific values should
live near where they are needed (in skill and knowledge files).

## Access Methods

- **Railway env vars:** `cat /proc/1/environ | tr '\0' '\n'`
- **Secrets file:** `/workspace/librechat/.secrets` (JSON, on persistent volume)

## Railway Environment Variable Categories

| Category | Key variables | Used by |
|----------|--------------|---------|
| LLM API keys | OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_KEY, OPENROUTER_KEY | LibreChat, Forge Optimizer |
| Service tokens | SUPRSEND_SERVICE_TOKEN, RAILWAY_API_TOKEN, NEON_API_KEY, NOTION_TOKEN, LINEAR_ACCESS_TOKEN | MCP servers |
| Infrastructure | MONGO_URI, MEILI_HOST, MEILI_MASTER_KEY, RAG_API_URL | LibreChat, MongoDB, Meilisearch |
| Git credentials | GITHUB_PERSONAL_ACCESS_TOKEN, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL | uvilo-git, uvilo-git-remote |
| Vercel | VERCEL_API_KEY | vercel MCP |
| Auth | CREDS_KEY, CREDS_IV, JWT_SECRET, JWT_REFRESH_SECRET | LibreChat auth |
| Email | EMAIL_HOST, EMAIL_USERNAME, EMAIL_PASSWORD | Postmark SMTP |
| Analytics | POSTHOG_API_KEY, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY | PostHog, Langfuse |
| Search | SERPER_API_KEY, TAVILY_API_KEY, FIRECRAWL_API_KEY, JINA_API_KEY | Web search, scraping |

## Secrets File (.secrets)

Location: `/workspace/librechat/.secrets`

Keys:
- `uvilo_ai` / `librechat` — Login credentials for uvilo.ai and librechat.uvilo.ai
- `vercel.protection_bypass` — Vercel deployment protection bypass secret
- `composio.api_key` — Composio integration API key

**⚠ .secrets is NOT committed to source control.** It lives only on the Railway
persistent volume. If the volume is wiped or the file is accidentally deleted, it
must be re-created from scratch. When modifying .secrets, instruct the user to store
the updated contents in a safe place (e.g., password manager) so it can be recovered.

## What NOT to Do

- Do NOT use `os.environ` or `os.getenv()` — unreliable in Railway container
- Do NOT use `echo $VAR` — shell exports don't persist reliably
- Do NOT commit secret values to the repo

Phase 3: Forge Directory Restructuring

Major reorganization per R5 decisions. This is the largest phase and should be done carefully to avoid breaking cross-references, the sidebar, and the content build.

3.0 Simplify Content Inclusion Pattern (R10, R11)

This is a prerequisite for the rest of Phase 3 — it removes the SKILL.md exclusion machinery that other tasks currently work around.

A. Simplify content.config.ts glob pattern

Replace the ~30-line pattern array with:

pattern: [
  '**/*.md',                     // All markdown files everywhere
  '!.internal/**',               // Except internal Astro source
  '.generated/**/*.view.md',     // Re-include file-view wrappers for non-.md files
],

Remove all per-department includes, per-directory excludes, and .generated/ re-inclusions for .md files. The .generated/ line is only needed for non-.md file-view wrappers (.ts, .json, .py, etc.).

B. Add name and description to the Starlight extend schema

In the same file, update the docsSchema extend:

schema: docsSchema({
  extend: z.object({
    visibility: z.enum(['internal', 'public']).optional().default('internal'),
    status: z.enum(['draft', 'review', 'approved', 'active', 'implemented']).optional(),
    owner: z.string().optional(),
    last_reviewed: z.coerce.date().optional(),
    version: z.number().optional(),
    name: z.string().optional(),           // Agent Skills spec: skill identifier
    description: z.string().optional(),    // Agent Skills spec: skill description
  }),
}),

This ensures name and description survive Zod parsing and are available in Starlight page data.

C. Remove SKILL.md wrapper generation from the page generator

In Forge/Projects/Sidebar_Reorg/Scripts/generate_view_pages.ts, remove the logic that generates .generated/...SKILL.md.view.md wrapper pages. SKILL.md files are now included directly as regular content.

D. Update all SKILL.md files with combined frontmatter

Every SKILL.md file must have both Agent Skills fields and Starlight fields:

---
name: preview
description: Use when previewing the Vercel deployment
title: "Preview"
visibility: internal
status: archived
owner: "erik@uvilo.com"
---

The title field should match the skill’s display name (human-readable). The name field is the Agent Skills identifier (lowercase, hyphens). The description field is the Agent Skills trigger description.

E. Update sidebar entries for SKILL.md pages

SKILL.md files are now regular content pages. Add { slug: '...' } entries for each SKILL.md to the sidebar in .internal/astro.config.mjs (under the appropriate Skills subgroup). Previously these were only accessible via .generated/ wrapper pages.

F. Update AI_Guide.md and Update_Sidebar/SKILL.md

Remove references to SKILL.md exclusion, file-view wrappers for SKILL.md, and the complex content inclusion rules. Replace with the simplified pattern description.

3.1 Rename Prompts → Assets

Move Forge/Prompts/ → Forge/Assets/
Move Forge/FORGE.md → Forge/Assets/FORGE.md
Update all references to FORGE.md path in:
- Root AGENTS.md
- Forge/AGENTS.md
- Forge/Knowledge/System_Prompt.md
- Forge/Skills/Update_Agents/SKILL.md and scripts
- .internal/astro.config.mjs sidebar
- .internal/src/content.config.ts glob patterns

Important: The /update-agents skill reads FORGE.md and copies it to LibreChat agent instructions. The path change must be reflected in that skill’s script.

3.2 Create Consolidated Root-Level Documentation

Create these files at Forge/ root level by consolidating existing Knowledge/ content:

New file	Source content	Approx. words
`Forge_Charter.md`	Existing — no change	~400
`Forge_Content_System.md`	AI_Guide.md	~500
`Forge_Agent_Architecture.md`	System_Prompt.md + Memory_Architecture.md + Libre_Agents.md	~1,200
`Forge_Document_Structure.md`	File_Naming.md	~600
`Forge_Infrastructure.md`	Setup.md + Constants.md + Secrets.md (R4) + Tools/*.md (condensed)	~2,500

Naming rationale: Forge_Document_Structure replaces the generic Forge_Conventions. This file covers file naming, folder hierarchy, and sidebar/menu structure — the structural conventions for how documents are organized and navigated. Other conventions (markdown syntax, tool usage, project management) belong in their respective domain files.

Each file should:

Have YAML frontmatter with title, visibility, status, owner
Start with a table of contents (for human readability)
Use clear section headers (for Typesense semantic search)
Be comprehensive enough for a human to read top-to-bottom
Cross-reference other root-level docs, not Knowledge/ subdirectory files

Typesense chunking strategy: Instead of splitting long files into arbitrary overlapping word-count chunks, split by sub-sections starting at headings (##, ###). Each heading-defined section becomes its own chunk with the heading as context. This preserves semantic coherence — a chunk about “Deployment Protection Bypass” stays intact rather than being split mid-sentence. Update the indexing scripts (index-department.py, index-repo.ts) to implement heading-based chunking. The path field for chunks becomes path#heading-slug (e.g., forge/forge_infrastructure#deployment-protection-bypass).

3.3 Fold Knowledge/Tools/ Content into Skills

Per the R5 decision, per-MCP tool reference files are skills misfiled as knowledge. Each Knowledge/Tools/*.md file should be folded into the skill that uses that tool. If no skill exists yet, create one.

Mapping:

Current file	Destination skill	Action
Playwright.md	New `Forge/Skills/Playwright_MCP/SKILL.md`	Create skill
Suprsend.md	New `Forge/Skills/Suprsend_MCP/SKILL.md`	Create skill (fold proxy info in)
Vercel.md	New `Forge/Skills/Vercel_MCP/SKILL.md`	Create skill
Railway.md	Fold into `Forge/Skills/Deploy_Config/SKILL.md`	Extend existing skill
MCP_Development.md	New `Forge/Skills/MCP_Development/SKILL.md`	Create skill
Linear.md	New `Forge/Skills/Linear_MCP/SKILL.md`	Create skill
LibreChat.md	Fold into `Forge/Skills/Deploy_Config/SKILL.md`	Extend existing skill
Git.md	Fold into existing Git-related skill	Extend existing skill
NPM.md	New `Forge/Skills/NPM/SKILL.md`	Create skill
Composio.md	New `Forge/Skills/Composio_MCP/SKILL.md`	Create skill
Typesense.md	New `Forge/Skills/Typesense_MCP/SKILL.md`	Create skill

Skill naming principle: Skills for tools accessed via an MCP server use the <Tool>_MCP naming convention — e.g., Vercel_MCP, Linear_MCP, Playwright_MCP, Typesense_MCP, Suprsend_MCP, Composio_MCP. This makes clear the skill is about using that tool’s MCP server interface, not about the tool in general. The declarative knowledge about the tool’s configuration lives in Forge_Infrastructure.md.

Skills for tools NOT accessed via MCP (NPM, MCP_Development, Git) do not get the _MCP suffix.

Key principle: Each skill becomes self-contained — it carries everything an agent needs to use that tool, including quirks, workarounds, and configuration gotchas. No more cross-references to Knowledge/Tools/.

3.4 Eliminate Lessons.md as Separate Concept

Review all entries in Forge/Lessons.md
Stable, permanent learnings → integrate into the relevant consolidated doc
Transient/session-specific notes → they belong in WIP files, not a persistent doc
Remove Forge/Lessons.md
Remove the “read Lessons.md” step from PRE-WORK in FORGE.md
The PRE-WORK step becomes: “Read Knowledge/INDEX.md” (or equivalent after restructuring)

Current Lessons.md entries and their destinations:

Entry	Destination
REVISION HYGIENE	Forge_Document_Structure.md (writing section)
LINKS MUST BE CLICKABLE	Forge_Document_Structure.md (writing section)
DON’T CHECK OFF UNVERIFIED WORK	FORGE.md (todo conventions section — already partially there)
ASK FOR HELP EARLY	Replaced by escalation rule in FORGE.md (R6)
OPENAI_API_KEY ON RAILWAY	Forge_Infrastructure.md (env vars section)
PASTE PROMPTS IN CODE BLOCKS	Forge_Document_Structure.md (writing section)

After all file moves and consolidations:

Update all AGENTS.md files that reference Knowledge/ paths
Update sidebar in .internal/astro.config.mjs
Update glob patterns in .internal/src/content.config.ts
Verify build: cd .internal && npm run build
Verify Typesense index picks up new file locations

3.6 Update FORGE.md References

FORGE.md currently references:

Lessons.md → remove or replace with pointer to consolidated docs
Knowledge/index.md → replace with pointer to root-level doc index
Knowledge/Tools/<Tool>.md → replace with pointer to Infrastructure doc
Various Knowledge/ paths → update to new root-level doc paths

3.7 Update Skills vs Knowledge Definition

FORGE.md’s current definition:

Concept	Test
Skill	Reusable procedure — “Can I walk through this step-by-step?”
Knowledge	Reference fact — “Would I grep for this to answer a question?”

Replace with the updated definition:

Concept	Definition
Knowledge	Declarative description of the system — one document per major topic or feature, aimed for reading by humans and discovering by machines (via Typesense) when needed
Skill	Procedural, minimal, atomic instructions for accomplishing a task by machines
Guide	Step-by-step instructions for humans on how to accomplish tasks, supplementing the information in Knowledge
Command	User-facing `/name` dispatch — routes to a skill or procedure
Instructions	Collective term for Knowledge, Skills, Guides, and Commands — all the content that instructs agents and users how the system works and what to do

Decision rule: If it tells you how to do something, it’s a skill. If it tells you what something is, it’s knowledge.

This replaces the old “grep test” with a clearer declarative vs procedural distinction. Knowledge files are comprehensive documents for human consumption (like librechat.ai/docs); skills are concise action recipes for machine execution.

Phase 4: Forge Optimizer Skill (R8)

Independent of the restructuring — can be done in parallel with Phase 3.

4.1 Create Skill Structure

Forge/Skills/Forge_Optimizer/
├── SKILL.md              # Procedure outline + essential rules (≤500 words)
├── LESSONS.md            # Transient learnings (to be eliminated per R5)
└── references/
    ├── extraction_prompt.md   # LLM prompt template for transcript analysis
    └── example_report.md      # Sample output from a real analysis

4.2 SKILL.md Content

The skill should:

Access conversation content directly from MongoDB (not from a JSON export). The MONGO_URI is available from Railway env vars (see Secrets inventory). Conversations are stored in the test.conversations collection.
Accept a conversation title as input. When no title is provided, analyze the most recent conversation (excluding the current one).
Also add a /optimize command that takes an optional conversation title argument.
Run an LLM analysis using the extraction prompt template
Produce a structured report with categories:
- Token waste events — unnecessary tool calls, redundant reads, failed approaches
- Missing knowledge — things the agent should have known but didn’t
- Rule violations — operating rules the agent skipped
- Codifiable patterns — behaviors that should become lessons, skills, or knowledge
- Recommended changes — specific additions/modifications to FORGE.md, docs, or skills
Save the report and present findings to the user

MongoDB access pattern:

import json, urllib.request
mongo_uri = # read from /proc/1/environ
# Parse connection string, query test.conversations
# Sort by updatedAt descending, skip first (current convo), take next

4.3 Sample Analysis

Use the existing transcript at Forge/Projects/Forge_Skills_2/Assets/2026-04-13_18-20.json as the first test case. Once MongoDB access is working, test by looking up this same conversation by title.

Phase 5: Alpine → Debian-slim Investigation (New Project)

This is a significant infrastructure change that warrants its own project. Since this is work on Forge infrastructure, it goes in Forge Projects.

5.1 Create Project

Create Forge/Projects/Container_Base_Image/ with:

Container_Base_Image_Requirements.md — problem statement and goals
Container_Base_Image_Research.md — Alpine vs Debian-slim analysis
Container_Base_Image_State.md — task tracking

5.2 Research Questions

Can we build a custom LibreChat image based on node:20-slim instead of node:20-alpine?
What LibreChat build steps need to change?
What is the image size difference?
Do all current MCP servers and npm packages work on Debian-slim?
Can common tools (curl, wget, nano, bash) be included without significant size increase?
What is the migration path? (Build new image → test → deploy → verify)

5.3 Expected Outcome

If feasible, switch to a Debian-slim base image. This would:

Eliminate musl/glibc compatibility issues
Provide standard Linux tools out of the box
Remove the need for most Alpine-specific workarounds documented in R2
Make the “Before You Install” section much simpler

Implementation Order

Phase	Tasks	Risk	Depends on
1	FORGE.md quick fixes (1.1–1.7)	Low	None
2	Knowledge updates (2.1–2.3)	Low	None
3	Directory restructuring (3.1–3.6)	High	Phase 1 (FORGE.md moves to Assets)
4	Forge Optimizer skill (4.1–4.3)	Low	None (independent)
5	Alpine investigation (5.1–5.3)	Medium	None (separate project)

Recommended execution order: Phase 1 → Phase 2 → Phase 4 (in parallel with Phase 3 planning) → Phase 3 → Phase 5.

Phase 3 is the highest-risk phase because it moves many files and updates many cross-references. It should be done in a single focused session with a clean git state, and the build should be verified after each major step.

Verification

After all phases: