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
| Type | Use Case | Examples |
|---|---|---|
| PRD | Product requirements | Feature specs, user stories |
| Architecture | System design | API designs, data models, component diagrams |
| Style Guide | Visual/code standards | CSS conventions, naming patterns |
| Design System | Component library | Reusable components, tokens, patterns |
| General | Everything else | Meeting notes, onboarding guides |
Creating Documents
- Navigate to a project or feature
- Click + New Document
- Enter:
- Title — Descriptive name
- Type — Select from the types above
- Content — Markdown content
- 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
| Level | Scope | Examples |
|---|---|---|
| Project Context | Entire project | Architecture overview, migration version, known patterns, cross-feature conventions |
| Feature Context | Single feature | Feature-specific patterns, gotchas, design decisions, last work done |
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:
- Create a context manually from the project or feature view
- Edit context content directly in the markdown editor
- Add context notes that agents should follow
Recovering cleanup of legacy context bodies (operators)
Deleting or replacing a stored context queues its old object for retirement.
New uploads record their storage destination; cleanup checks it before deletion.
Bodies uploaded before this provenance was recorded have an unknown destination.
They remain in vibeflow_context_body_cleanup until an operator verifies the
original bucket. A matching key prefix does not prove which bucket holds the
original body. Deployments with legacy stored contexts need this recovery step
as those bodies are deleted or replaced.
Build the maintenance command from the same revision as the deployed server:
cd axiomcloud
go build -mod=vendor -o context-body-recovery ./cmd/context-body-recovery
Use an authorized maintenance account with database and storage access. As with
context-dedup, opening the database runs normal startup migrations and
reconciliation, even in inspection mode. Apply deployment migrations first and
use the normal maintenance window/backup procedure. Inspection does not change
the cleanup job or delete objects. Supply the database DSN via DATABASE_URL
instead of putting credentials in command history.
-
Find unknown destinations using your database client. Substitute the exact organization ID; process at most 100 jobs per batch and advance
:after_idfrom the last ID returned (start with an empty string):SELECT id, storage_key, user_id, not_before FROM vibeflow_context_body_cleanup WHERE organization_id = :org_id AND storage_target = '' AND id > :after_id ORDER BY id LIMIT 100; -
Verify the original provider, endpoint, bucket and region using upload logs, storage inventory or configuration history. Choose a resolver user whose storage settings point to that destination with valid credentials. Use
-user 0only for the cloud configuration; another user falls back to cloud storage when personal storage is disabled. If necessary, configure a dedicated recovery user's storage for the original bucket. Do not repoint active upload users merely to recover an old job. -
Inspect one job (use
-driver sqlitefor SQLite):./context-body-recovery -driver postgres -org "$ORG_ID" -job "$JOB_ID" -user "$RESOLVER_USER_ID"The command checks that no live context references the key and that the object exists, then prints the key, bucket and destination fingerprint. Existence alone is not proof of origin: a copy may exist in another bucket. Compare against the records from step 2. Credentials and body text are never printed. If the original destination cannot be established, retain the job and investigate; do not edit its target directly or remove it from the queue.
-
Explicitly bind the verified destination using the fingerprint printed by inspection:
./context-body-recovery -driver postgres -org "$ORG_ID" -job "$JOB_ID" -user "$RESOLVER_USER_ID" -apply -expect-target "$VERIFIED_TARGET"Apply refuses a changed destination, absent object, live reference or an already bound job. It changes only this job's resolver and target, preserving its grace period. Keep that resolver configured until cleanup completes. The existing leader worker processes up to 100 due jobs per sweep (default interval 15 minutes) and performs deletion. A destination change or provider error keeps the job queued for retry. Credential rotation is supported.
-
Verify the job disappears from the queue and the original object is absent in storage. If the job is already bound but pending, restore its recorded original destination/credentials and inspect cleanup logs; this command deliberately cannot overwrite known provenance. Recovery applies to the retired object; bucket version retention/lifecycle policies remain the storage administrator's responsibility.
Assets
Assets are files (images, screenshots, PDFs) that can be attached to any entity.
Uploading Assets
- Navigate to a project, feature, todo, or issue
- Click Upload Asset
- Select a file from your computer
- 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:
| Entity | Can Attach |
|---|---|
| Project | Documents, Assets |
| Feature | Documents, Assets |
| Todo | Documents, Assets |
| Issue | Documents, Assets |
Attachments are categorized: design_system, architecture, requirements, or general.
Review Comments
Documents and contexts support section-level review comments:
- Open a document
- Find the section (## heading) you want to comment on
- Click the comment icon
- Write your review comment
- 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:
- Open a document or context
- Click Share
- Generate a public link (with optional expiration date)
- Anyone with the link can view the content (read-only)
Public share links do not expose author email addresses (GDPR/SOC 2 compliance).