Project Workspace
In DotCraft, the workspace is your project folder. Everything the agent builds up there — sessions, long-term memory, skills, automations, plugins, and model choices — lives in one .craft/ folder at the project root. It travels with the project: commit it alongside your code, back it up, sync it to another machine, or hand it to a teammate, and they open the same agent you do.
One Workspace per Project
Many agents share a single workspace across every project; DotCraft gives each project its own. A project's .craft/ holds only that project's memory, skills, automations, and model choices, so each project stays independently configured and isolated from the rest. Desktop can keep several of these workspaces open at once and switch between them in place.
Key Concepts
| Concept | Meaning |
|---|---|
| Workspace | Project root that contains a .craft/ directory. Desktop, TUI, ACP, bots, and automations all act on the same workspace. |
| Bootstrap files | .craft/AGENTS.md, .craft/SOUL.md, .craft/USER.md — agent rules, personality, and user profile. |
| Memory & History | .craft/MEMORY.md and .craft/HISTORY.md — long-term memory and history maintained by the agent and readable by humans. |
| Skills / Plugins | .craft/skills/ and .craft/plugins/ — capability bundles that travel with the workspace. |
| Sessions | .craft/sessions/ and .craft/threads/ — conversation archives shared by every entry point. |
| Config | .craft/config.json — workspace-level config layered on top of global ~/.craft/config.json. |
Why Organized This Way
Every entry point reads the workspace before doing anything. That means:
- Switching entry points never loses context: a session opened in Desktop continues in TUI.
- Restoring on another machine costs nothing: sync the project directory.
- Teams share one baseline: commit the shareable parts of
.craft/(skills, commands, AGENTS.md) and every teammate's Desktop boots with the same agent constraints.
The generated .craft/.gitignore filters generated artifacts such as logs, caches, terminal captures, Dreams run snapshots, databases, and managed worktrees. It is not a privacy boundary. If a project's .craft/ should stay private, ignore .craft/ from the repository root.
Global vs Workspace Config
DotCraft layers two configuration files:
| Layer | Path | Purpose |
|---|---|---|
| Global | ~/.craft/config.json | Provider credentials, endpoints, personal preferences — not committed |
| Workspace | <workspace>/.craft/config.json | Model selection, entry-point switches, automations, security — committable |
When in doubt: put providers globally and let the workspace override only the project-specific choices. Provider fields, entry switches, memory, skills, automations, and security options all live in the Configuration Reference.
Bootstrap Trio
Three Markdown files under .craft/ define the agent's identity and rules for this project:
AGENTS.md— role responsibilities, behavior boundaries, answer rulesSOUL.md— personality, tone, expression styleUSER.md— user profile, audience background, communication preferences
They are plain Markdown with no special syntax. DotCraft injects them into the system prompt at every session start.
First Entry
| Step | Command or action |
|---|---|
| Open in Desktop | Launch Desktop → choose project folder → follow setup |
| Init from terminal | cd <project> → dotcraft setup and answer prompts |
| Verify | In Desktop, ask "Read README and docs/index.md and tell me how to start the project" |
Full walkthrough: Getting Started.