Public manual · Updated 2026-06-10
VELA Research Workflow Environment
VELA is a portable research workflow environment for Codex. It gives each project a readable operating layer: folders, rules, handoffs, evidence ledgers, schemas, validators, logs, memory governance, and controlled evolution.
Not an app
VELA is not a desktop app, paper generator, citation manager, or background automation platform.
Engineering cybernetics
Objectives, state, feedback, validation, and correction stay visible in files, checks, and version history.
Seven layers
Tasks, tools, evidence, stages, logs, checks, and durable rules remain separated.
What VELA Actually Installs
| Part | Meaning | Result |
|---|
| Project order | Stable folders, Codex rules, handoff templates, and machine-readable state. | Future threads and collaborators can read the project without relying on chat history. |
| Tool governance | Skills, plugins, MCP servers, and local commands are routed through profiles and quality gates. | Tools open because the route needs them, not just because they are available. |
| Reviewable evolution | Failures, fixes, and reusable procedures become candidates for later review. | Stable experience can become durable rules only after checks and commits. |
The public package includes routes, public skills, MCP/profile templates, plugin coordination notes, schemas, validators, tests, envctl helpers, memory governance, and project folder hygiene. It does not include private databases, account state, browser sessions, cookies, tokens, caches, or personal custom modules outside the public research workflow.
Core Structure
| Module | Meaning | Contents |
|---|
| Source package | The VELA repository cloned from GitHub | package/, runtime/, schemas/, scripts/, docs/, tests/ |
| Local runtime | User-side runtime installed into Codex | ~/.vela, ~/.codex/skills, CLI, profiles, commands, receipts |
| Project layer | Each research project's files | materials/, evidence/, claims/, methods/, deliverables/, handoffs/, logs/ |
| Tool interface | Optional connectors to user-owned tools | Git, Python, ripgrep, native Browser/Chrome/Computer Use, route-scoped MCP servers, Codex plugins, Zotero, Obsidian |
| Memory and evolution | Candidate memory and governed rule promotion | logs, local memory contracts, CodeGraph, evolution backlog, validators |
| Layer | Windows | macOS / Linux | Role |
|---|
| Source package | cloned vela/ | cloned vela/ | Git-updated source, docs, schemas, tests, runtime package. |
| Local runtime | %USERPROFILE%\.vela, %USERPROFILE%\.codex | ~/.vela, ~/.codex | CLI shims, skills, profiles, commands, receipts, doctor reports. |
| Project layer | any project folder | any project folder | vela init scaffold and .vela/context.json. |
Seven Layers
| Layer | Purpose |
|---|
| 01 Task and boundary | Define objectives, scope, constraints, and review standard. |
| 02 Tools and interfaces | Decide which local tools, plugins, and MCP servers are needed. |
| 03 Context and evidence | Separate materials, evidence, claims, methods, and source notes. |
| 04 Research stage | Track design, literature, full text, analysis, writing, figures, submission, and retrospective stages. |
| 05 Runtime logs | Preserve handoffs, rendered prompts, doctor reports, validation reports, failures, and repairs. |
| 06 Reliability checks | Run schemas, validators, privacy scans, tests, and quality gates. |
| 07 Environment governance | Decide which reusable rules can persist through commits. |
| Question | Layer That Answers It |
|---|
| What is the task? | Task and boundary. |
| Which tools are needed? | Tools and interfaces. |
| What supports the decision? | Context and evidence. |
| Which research stage is this? | Research stage. |
| Is it reliable? | Reliability checks. |
| Can this experience persist? | Environment governance. |
Workflow Routes
| Route | Use it for | Boundary |
|---|
general-research | Initial research triage | Does not replace specialized routes. |
stack-governance / environment-ops | Runtime, skills, plugins, MCP, profiles, and configuration checks | Does not decide research facts. |
project-folder-hygiene | Project folder cleanup and handoff preparation | Does not silently delete raw material, data, PDFs, or evidence. |
evidence-based-literature-workflow / literature-review / reference-fulltext-acquisition | Literature, full text, citation evidence, and review workflows | Discovery is not formal citation. |
empirical-quant / text-corpus / network-analysis | Quantitative, text, and network analysis | Tools are actuators; evidence and reproducibility are deliverables. |
research-figure-design / research-presentation | Figures, tables, presentations, and web decks | No invented data or statistics. |
writing-export / social-science-submission-package | Writing, reviewer response, DOCX/LaTeX, and version freeze | Language polish must not change facts. |
Skills, Plugins, MCP
VELA routes combine active skills, optional Codex plugins, and MCP interfaces. Plugins and MCP servers are enhancement layers; schemas, validators, project files, and commits remain the governing layer. Browser-visible and desktop-visible material starts with native Browser, Chrome, and Computer Use.
Memory Boundary
Memory is a candidate signal. Thread memory intake reports are schema-checked, bounded candidates; VELA does not import full transcripts, store secrets, inject recalled context by default, or promote memory into durable rules without checks and review.
Thread Memory Intake
| Landing zone | Stores | Boundary |
|---|
| Project files | Project facts, evidence, stage, methods, deliverables | Project-scoped continuation and review. |
| Runtime logs | Commands, checks, failures, repairs, handoffs, validation reports | Debugging, rollback, and audit. |
| Thread memory intake report | Short task summary, evidence pointers, reusable procedure, risk notes, and recommended landing zone | Validated by thread_memory_intake_report.v1; no full chat, credentials, browser state, or private files. |
| Evolution backlog | Candidate rules, skills, schemas, automations | Only after review, validation, tests, and commits. |
Common Commands
| Goal | Command |
|---|
| Check runtime | vela doctor |
| Initialize project | vela init <project> |
| Create handoff | vela handoff new --template claim-check |
| Lint handoff | vela handoff lint handoffs/H001.yaml |
| Validate project | vela validate <project> --repair-context |
| Privacy scan | vela privacy scan <project> |
| Install runtime | vela runtime install --include core,automation,toolchain |
Dependencies And Runtime
| Type | Examples | How VELA Treats Them |
|---|
| Core | Git, Python, shell, VELA CLI, schemas, validators | installers and vela doctor check them directly. |
| Recommended | ripgrep, GitHub CLI, Node.js, PowerShell 7, Homebrew/winget | missing tools are reported, not faked. |
| Optional integrations | Zotero, Obsidian, MCP servers, Codex plugins, external memory-service patterns, CodeGraph | profiles, doctor checks, and adoption reviews are provided; user authorization is required. External memory services are not installed or prestarted by VELA. |
Automation Boundary
| Type | Purpose | Output |
|---|
| Environment audit | tool gaps, profile drift, MCP state, schema changes, runtime install state | doctor report, stack validation report |
| Project audit | project structure, evidence chain, handoffs, privacy risk, deliverables | validation report, privacy report, context repair |
| Evolution audit | reusable experience, conflicting rules, retired routes | evolution backlog, route conflict report, candidate patch |
