Skip to main content
Documentation

How to Frontload Your Data

Give your AI agent a head start by populating your Minolith project with knowledge, procedures, and design tokens before the first session. Instead of building context organically over many sessions, you can seed everything upfront so your agent has the full picture from day one.

Prerequisites:

  • A Minolith account (sign up — 14-day free trial, no card required)
  • A project with an API key
  • Your project brief, coding standards, architecture decisions, and any existing documentation

Why Frontload?

When an agent connects to an empty Minolith project, it starts with nothing — no rules, no patterns, no history. It learns as it works, but that means the first few sessions are the least informed.

Frontloading solves this. By pre-populating your project with the knowledge your agent needs, you get the benefits of a mature knowledge base from the very first conversation:

  • Fewer mistakes on established conventions
  • No re-litigating settled decisions
  • Runbooks ready to follow from session one
  • Design system available before the first line of CSS

What You'll Need

Gather these materials before you start:

  • Project brief or README — what the project is, what stack it uses, how it's structured
  • Coding standards — naming conventions, file organisation, architectural rules
  • Key decisions — why you chose this framework, database, hosting, etc.
  • Known gotchas — things that break, surprising behaviour, common mistakes
  • Workflows — deployment procedures, review processes, release checklists
  • Design tokens — colours, typography, spacing (if applicable)
  • Foundation documents — PDFs, briefs, brand guidelines, spreadsheets, reference files

You don't need all of these. Start with whatever you have — even a few rules and decisions will make a difference.

Step 1: Store Your Context

Context entries are the foundation. They tell your agent how the project works, what rules to follow, and what pitfalls to avoid. All Context operations are free — store as much as you need.

From the dashboard

  1. Open your project and click Context in the sidebar
  2. Click New Entry
  3. Fill in the form:
    • Type — choose the entry type (rule, pattern, decision, warning, fact, etc.)
    • Title — a short, descriptive name
    • Body — the full content (markdown supported)
    • Scope — optional area tag like frontend, api, database
    • Priority — set to High for entries that should load automatically at session start
    • Tags — comma-separated keywords for retrieval (e.g. css, frontend, code-standards)
  4. Click Save

Repeat for each piece of knowledge. Here are the most useful types to start with:

  • Rules — hard constraints the agent must always follow (e.g. "All CSS in external files", "Never commit .env")
  • Decisions — architectural choices with rationale so the agent doesn't re-open settled debates
  • Patterns — how things are done in your codebase, so the agent follows existing conventions
  • Warnings — known gotchas and pitfalls, often the most valuable entries
  • Facts — stack, hosting, environment details that ground the agent in reality

From the API

Use POST /v1/context/entries for individual entries:

curl -X POST https://api.minolith.io/v1/context/entries \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "rule",
    "title": "All CSS in external files",
    "body": "Never use inline styles or <style> blocks in templates. All styles go in external CSS files under assets/css/.",
    "tags": ["css", "frontend", "code-standards"],
    "scope": "frontend",
    "priority": "high"
  }'

For bulk loading, use POST /v1/context/entries/bulk to create up to 50 entries at once:

curl -X POST https://api.minolith.io/v1/context/entries/bulk \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "type": "rule",
        "title": "Never commit .env files",
        "body": "Environment files contain credentials and must never be committed to git.",
        "tags": ["security", "git"],
        "priority": "high"
      },
      {
        "type": "fact",
        "title": "Project stack",
        "body": "Next.js 14 (App Router), TypeScript, Tailwind CSS, Prisma ORM, PostgreSQL 16. Hosted on Vercel (frontend) and Railway (database).",
        "tags": ["stack", "infrastructure"],
        "scope": "platform"
      }
    ]
  }'

The bulk endpoint is much faster when you have a lot of entries to create.

Tips for writing good context

  • Use tags generously. Tags are how your agent finds relevant entries. More tags = better retrieval.
  • Set a scope for entries that apply to a specific area (e.g. frontend, api, database).
  • Mark critical entries as high priority. These are loaded automatically at session start via bootstrap.
  • Write for someone who has never seen the codebase. Your agent starts each session fresh.
  • Keep entries focused. One rule per entry, one decision per entry. Don't bundle unrelated things together.

Step 2: Create an Agent Definition

An agent definition gives your AI a role, responsibilities, and instructions. When the agent calls bootstrap, it receives this definition and knows how to behave.

From the dashboard

  1. Click Agents in the project sidebar
  2. Click Create Agent
  3. Fill in the form:
    • Name — a lowercase identifier like orchestrator or code-reviewer
    • Role — one-line description (e.g. "Senior full-stack developer for the Acme project")
    • Prompt — the full system prompt with responsibilities, communication style, and domain knowledge
    • Is Main — set to Yes for the primary agent that bootstrap will return. Only one agent can be the main orchestrator.
    • Tags — e.g. main, orchestrator
    • Tools Allowed / Denied — optional JSON arrays to control which tools the agent can use
  4. Click Create

You can also browse the Agent Registry for pre-built templates. Click Registry at the top of the Agents page, find a template that fits, and install it with one click. Installed templates are fully editable.

From the API

curl -X POST https://api.minolith.io/v1/agents/ \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orchestrator",
    "role": "Senior full-stack developer for the Acme project.",
    "prompt": "You are the lead developer on the Acme project.\n\n1. Follow all rules and patterns stored in context.\n2. After completing work, store new knowledge with store_context.\n3. Log deployments with log_event.\n4. Push back on requests that violate established rules.",
    "tags": ["main", "orchestrator"]
  }'

Step 3: Set Up Runbooks (Optional)

If your team has repeatable procedures — deployments, incident response, onboarding — define them as runbooks so your agent can follow them step by step.

From the dashboard

Runbooks can be edited and managed from the dashboard, but new runbooks must be created via the API or MCP tools. Once created, you can view, edit, and manage them from the Runbooks page in the sidebar.

From the API

curl -X POST https://api.minolith.io/v1/runbooks/ \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Deployment",
    "description": "Standard deployment procedure for the main application.",
    "category": "deployment",
    "tags": ["deployment", "production"],
    "variables": ["version", "changelog_entry"],
    "steps": [
      {
        "type": "check",
        "title": "All tests passing",
        "instruction": "Run the full test suite and confirm all tests pass."
      },
      {
        "type": "action",
        "title": "Update version number",
        "instruction": "Update the version in package.json to {{version}}."
      },
      {
        "type": "gate",
        "title": "Approval to deploy",
        "instruction": "Confirm with the user that the changes are ready for production."
      },
      {
        "type": "action",
        "title": "Deploy",
        "instruction": "Push to main branch to trigger the deployment pipeline."
      },
      {
        "type": "check",
        "title": "Verify deployment",
        "instruction": "Check that the new version is live and healthy."
      }
    ]
  }'

Runbooks support four step types:

  • action — do something
  • check — verify a condition
  • gate — wait for human approval before continuing
  • branch — take different paths based on an outcome

Step 4: Define Your Design System (Optional)

If your project has an established visual language, define it in the Styleguide so your agent builds UI that matches.

Tokens — from the dashboard

  1. Click Styleguide in the project sidebar
  2. Click Tokens
  3. Click into a section (colours, typography, spacing, borders, shadows, or breakpoints) or create one
  4. Edit the JSON data for that section — this is a free-form JSON object containing your token values
  5. Click Save

Tokens — from the API

curl -X POST https://api.minolith.io/v1/styleguide/tokens \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "section": "colours",
    "data": {
      "primary": "#00d4aa",
      "background": "#0a0a0f",
      "surface": "#12121a",
      "text": "#e8e8f0",
      "border": "#2a2a3a",
      "danger": "#ef4444",
      "success": "#10b981"
    }
  }'

Components — from the dashboard

  1. Go to Styleguide → Components
  2. Click Create Component
  3. Fill in:
    • Name — lowercase with hyphens (e.g. button, card, modal)
    • Description — what the component is and when to use it
    • Variants — JSON object defining the component's visual variants
    • Sizes — JSON object for size overrides (optional)
    • Notes — additional usage guidance
  4. Click Create

Components — from the API

curl -X POST https://api.minolith.io/v1/styleguide/components \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "button",
    "description": "Primary interactive element. All buttons use .btn base class plus a variant modifier.",
    "usage_notes": "Always use a variant class. Never style buttons with inline styles.",
    "variants": ["primary", "outline", "danger", "ghost"],
    "sizes": ["sm", "md", "lg"]
  }'

Patterns and Voice — from the dashboard

Patterns and voice rules follow the same flow:

  1. Go to Styleguide → Patterns or Styleguide → Voice
  2. Click Create
  3. Fill in the name, description, definition/rules (as JSON), and optional notes
  4. Click Create

Patterns and Voice — from the API

# Pattern
curl -X POST https://api.minolith.io/v1/styleguide/patterns \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crud-list-page",
    "description": "Standard list page with filter form, data table, and pagination.",
    "definition": {
      "structure": ["filter-form", "data-table", "pagination"],
      "empty_state": "Always show an empty state with a CTA when the list has no data."
    }
  }'

# Voice rule
curl -X POST https://api.minolith.io/v1/styleguide/voice \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "error-messages",
    "description": "Voice rules for error messages across the application.",
    "rules": "Be specific about what went wrong. Tell the user what to do next. Never blame the user. Keep it under two sentences."
  }'

Assets — from the dashboard

  1. Go to Styleguide → Assets
  2. Click Upload Asset
  3. Fill in:
    • File — select an image file (PNG, SVG, JPG, WebP, GIF, ICO — max 5 MB)
    • Name — lowercase with hyphens (e.g. logo-dark, icon-cube)
    • Description — what the asset is
    • Usage Rules — constraints on use (e.g. "Only use on dark backgrounds. Minimum width 120px.")
    • Usage Context — where the asset should be used (e.g. "Site header, email templates")
    • Tags — comma-separated keywords
  4. Click Upload

Assets — from the API

curl -X POST https://api.minolith.io/v1/styleguide/assets \
  -H "Authorization: Bearer mlth_yourkey" \
  -F "file=@/path/to/logo.svg" \
  -F "name=logo-dark" \
  -F "description=Main logo for dark backgrounds" \
  -F "usage_rules=Apply filter: invert(1) for light backgrounds. Minimum width 120px." \
  -F "usage_context=Site header, documentation, email templates" \
  -F "tags[]=logo" \
  -F "tags[]=branding" \
  -F "tags[]=svg"

Step 5: Upload Foundation Documents (Optional)

If your project has briefs, PRDs, brand guidelines, reference spreadsheets, architecture diagrams, or other foundational files, upload them to the Documents service. Your agent will see a summary of available documents at session start via bootstrap, and can fetch details or download URLs when needed.

From the dashboard

  1. Click Documents in the project sidebar
  2. Click Upload Document
  3. Fill in the form:
    • File — select your document (PDF, Word, Excel, PowerPoint, images, markdown, CSV, JSON, ZIP — max 50 MB)
    • Title — a descriptive name for the document
    • Description — what this document is and why it matters (optional, markdown supported)
    • Priority — set to High for key foundation documents so they appear in the bootstrap summary
    • Scope — optional area tag (e.g. brand, api, design)
    • Tags — comma-separated keywords for filtering
  4. Click Upload

Tips for organising documents

  • Set high priority on the documents your agent needs to know about — project briefs, brand guidelines, architecture overviews. Bootstrap returns high-priority document titles so the agent knows to query them.
  • Use scope and tags consistently with your context entries. If your context uses scope: brand, tag your brand guidelines document with the same scope.
  • Write a clear description. Your agent sees the title and description but not the file content. A good description tells the agent when to download the full file.
  • Don't duplicate context entries. Documents are for files that need to stay as files (PDFs, spreadsheets, images). If the content can be expressed as text, use a context entry instead — it's searchable and directly readable by the agent.

Step 6: Create Tasks (Optional)

If you already know what your agent should work on, create tasks upfront so they appear at session start via bootstrap. Tasks pair with agent definitions — assign tasks to specific agents and they'll pick them up automatically.

From the dashboard

  1. Click Tasks in the project sidebar
  2. Click Create Task
  3. Fill in:
    • Title — what needs to be done
    • Category — task, bug, feature, idea, issue, or discussion
    • Description — details and acceptance criteria (markdown supported)
    • Priority — low, normal, high, or urgent
    • Assign to — select an agent or team member
    • Tags — comma-separated keywords
  4. Click Create Task

From the API

curl -X POST https://api.minolith.io/v1/tasks/ \
  -H "Authorization: Bearer mlth_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Set up CI/CD pipeline",
    "description": "Configure GitHub Actions for automated testing and deployment.",
    "category": "task",
    "priority": "high",
    "assignee_type": "agent",
    "assignee_id": "agt_your_agent_id",
    "tags": ["devops", "ci", "setup"]
  }'

Your agent will see assigned tasks in the bootstrap response under assigned_tasks, grouped by status. Agents can also call get_my_tasks to check for work at any point during a session.

Step 7: Verify with Bootstrap

Once you've populated your data, test that everything loads correctly.

From the dashboard

Open your project and check each section in the sidebar — Context, Agents, Styleguide, Runbooks, Documents. Everything you created should appear in the listings.

For agents, click Bootstrap at the top of the Agents page to see exactly what the bootstrap call will return to your agent.

From the API

curl https://api.minolith.io/v1/bootstrap \
  -H "Authorization: Bearer mlth_yourkey"

You should see your agent definition, high-priority context entries, styleguide summary, documents summary, and any active runbook runs in the response. This is exactly what your AI agent will receive when it starts a session.

Let Your Agent Do It

Everything above uses the dashboard or REST API, but you can also frontload through the MCP server if you've already connected it. Start a conversation with your AI agent and give it the raw material:

"I want to set up the project knowledge base. Here are our coding rules, architecture decisions, and known gotchas. Please store each of these as context entries with appropriate types, tags, and scopes."

Then paste your rules, decisions, and patterns. The agent will call store_context for each one. This is often faster than creating entries by hand, especially for large amounts of unstructured knowledge.

You can also provide your project brief or README and ask the agent to extract the knowledge:

"Here is our project README. Please read through it and store the important rules, patterns, facts, and decisions as context entries."

What to Frontload First

If you're not sure where to start, prioritise in this order:

  1. Rules — what must always (or never) be done. These prevent the most mistakes.
  2. Facts — stack, hosting, environment details. These ground the agent in reality.
  3. Decisions — why things are the way they are. These prevent re-litigation.
  4. Warnings — known gotchas. These prevent known bugs from being reintroduced.
  5. Agent definition — so bootstrap returns a useful identity from session one.
  6. Foundation documents — briefs, PRDs, brand guidelines. Upload once, reference forever.
  7. Tasks — pre-assigned work items so the agent knows what to do from session one.
  8. Patterns — how things are done. These ensure consistency.
  9. Runbooks — repeatable procedures. These ensure correctness.
  10. Styleguide — design tokens and components. These ensure visual consistency.

You don't need to do everything at once. Even a handful of high-priority rules and a brief agent definition will make a noticeable difference in your first session.

Last updated: 6 Apr 2026