Authoring context

Everything you author lives in workspace/<org>/ as YAML + markdown. This guide covers the edit + apply loop.

Directory layout

workspace/<org>/
├── workspace.yaml                # manifest: orgId, name, optional retrieval overrides
├── sources/<slug>/source.yaml  # connector config (Phase 5)
├── objects/<slug>/
│   ├── type.yaml
│   └── classification-prompt.md
├── skills/<slug>/
│   ├── skill.yaml
│   └── prompt.md
├── workflows/<slug>/workflow.yaml
└── agents/
    ├── <slug>.yaml
    └── <slug>.system-prompt.md

The three commands

npm run workspace:check    # validate + diff, no writes
npm run workspace:apply    # sync to DB; records a workspace_version audit row
npm run workspace:export   # bootstrap: dump current DB rows back to workspace/<org>/

workspace:apply is idempotent — running it twice is a no-op. It touches only the rows that changed since the last apply.

Every apply bumps workspace_version.sha and every skill_run stamps workspace_sha so any output traces back to the exact commit that produced it.

Editing

From a text editor

Open the YAML / markdown in your editor, save, npm run workspace:apply. That's it.

From an MCP client (Claude Code, Cursor, Zed, …)

The MCP server exposes workspace_write_skill, workspace_write_agent, workspace_write_object_type, workspace_write_source, and workspace_delete. These write to disk and call workspace:apply automatically. Git is not auto-handled — commit and push yourself.

See MCP reference.

From the dashboard

Drilldown pages (/dashboard/skills/<slug>, /dashboard/agents/<slug>, …) render the backing YAML + markdown files. Full in-app editing via CodeMirror is on the roadmap.

Git workflow

Vocion does not commit for you. Your workspace directory is a normal git repo:

# after editing + applying
cd workspace/metacto
git add .
git commit -m "feat(skill): add discovery_summary"
git push

The dashboard shows a small dirty badge on resource pages when your workspace repo has uncommitted changes.

Multi-tenant

Each tenant gets its own workspace/<org>/ directory (or, for production, its own git repo — see extract-tenant). Set WORKSPACE_PATH and VOCION_ORG_NAME to point at the tenant you're working on; workspace:apply scopes writes by orgId automatically.

Extract a tenant repo
Writing a plugin — when workspace-as-code isn't enough