Documents & Contexts

VibeFlow manages two types of knowledge artifacts: Documents (versioned design artifacts) and Contexts (living project memory). Both are stored as markdown and are essential for agents to understand your project before writing code.

Documents

Documents are formal design artifacts attached to projects or features.

Document Types

Creating Documents

1. Navigate to a project or feature
2. Click + New Document
3. Enter:
   • Title — Descriptive name
   • Type — Select from the types above
   • Content — Markdown content
4. The document is automatically attached to the project or feature

How Agents Use Documents

Before implementing any work item, agents are instructed to load and read all relevant documents. This ensures:

• PRDs define the "what" and "why"
• Architecture docs define the "how"
• Style guides ensure consistency
• Design systems prevent duplicate component creation

Contexts

Contexts are living documents that capture project knowledge, conventions, and session history. They are the persistent memory of your project.

Context Levels

How Contexts Work

• Project context ({project-name}-context.md) — Updated by agents after every work session. Contains recent work summary, active documents, known patterns, and cross-feature conventions.
• Feature context ({feature-name}-context.md) — Updated when agents work on a feature. Contains feature-specific architecture, checklists, gotchas, and current state.

Contexts are the primary mechanism for knowledge transfer between agent sessions. When a new session starts, the agent reads the project context to understand what was done before and what conventions to follow.

Creating and Editing Contexts

Contexts are typically created and maintained by agents automatically. You can also:

1. Create a context manually from the project or feature view
2. Edit context content directly in the markdown editor
3. Add context notes that agents should follow

Assets

Assets are files (images, screenshots, PDFs) that can be attached to any entity.

Uploading Assets

1. Navigate to a project, feature, todo, or issue
2. Click Upload Asset
3. Select a file from your computer
4. The asset is automatically attached and accessible

Images are auto-converted to WebP format for optimal size. Assets are stored in your configured object storage (S3, MinIO, R2, etc.).

Attachments

Attachments link documents and assets to entities:

Attachments are categorized: design_system, architecture, requirements, or general.

Review Comments

Documents and contexts support section-level review comments:

1. Open a document
2. Find the section (## heading) you want to comment on
3. Click the comment icon
4. Write your review comment
5. Comments appear inline, anchored to the section heading

This enables collaborative review of design docs before implementation.

Public Sharing

Share documents and contexts with external stakeholders:

1. Open a document or context
2. Click Share
3. Generate a public link (with optional expiration date)
4. Anyone with the link can view the content (read-only)

Public share links do not expose author email addresses (GDPR/SOC 2 compliance).