Forge Skills 2 Research

Solutions research for each requirement in Forge_Skills_2_Requirements.md. Each section presents the problem, evaluates options, records Erik’s decisions, and details the chosen approach.

---

Research History

Session 2026-04-14 (initial)

Created research document with 9 requirement areas (R1–R9), options analysis, and decision points for Erik.

Session 2026-04-14 (decisions)

Erik reviewed all decision points. Decisions recorded inline. Major new themes: (1) restructure Forge directory layout — consolidate Knowledge into root-level docs, rename Prompts to Assets, move FORGE.md there; (2) Alpine container is a problem worth solving at root cause level; (3) permission system must not be weakened — user decides, not agent; (4) information should be consolidated into fewer, longer files for human readability; (5) new “Before You Install” document for environment constraints. Web research conducted on: AgentSpec (LLM rule enforcement), Alpine vs Debian-slim containers, MCP security best practices, knowledge management consolidation patterns.

---

R1: Deferred Tool Awareness

Problem: Agents lack a mental model of their own tool architecture. They don’t understand that most MCP tools are deferred (not loaded into context) and that ToolSearch exists to discover them on demand. When an agent needs a capability, it reaches for npm install instead of searching for an existing MCP server.

Current state: FORGE.md already mentions deferred tools and ToolSearch in the ENVIRONMENT & AUTHORITY section, but agents treat it as background context and don’t act on it.

Options Evaluated

A. Strengthen the FORGE.md directive (wording only) — Add a mandatory pre-installation checklist to FORGE.md’s EXECUTION RULES section. Same class of problem as R9 — rules in FORGE.md are treated as background, not checklist items.

B. Add a “MCP Server Inventory” Knowledge file — Create Knowledge/MCP_Servers.md with an inventory of every available MCP server. Agents can discover capabilities by reading a single file. Cons: must be maintained; still relies on agents reading a directive.

C. Combine A + B — Strengthen the FORGE.md directive AND create the MCP server inventory.

Decision

Erik chose: Modified B. Erik is concerned that a full Knowledge file will become bloat. Instead, list the MCP servers by name with 2–3-word disambiguation directly in FORGE.md. Example:

Available deferred tools include context7 (up-to-date docs for libraries), github, notion, playwright, railway.

Uvilo-specific tools (linear, neon, posthog, suprsend) should NOT be mentioned in FORGE.md — they belong in Uvilo/AGENTS.md. FORGE.md is general-purpose and should not contain tools only used by one department.

Additionally, Uvilo/AGENTS.md should make clear that “Product” is Uvilo AI, Uvilo Inc.’s flagship product, and all the other department folders (except Forge) belong to Uvilo Inc.

Rationale: A one-line list in FORGE.md gives agents a mental model without creating a new file to maintain. The list is short enough to fit within the word budget. Uvilo-specific context belongs in Uvilo’s department, not Forge.

Implementation

1. Add a one-line deferred tools list to FORGE.md’s ENVIRONMENT & AUTHORITY section
2. Update Uvilo/AGENTS.md to clarify: Product = Uvilo AI, all non-Forge departments belong to Uvilo Inc.
3. Move Uvilo-specific tool mentions (neon, posthog, suprsend, linear) from Forge context to Uvilo/AGENTS.md

---

R2: Don’t Install What Already Exists

Problem: When asked to test os.uvilo.com using Playwright, the agent tried npm install playwright instead of using the existing Playwright MCP server. This failed due to Alpine container incompatibilities. The agent didn’t know Playwright MCP existed, didn’t think to use ToolSearch, and didn’t know Alpine constraints.

Current state: Knowledge/Tools/MCP_Development.md documents Alpine constraints (no bash, no curl/wget, busybox ash). Knowledge/Tools/Playwright.md documents the Playwright MCP server. But neither is loaded proactively.

Options Evaluated

A. Alpine constraints in FORGE.md — Add a short constraint block to FORGE.md’s ENVIRONMENT & AUTHORITY section.

B. Alpine constraints in the MCP Server Inventory file (from R1-B/C) — Put the Alpine constraints alongside the server inventory.

C. Combine A + B — Brief Alpine warning in FORGE.md plus full details in the inventory file.

Decision

Erik chose: Neither A, B, nor C as proposed. Two key objections:

1. “Since by default nothing should be installed, this does not need to be noted.” — The default behavior should be “don’t install anything.” Alpine constraints are a secondary concern; the primary fix is making agents check for existing tools first (R1).

2. “Why mention Alpine when talking about existing MCP servers? This should be in a ‘Before you install anything in the environment’ file.” — Alpine constraints are environment-specific installation knowledge, not tool awareness knowledge. They belong in a dedicated document about the environment’s constraints, not mixed into the MCP server inventory.

Additional concern raised by Erik: “Why are we running on a crappy, incompatible linux? We need to seriously rethink this.” Erik asks whether Railway containers can be spun up with better distros, or whether common Linux tools (nano, curl, wget) can be installed. This may warrant a separate project.

Research: Alpine vs Debian-slim

The LibreChat Docker image (ghcr.io/danny-avila/librechat-dev:latest) is based on node:20-alpine. Our custom Dockerfile extends it:

FROM ghcr.io/danny-avila/librechat-dev:latest
USER root
RUN apk add --no-cache git bash && pip install --quiet --break-system-packages mcp
USER node

Why Alpine is problematic for our use case:

• musl vs glibc: Alpine uses musl libc; most npm packages and Python wheels are built against glibc. Many packages fail silently or require compilation from source. (iximiuz.com, oneuptime.com)
• Missing utilities: No curl, wget, nano by default. BusyBox ash instead of bash (though we add bash in our Dockerfile).
• Python wheel compatibility: Pre-built wheels target glibc. On Alpine, pip install numpy compiles from source, adding minutes to builds and requiring gcc/musl-dev/etc. (oneuptime.com)
• Community experience: A quarter of respondents in one survey started with Alpine but moved away, citing compatibility and performance issues. (iximiuz.com)

Alternative: Switch to node:20-slim (Debian bookworm-slim)

• Uses glibc — all standard npm packages and Python wheels work
• Includes bash, curl, wget by default
• ~70MB larger than Alpine (~130MB vs ~60MB compressed), but this is negligible on Railway
• apt-get instead of apk for package management
• Our Dockerfile would change to: FROM node:20-slim + RUN apt-get update && apt-get install -y git python3 python3-pip && rm -rf /var/lib/apt/lists/*

Feasibility: LibreChat’s Dockerfile uses node:20-alpine as its base, and our custom image extends ghcr.io/danny-avila/librechat-dev:latest. We cannot change the base without rebuilding LibreChat from source or creating a completely custom image. The most practical approach is to create a new Dockerfile that starts from node:20-slim and replicates the LibreChat build steps, or uses a multi-stage build that copies the LibreChat artifacts into a Debian-slim runtime image.

This is a significant infrastructure change that warrants its own project.

Implementation

1. Create Forge/Infrastructure.md (or a new “Before You Install” doc) documenting:
   • The container is Alpine-based: no bash (unless added), no curl, no wget, no nano
   • Many npm packages fail due to musl/glibc incompatibility
   • Before installing anything, check for existing MCP servers (cross-ref R1)
   • Use Python’s urllib for downloads instead of curl/wget
   • Use shutil.which("bash") or shutil.which("sh") for shell detection
2. New project proposal: Evaluate switching from Alpine to Debian-slim base image. This would eliminate most Alpine-specific workarounds at the root cause level. Separate project recommended.

---

R3: Vercel Deployment Protection Bypass

Problem: The agent couldn’t figure out how to bypass Vercel’s deployment protection to access os.uvilo.com via Playwright. No knowledge file explains the bypass mechanism.

Current state: Knowledge/Tools/Vercel.md covers API key handling and preview URLs but not access control. Knowledge/Tools/Playwright.md covers authenticated browsing via .secrets file but not Vercel protection.

How Vercel Protection Bypass Works

Vercel Standard Protection requires authentication for preview deployments. The bypass mechanism (vercel.com):

1. Enable “Protection Bypass for Automation” in Vercel project settings
2. Vercel generates a secret and sets it as VERCEL_AUTOMATION_BYPASS_SECRET in the project’s environment variables
3. Include the secret as either:
   • HTTP header (recommended): x-vercel-protection-bypass: <secret>
   • Query parameter: ?x-vercel-protection-bypass=<secret>

For Playwright MCP specifically, the query parameter approach is simpler — it sets a bypass cookie on the first request, so subsequent navigations within the same browser session don’t need the parameter.

Options Evaluated

A. Query parameter approach + Knowledge file update — Store bypass secret in .secrets, update Vercel.md with procedure.

B. Header approach + custom Playwright setup script — More “proper” but significantly more complex; Playwright MCP doesn’t expose route interception as a tool.

C. Query parameter approach (recommended) — Pragmatic choice for AI agent using Playwright MCP tools.

Decision

Erik chose: C. Implementation steps:

1. Enable “Protection Bypass for Automation” in Vercel project settings DONE — already enabled
2. Retrieve the VERCEL_AUTOMATION_BYPASS_SECRET value DONE — stored in .secrets under vercel.protection_bypass key (not committed to source control)
3. Add it to /workspace/librechat/.secrets DONE — already present
4. Update Knowledge/Tools/Vercel.md (or the new consolidated Vercel doc) with the bypass procedure

Implementation

Update the Vercel knowledge doc with:

• The bypass mechanism explanation
• How to use the query parameter: https://os.uvilo.com?x-vercel-protection-bypass=<secret>
• Reference to .secrets file for the bypass value
• Note that the cookie persists for the session after first navigation

---

R4: Secrets and Environment Variable Access

Problem: Agents are unaware of what secrets exist or how to access environment variables on Railway. The /proc/1/environ pattern is buried in a Knowledge file. Agents try os.environ or echo $VAR which don’t work reliably.

Current state:

• Knowledge/Setup.md lists key env vars but doesn’t explain how to read them
• Lessons.md has one entry about reading OPENAI_API_KEY from /proc/1/environ
• Knowledge/Tools/Railway.md mentions env var behavior but not access patterns
• /workspace/librechat/.secrets exists for Playwright auth credentials
• No inventory of what secrets/env vars are available

Options Evaluated

A. Create Knowledge/Secrets.md — a secrets inventory — Single file listing how to read Railway env vars, known env vars and their purpose (not values), .secrets file location and format, what NOT to do.

B. Expand Knowledge/Tools/Railway.md with env var access patterns — Doesn’t create a new file but could exceed the 800-word budget.

C. Create Knowledge/Secrets.md + update Railway.md — Split: access patterns in Railway.md (Railway-specific), inventory in Secrets.md (what exists, where to find them).

Decision

Erik chose: C. Knowledge/Secrets.md should list what is available but should not need to be loaded very often, because directions for using specific env/secret values should be kept near where they are needed in other skills and knowledge files. Secrets.md is a reference index, not a routinely-loaded document.

Implementation

1. Create Knowledge/Secrets.md:
   • How to read Railway env vars: cat /proc/1/environ | tr '\0' '\n'
   • Inventory of known env var categories (not values — values are in Railway/env):
     • LLM API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
     • Service tokens (SUPRSEND_SERVICE_TOKEN, RAILWAY_API_TOKEN, etc.)
     • Infrastructure (MONGO_URI, MEILI_HOST/MASTER_KEY, etc.)
     • Git credentials (GITHUB_PERSONAL_ACCESS_TOKEN, GIT_AUTHOR_*)
     • Vercel (VERCEL_API_KEY)
   • .secrets file location and format
   • What NOT to do (don’t use os.environ, don’t use echo $VAR)
2. Update Knowledge/Tools/Railway.md with the /proc/1/environ access pattern
3. Add cross-references from relevant skill/knowledge files to specific env vars they need

---

R5: Knowledge File Naming and Organization Audit

Problem: AI_Guide.md contains loosely related items (page generation system, content inclusion rules, writing conventions, key files reference) under a vague name. The name tells an agent nothing about what’s inside or when to load it. More broadly, Erik has major concerns about the entire knowledge/skills organization system.

Erik’s Concerns (Broader Than Original R5)

1. Information dispersed into many little files. Knowledge is broken into dozens of small files that will eventually number in the hundreds. Humans want to read much longer documentation files, broken down by major sections or features — like librechat.ai/docs.

2. Skills are not self-contained. They may need to refer to knowledge files elsewhere, creating fragile cross-references.

3. Ill-defined “Learnings” concept. Is a learning a change to a skill, or is it documentation? The LESSONS.md concept is confusing and adds another category of file to maintain.

4. No human-readable knowledge. The current structure is optimized for LLM context-loading but hostile to human browsing. With Typesense installed, LLMs will find knowledge via semantic search, not by reading individual knowledge files. The documentation site should serve both audiences.

5. FORGE.md is in the wrong place. It’s an asset (a system prompt template), not a root-level document.

Proposed New Forge Directory Structure

Inside each department, including Forge, the structure should be:

Forge/
├── INDEX.md
├── README.md
├── AGENTS.md
├── Projects/
├── Skills/           # Skills should be self-contained as much as possible
├── Assets/           # Renamed from "Prompts" — FORGE.md moves here
│   └── FORGE.md
└── [5–10 root-level documentation files]  # Consolidated, human-readable

The root-level documentation files should describe the entire Forge system in detail for both humans and LLMs. Forge_Charter.md should be the first. Then the contents of Knowledge/ should be moved to the root level, consolidated into fewer, longer files.

Rename Setup → Infrastructure. Knowledge/Setup.md becomes Forge_Infrastructure.md at the Forge root. There should still be a Forge_Setup skill with all the info needed to re-build the whole system from scratch.

Research: Knowledge Management Best Practices

Consolidation over fragmentation. Research on AI agent knowledge management (raia) recommends consolidating related small files into larger documents with clear section headers and tables of contents. Target: 1–5MB for consolidated files. Multiple small files (under 100KB each) create management overhead and impact system performance.

Semantic search changes the equation. With Typesense installed, LLMs find knowledge by semantic search, not by reading individual files. This means the “one topic per file, ≤800 words” constraint was designed for a world without semantic search. In a search-first world, longer consolidated files with clear sections work better — the search engine returns the relevant section, and the human can read the full document for context. (Oracle)

Hybrid model: folders + AI. The best approach is hybrid — keep basic folder structures for ownership and organization, but let AI handle understanding and retrieval. Folders are for ownership, not discovery. (smartarchive.io)

LibreChat docs as model. librechat.ai/docs organizes documentation by major feature areas with long, detailed pages — not dozens of tiny files. This is the model Erik wants for Forge.

Proposed Consolidation Map

Current files	→ New root-level file	Content
Forge_Charter.md	Forge_Charter.md (stays)	Values, goals, scope, constraints
Knowledge/AI_Guide.md	Forge_Content_System.md	Page generation, inclusion rules, writing conventions, key files
Knowledge/System_Prompt.md + Knowledge/Memory_Architecture.md	Forge_Agent_Architecture.md	System prompt pipeline, memory architecture, caching
Knowledge/Libre_Agents.md	Forge_Agent_Architecture.md (section)	Master agent + sync script
Knowledge/File_Naming.md	Forge_Conventions.md	Naming rules, sidebar order, department structure
Knowledge/Setup.md	Forge_Infrastructure.md	Disaster recovery, MCP servers, deployment, environment
Knowledge/Constants.md	Forge_Infrastructure.md (section)	Paths, Railway IDs
Knowledge/Secrets.md (new from R4)	Forge_Infrastructure.md (section)	Env var access, secrets inventory
Knowledge/Tools/*.md	→ Skills that use those tools (self-contained)	Per-MCP usage procedures are skills, not knowledge
Lessons.md	Eliminate as separate concept	Stable learnings → relevant doc; transient notes → WIP

Key principle: Each root-level doc is a comprehensive reference for its domain. Humans can read it top-to-bottom. LLMs use Typesense to find the relevant section. No more “one topic per file, ≤800 words” constraint for these consolidated docs.

Knowledge/Tools/ Is Skills, Not Knowledge

By Forge’s own test — “Can I walk through this step-by-step?” → yes → it’s a skill — the per-MCP tool reference files in Knowledge/Tools/ are skills misfiled as knowledge:

• Playwright.md (“use SSE, not streamable-http”) is a procedure for setting up Playwright correctly
• Suprsend.md (schema deduplication fix) is a procedure for working around a known bug
• MCP_Development.md (“use shutil.which('bash') or shutil.which('sh')”) is a procedure for writing MCP servers on Alpine
• Vercel.md (“pass API key as CLI arg”) is a procedure for configuring the Vercel MCP server
• Railway.md (“env var changes trigger redeploy”) is operational context for the Railway skill

The genuinely declarative scraps (“Service Tokens are account-wide”) are facts, but they belong inside a skill as context, not in a standalone reference file. As Lhotka notes: “Knowing that a hammer exists is different from knowing how to drive a nail without splitting the wood. The hammer is the tool. The technique is the skill.”

Decision: Fold each Knowledge/Tools/*.md file into the skill that uses that tool. If no skill exists yet (e.g., there’s no Playwright skill), create one. This makes skills self-contained — exactly what R5 demands.

Decision

Erik approved the general direction. Implementation requires careful planning to avoid breaking existing cross-references and the sidebar.

Implementation

This is a major restructuring. Steps:

1. Create Forge/Assets/ directory, move Prompts/ contents there, move FORGE.md there
2. Create consolidated root-level documentation files per the map above
3. Update all cross-references (AGENTS.md files, sidebar, content.config.ts)
4. Fold Knowledge/Tools/*.md content into the skills that use those tools (or create new skills where needed)
5. Rename Setup → Infrastructure throughout
6. Ensure Forge_Setup skill still exists with all info needed to rebuild from scratch
7. Update sidebar in .internal/astro.config.mjs
8. The old Knowledge/ directory is removed; its contents live in root-level docs or skills

---

R6: Ask-for-Help Escalation Rule

Problem: An agent trying to install TypeSense thrashed for several hours, costing ~$40 in tokens. Erik then installed TypeSense in the Railway dashboard in under 1 minute. The existing lesson in Lessons.md says “ask for help early” but is too soft.

Options Evaluated

A. Hard rule in FORGE.md — “After 2 failed attempts on infrastructure tasks, STOP and ask the user.”

B. Soft rule in Lessons.md only — Current state; insufficient.

C. Hard rule in FORGE.md + cross-reference in Lessons.md — Best of both worlds.

Decision

Erik chose: Modified A. The escalation rule belongs in FORGE.md as a hard rule, not in Lessons.md. Erik does not want a separate Lessons.md concept (see R5). The rule should be:

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.

Implementation

1. Add escalation rule to FORGE.md EXECUTION RULES section
2. Remove the soft version from Lessons.md (or eliminate Lessons.md per R5)
3. The rule is system-prompt priority — it’s in FORGE.md which is inlined

---

R7: Shell Permission Friction

Problem: When an agent runs commands that FORGE.md instructs it to run (e.g., rm -f /tmp/uvilo-shell-session.yaml in the end-of-session protocol), it hits the permission check, gets prompted, and then grants “session” — requiring multiple tool calls. The user is never involved in the decision.

Original Options

A. Add rm -f /tmp/ to allowed subcommands — Specific, narrow, addresses the known friction point.

B. Use truncate instead of rm — Workaround: truncate -s 0 /tmp/uvilo-shell-session.yaml avoids the rm permission check.

C. Rethink the end-of-session protocol — Use a different mechanism to clear session state.

Erik’s Decision — Fundamental Disagreement with Original Analysis

Erik disagrees with the original framing. Key points:

1. “I disagree with your analysis. You are only looking at one small sample chat. I see this problem ALL THE TIME.” — The permission friction is systemic, not a one-off. Every session encounters it multiple times.

2. “I disagree allowing rm anywhere — always use the trash command.” — No form of rm should be in the allowed list. The trash command exists for a reason.

3. “When the agent encounters a permission check, it should not override it! The whole point is for the user to decide what is allowed and what is not.” — The permission system is working as designed. The problem is NOT that agents need to bypass permissions — the problem is that agents are instructed to run commands that trigger permission checks, and then they auto-grant. The correct fix is:

   a. Change the end-of-session protocol to use the trash command or truncate instead of rm b. Never have agents auto-grant permissions — the user should always be the one deciding c. The user can choose “session” to remove friction for the rest of the session, or “always” to remove a particular friction point permanently

Research: MCP Permission Security Best Practices

MCP security research (knostic.ai, cerbos.dev, modelcontextprotocol.io) consistently recommends:

• Least-privilege access: Agents should only have the permissions they need for the specific task at hand
• User-in-the-loop for elevated actions: Destructive operations (file deletion, infrastructure changes) should require explicit user authorization
• No auto-escalation: Agents should never self-grant elevated permissions — this defeats the purpose of the permission boundary
• Capability-level scoping: Permissions should be scoped to specific tool actions, not blanket grants

The current uvilo-shell permission model is well-designed by these standards. The issue is not the model — it’s the agent behavior of auto-granting and the FORGE.md instructions that create guaranteed friction points.

Implementation

1. Change end-of-session step 3 in FORGE.md from rm -f /tmp/uvilo-shell-session.yaml to truncate -s 0 /tmp/uvilo-shell-session.yaml (truncate is already in the always-allowed list via awk/shell builtins, or can be added as a subcommand)
2. Add explicit rule to FORGE.md: “Never auto-grant permissions. When a permission check fires, present it to the user. The user decides: once, session, or always.”
3. Audit FORGE.md for other instructions that create guaranteed friction points and fix them
4. Keep rm out of allowed commands — always use uvilo-trash for file deletion

---

R8: Systematic Inefficiency Detection

Problem: There is no mechanism to systematically review past conversations for inefficiencies. Problems like R1–R7 are discovered manually, often after significant waste.

Options Evaluated

A. Rule-based script — Parse transcripts, count tool calls, flag patterns. Deterministic but rigid.

B. LLM-based skill with structured extraction prompt — Use an LLM to analyze transcripts and produce a structured report. More flexible, can detect semantic patterns (unnecessary approaches, missing knowledge).

C. LLM-based skill + references/ directory — The skill extracts findings; deep reference material (prompt templates, example analyses) lives in references/.

Decision

Erik chose: C. The Forge_Optimizer skill should use an LLM-based approach with structured extraction, and reference material should be kept in a references/ subdirectory.

Implementation

1. Create Forge/Skills/Forge_Optimizer/SKILL.md — procedure for analyzing conversation transcripts
2. Create Forge/Skills/Forge_Optimizer/references/ — prompt templates, example analyses
3. The skill should produce a structured report with:
   • Token waste events (unnecessary tool calls, failed approaches)
   • Missing knowledge (things the agent should have known but didn’t)
   • Patterns that should be codified as lessons or skills
   • Recommended changes to FORGE.md, Knowledge, or Skills
4. Sample transcript already exists in Forge/Projects/Forge_Skills_2/Assets/2026-04-13_18-20.json

---

R9: Agents Skip Required Steps from Their Own Operating Rules

Problem: FORGE.md contains a SIDEBAR RULE that agents repeatedly skip. When creating the Forge_Skills_2 project, the agent created three markdown files and committed them — but did not add any to the sidebar. This is not an edge case — it’s a core operating rule written in the system prompt that agents treat as background context rather than checklist items.

Research: LLM Rule Enforcement

AgentSpec (cposkitt.github.io, venturebeat.com) is a DSL for runtime enforcement of LLM agent behavior. Key insight: rules need to be attached to trigger points (before/after specific actions) to be reliably followed. AgentSpec hooks into three decision points:

1. AgentAction — before an action is executed
2. AgentStep — after an action produces an observation
3. AgentFinish — when the agent completes its task

This is the structural solution: rules attached to trigger points, not floating in background context.

OWASP guidance (genai.owasp.org): “Avoid reliance on system prompts for strict behavior control. Instead, rely on systems outside the LLM to ensure this behavior.” This supports the approach of structural enforcement (checklists, post-action verification) rather than just better wording.

Practical takeaway for Forge: We can’t implement AgentSpec-style runtime hooks in LibreChat (we don’t control the agent loop). But we can approximate the trigger-point approach by:

1. Making rules procedural (checklists tied to specific actions) rather than declarative (background principles)
2. Adding a post-action self-check step that forces the agent to verify compliance
3. Requiring the agent to summarize what it did, creating a natural audit point

Options Evaluated

A. Add an explicit post-action checklist to FORGE.md — Makes compliance a discrete step rather than a background rule.

B. Add “summarize major steps” rule to FORGE.md — Forces the agent to articulate what it did, creating a natural self-check moment.

C. Combine A + B — Checklist provides the verification framework; summary forces the agent to surface what it did.

Decision

Erik chose: C. Both the post-action checklist and the summarize rule.

Updated decision (2026-04-14 review): The SUMMARIZE rule stays in FORGE.md. The POST-ACTION CHECKLIST does NOT belong in FORGE.md — it is specific to creating/renaming/deleting pages and files. It belongs in the Create_Page skill. Eventually, when multi-agent orchestration is available, page management should be handled by a specialized sub-agent.

Implementation

1. Add to FORGE.md EXECUTION RULES:

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

2. Add to FORGE.md EXECUTION RULES:

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."

3. FORGE.md word budget impact: Current FORGE.md is ~1,460 words (budget ≤1,500). Proposed additions from R1, R6, R7, R9 total ~150 words over budget. The COMMANDS table (~80 words) can be moved to a reference doc to free space. See “FORGE.md Word Budget” section below.

---

New: “Before You Install” Document

Origin: Erik’s decisions on R2 and R6 both pointed to the need for a single document about environment constraints and installation rules.

Purpose: A consolidated reference for what agents need to know before installing anything in the environment.

Content:

• Container is Alpine-based: limited tools, musl/glibc incompatibility
• Before installing any package: check for existing MCP servers (R1 list)
• Common missing tools and their alternatives (Python urllib instead of curl)
• Escalation rule: 2 failed infra attempts → stop and ask user (R6)
• Never use rm — use trash command (R7)
• How to read env vars on Railway (R4)

Location: Per R5 restructuring, this content should be a section in Forge_Infrastructure.md rather than a standalone file.

---

FORGE.md Word Budget

Current FORGE.md: ~1,460 words (budget: ≤1,500).

Proposed additions:

• R1: ~30 words (deferred tools list)
• R6: ~30 words (escalation rule)
• R7: ~20 words (never auto-grant permissions)
• R9: ~60 words (post-action checklist + summarize rule)

Total: ~140 words over budget.

Options

1. Move COMMANDS table to a reference doc, keep one-line pointer in FORGE.md (saves ~80 words)
2. Compress existing sections — EXECUTION RULES and WORK TRACKING have room for tightening
3. Increase budget to 1,700 words (simplest but least disciplined)
4. Move FORGE.md to Configs/ — per R5 restructuring, FORGE.md moves to Forge/Configs/FORGE.md. This doesn’t change the word budget but changes the conceptual home.

Decision

Pending. Recommend Option 1 + 2 combined. The COMMANDS table is rarely needed (agents use /commands interactively) and can live in a reference doc.

---

Summary of Decisions

Req	Decision	Key change
R1	List deferred tools in FORGE.md with 2–3-word disambiguation; move Uvilo-specific tools to Uvilo/AGENTS.md	No new Knowledge file
R2	Create “Before You Install” section in Infrastructure doc; propose Alpine→Debian-slim as separate project	Address root cause, not symptoms
R3	Query parameter approach; bypass secret already in .secrets	Update Vercel doc
R4	Create Secrets.md as reference index; keep usage directions near where they’re needed	Secrets.md is rarely loaded
R5	Consolidate Knowledge/ into 5–10 root-level docs; rename Prompts→Assets; move FORGE.md to Configs; eliminate standalone Lessons.md	Major restructuring
R6	Hard escalation rule in FORGE.md; no separate Lessons.md	System-prompt priority
R7	Never auto-grant permissions; use truncate not rm; user always decides	Permission model is correct; agent behavior is the fix
R8	LLM-based Forge_Optimizer skill with references/	Structured extraction + deep reference
R9	Post-action checklist + summarize rule in FORGE.md	Procedural enforcement, not just declarative