# Project Workspace

DotCraft anchors every AI workflow to a real project directory. When you open a project, its conversation history, skills, long-term memory, automations, plugins, and model selection live in a single `.craft/` directory that is backed up, shared, and restored together with the repository — never scattered across a cloud account, a system prompt, or a single editor window.

> One project, one workspace, one persistent Agent state.

## 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

```mermaid
flowchart TB
  subgraph Workspace[" Project workspace "]
    direction TB
    Code["Code / docs"]
    Craft[".craft/"]
    Craft -->|identity| Bootstrap["AGENTS.md / SOUL.md / USER.md"]
    Craft -->|long context| Memory["MEMORY.md / HISTORY.md"]
    Craft -->|reusable flows| Skills["skills/ · plugins/"]
    Craft -->|session archive| Sessions["sessions/ · threads/"]
    Craft -->|project config| Config["config.json"]
  end

  Desktop --> Workspace
  TUI --> Workspace
  Editor["IDE / Editor (ACP)"] --> Workspace
  Channels["Channels / Bots"] --> Workspace
  Automations --> Workspace
```

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.

## 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 |

Minimal workspace config:

```json
{
  "ProviderId": "anthropic",
  "Model": "claude-sonnet-4-5",
  "DashBoard": { "Enabled": true }
}
```

```json
{
  "Providers": {
    "anthropic": {
      "DisplayName": "Anthropic",
      "Protocol": "anthropic",
      "ApiKey": "${ANTHROPIC_API_KEY}"
    },
    "openrouter": {
      "DisplayName": "OpenRouter",
      "Protocol": "openai-chat-completions",
      "ApiKey": "${OPENROUTER_API_KEY}",
      "EndPoint": "https://openrouter.ai/api/v1"
    }
  }
}
```

When in doubt: **put providers globally and let the workspace override only `ProviderId` and `Model`**. Full field reference: [Configuration Reference](../developing/configuration.md).

## Bootstrap Trio

The three Markdown files under `.craft/` decide "who this agent is in this project and what rules it follows":

- `AGENTS.md` — role responsibilities, behavior boundaries, answer rules
- `SOUL.md` — personality, tone, expression style
- `USER.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. The repository ships [Bootstrap templates](../resources/samples.md) for `senior-engineer` and `qq-group-assistant`.

## 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](../getting-started.md).

## When to Enable / Disable

Workspace switches at a glance (defaults):

| Capability | Setting | Default |
|---|---|---|
| Long-term memory consolidation | `Memory.AutoConsolidateEnabled` | `true` |
| Skill self-learning | `Skills.SelfLearning.Enabled` | `true` |
| Dashboard | `DashBoard.Enabled` | `false` |
| Local automations | `Automations.Enabled` | `true` |
| ACP editors | `Acp.Enabled` | `false` |

Treat entry switches (ACP and external channels) and behavior switches (Memory / Skills / Automations) as separate axes.

## Related

- [Getting Started](../getting-started.md)
- [Memory & Dreams](./memory.md)
- [Unified Session Core](./session-core.md)
- [Security & Sandbox](./security.md)
- [Configuration Reference](../developing/configuration.md)
