spacedriveapp · jamiepine · Mar 8, 2026 · Mar 4, 2026 · Mar 7, 2026 · Mar 7, 2026
diff --git a/docs/content/docs/(configuration)/config.mdx b/docs/content/docs/(configuration)/config.mdx
@@ -284,7 +284,7 @@ A file watcher (via the `notify` crate) monitors:
 
 - `~/.spacebot/config.toml`
 - `~/.spacebot/skills/` (instance-level skills)
-- Each agent's `workspace/` (identity files: SOUL.md, IDENTITY.md, USER.md)
+- Each agent's root directory (identity files: SOUL.md, IDENTITY.md, ROLE.md)
 - Each agent's `workspace/skills/` (workspace-level skills)
 
 On file change, Spacebot re-reads the changed files and atomically swaps the new values into the live `RuntimeConfig` using `arc-swap`. All consumers (channels, branches, workers, compactors, cron jobs) read from `RuntimeConfig` on every use, so they pick up changes immediately.
@@ -315,10 +315,10 @@ System prompts (channel, branch, worker, compactor, cortex, etc.) are Jinja2 tem
 │       └── SKILL.md
 └── agents/
     └── main/
-        ├── workspace/             # agent workspace
-        │   ├── SOUL.md            # personality (hot-reloaded)
-        │   ├── IDENTITY.md        # name and nature (hot-reloaded)
-        │   ├── USER.md            # info about the human (hot-reloaded)
+        ├── SOUL.md                # personality (hot-reloaded)
+        ├── IDENTITY.md            # name and nature (hot-reloaded)
+        ├── ROLE.md                # responsibilities, scope (hot-reloaded)
+        ├── workspace/             # sandbox boundary for worker file tools
         │   ├── skills/            # workspace-level skills (hot-reloaded)
         │   └── ingest/            # drop files here for memory ingestion
         ├── data/

diff --git a/docs/content/docs/(configuration)/permissions.mdx b/docs/content/docs/(configuration)/permissions.mdx
@@ -41,11 +41,13 @@ Values:
 Workspace confinement means the agent can access:
 
 ```
-~/.spacebot/agents/{agent_id}/workspace/   # identity files, prompt overrides
+~/.spacebot/agents/{agent_id}/workspace/   # working files, prompt overrides (sandbox boundary)
 ~/.spacebot/agents/{agent_id}/data/        # databases (read-only for file tool, managed by Spacebot)
 ~/.spacebot/agents/{agent_id}/archives/    # compaction archives
 ```
 
+Identity files (`SOUL.md`, `IDENTITY.md`, `ROLE.md`) live in the agent root (`~/.spacebot/agents/{agent_id}/`), outside the workspace, and are not accessible to worker file tools.
+
 But NOT:
 
 ```

diff --git a/docs/content/docs/(configuration)/sandbox.mdx b/docs/content/docs/(configuration)/sandbox.mdx
@@ -86,7 +86,7 @@ When the sandbox is enabled, the subprocess sees:
 | `/dev` | Read-write | Standard device nodes |
 | Agent data directory | **No access** | Masked/denied to protect databases and config |
 
-The data directory protection is important: even if the data directory overlaps with workspace-related paths, it's explicitly blocked. Workers can't read or modify databases, config files, or identity files at the kernel level.
+The data directory protection is important: even if the data directory overlaps with workspace-related paths, it's explicitly blocked. Workers can't read or modify databases or config files at the kernel level. Identity files (`SOUL.md`, `IDENTITY.md`, `ROLE.md`) live in the agent root directory, outside the workspace entirely, so they are naturally inaccessible to workers without needing kernel-level protection.
 
 ## Environment Sanitization
 

diff --git a/docs/content/docs/(configuration)/secrets.mdx b/docs/content/docs/(configuration)/secrets.mdx
@@ -72,6 +72,16 @@ config.toml value (secret: / env: / literal)
 
 If `anthropic_key` is set to `"secret:ANTHROPIC_API_KEY"` and the secret store has that key, it resolves to the stored value. If the store doesn't have it, the key is treated as missing and the implicit env fallback is tried.
 
+## Integration Setup
+
+Tool secrets are the authentication layer for external integrations. The typical setup flow:
+
+1. **Create a credential** from the external service (e.g. a GitHub personal access token)
+2. **Store it as a tool secret** using the name the CLI tool expects (e.g. `GH_TOKEN` for `gh`)
+3. **Install a matching skill** from [skills.sh](https://skills.sh) that teaches workers how to use the tool
+
+See [Skills — Setting Up an Integration](/docs/features/skills#setting-up-an-integration) for a complete walkthrough.
+
 ## How Secrets Reach Subprocesses
 
 Tool-category secrets are injected into worker subprocesses as environment variables. The flow:

diff --git a/docs/content/docs/(core)/agents.mdx b/docs/content/docs/(core)/agents.mdx
@@ -13,7 +13,8 @@ Agents communicate through an explicit communication graph — directed links th
 
 An agent is a self-contained unit. It has:
 
-- **A workspace** — directory containing identity files (SOUL.md, IDENTITY.md, USER.md, ROLE.md) and optional prompt overrides
+- **Identity files** — `SOUL.md`, `IDENTITY.md`, and `ROLE.md` in the agent root directory (`~/.spacebot/agents/{id}/`)
+- **A workspace** — sandboxed directory (`~/.spacebot/agents/{id}/workspace/`) for working files, ingest, and prompt overrides; this is the boundary for worker file tools
 - **Its own databases** — SQLite, LanceDB, and redb, completely isolated from other agents
 - **Its own cortex** — monitoring its own processes and memory graph
 - **Its own conversations** — channels, branches, workers scoped to this agent
@@ -224,11 +225,10 @@ Returns agents, humans, links, and groups for rendering.
 │
 ├── agents/
 │   ├── research/
-│   │   ├── workspace/
-│   │   │   ├── SOUL.md                   # personality, values, boundaries
-│   │   │   ├── IDENTITY.md               # name, nature, vibe
-│   │   │   ├── USER.md                   # info about the human
-│   │   │   └── ROLE.md                   # responsibilities, scope, escalation rules
+│   │   ├── SOUL.md                       # personality, values, boundaries
+│   │   ├── IDENTITY.md                   # name, nature, vibe
+│   │   ├── ROLE.md                       # responsibilities, scope, escalation rules
+│   │   ├── workspace/                    # sandbox boundary for worker file tools
 │   │   ├── data/
 │   │   │   ├── spacebot.db              # SQLite (memories, conversations, cron jobs)
 │   │   │   ├── lancedb/                 # LanceDB (embeddings, FTS)

diff --git a/docs/content/docs/(core)/architecture.mdx b/docs/content/docs/(core)/architecture.mdx
@@ -412,7 +412,7 @@ src/
 
 **The compactor is not an LLM.** It's a programmatic monitor that watches a number and spawns workers. The LLM work happens in the workers it spawns.
 
-**Prompts are files.** System prompts live in `prompts/` as Jinja2 templates, not as string constants in Rust code. Identity files (SOUL.md, IDENTITY.md, USER.md, ROLE.md) are loaded from the agent's workspace directory.
+**Prompts are files.** System prompts live in `prompts/` as Jinja2 templates, not as string constants in Rust code. Identity files (SOUL.md, IDENTITY.md, ROLE.md) live in the agent root directory — outside the workspace sandbox — so worker file tools cannot access them.
 
 **Three databases, three purposes.** SQLite for relational queries, LanceDB for vector search, redb for key-value config. Each doing what it's best at.
 

diff --git a/docs/content/docs/(core)/cortex.mdx b/docs/content/docs/(core)/cortex.mdx
@@ -49,8 +49,8 @@ The bulletin is injected into the system prompt between identity context and the
 ## Identity
 [from IDENTITY.md]
 
-## User
-[from USER.md]
+## Role
+[from ROLE.md]
 
 ## Memory Context                    ← this is the bulletin
 [A concise briefing synthesized from eight memory dimensions:

diff --git a/docs/content/docs/(core)/memory.mdx b/docs/content/docs/(core)/memory.mdx
@@ -162,9 +162,9 @@ Not everything is a graph memory. Some context is stable, foundational, and user
 
 - **SOUL.md** -- core values, personality, tone
 - **IDENTITY.md** -- agent name, nature
-- **USER.md** -- user context
+- **ROLE.md** -- responsibilities, scope, escalation rules
 
-These are loaded into channel system prompts every time. They're files on disk, not database rows, because they change rarely and users should be able to edit them in a text editor.
+These are loaded into channel system prompts every time. They're files in the agent root directory (not the workspace), not database rows, because they change rarely and users should be able to edit them in a text editor.
 
 What's gone:
 

diff --git a/docs/content/docs/(core)/prompts.mdx b/docs/content/docs/(core)/prompts.mdx
@@ -242,7 +242,7 @@ let marker = engine.render_system_truncation(remove_count)?;
 
 ## No User Overrides
 
-Unlike identity files (SOUL.md, IDENTITY.md, USER.md), system prompts cannot be modified by users. This ensures:
+Unlike identity files (SOUL.md, IDENTITY.md, ROLE.md), system prompts cannot be modified by users. This ensures:
 
 - Updates ship reliably (no local modifications to overwrite)
 - Consistent behavior across deployments

diff --git a/docs/content/docs/(deployment)/roadmap.mdx b/docs/content/docs/(deployment)/roadmap.mdx
@@ -22,7 +22,7 @@ The full message-in → LLM → response-out pipeline is wired end-to-end across
 - **Model routing** — `RoutingConfig` with process-type defaults, task overrides, fallback chains
 - **Memory** — full stack: types, SQLite store (CRUD + graph), LanceDB (embeddings + vector + FTS), fastembed, hybrid search (RRF fusion). `memory_type` filter wired end-to-end through SearchConfig. `total_cmp` for safe sorting.
 - **Memory maintenance** — decay + prune implemented
-- **Identity** — `Identity` struct loads SOUL.md/IDENTITY.md/USER.md, `Prompts` with fallback chain
+- **Identity** — `Identity` struct loads SOUL.md/IDENTITY.md/ROLE.md from agent root, `Prompts` with fallback chain
 - **Agent loops** — all three process types run real Rig loops:
   - **Channel** — per-turn tool registration, status injection, `max_turns(5)`
   - **Branch** — history fork, `max_turns(10)`, memory tools, result injection

diff --git a/docs/content/docs/(features)/skills.mdx b/docs/content/docs/(features)/skills.mdx
@@ -20,6 +20,41 @@ Spacebot's skill system is fully compatible with [skills.sh](https://skills.sh)
 - **Worker injection** — skills are injected into worker system prompts, not channels
 - **Hot-reloadable** — file watcher picks up skill changes without restart
 
+## Setting Up an Integration
+
+Most external tool integrations follow the same pattern: **add a credential, install a skill**. Here's how to set up GitHub as an example — the same pattern applies to AWS, npm, Docker, and any other CLI tool.
+
+### Example: GitHub Integration
+
+1. **Create a GitHub personal access token** at [github.com/settings/tokens](https://github.com/settings/tokens) with the scopes you need (e.g. `repo`, `read:org`).
+
+2. **Store it as a tool secret** so workers can authenticate:
+
+   ```bash
+   spacebot secrets set GH_TOKEN
+   # Paste your token when prompted
+   ```
+
+   Or use the dashboard **Secrets** panel to add `GH_TOKEN` with your token value.
+
+3. **Install a GitHub skill** that teaches workers how to use the `gh` CLI:
+
+   ```bash
+   spacebot skill add anthropics/skills/github
+   ```
+
+   Or browse the **Skills** tab in the dashboard and search for "github".
+
+4. **Done.** Workers now have `GH_TOKEN` as an environment variable and can read the GitHub skill for instructions on creating PRs, managing issues, and more.
+
+### Why This Works
+
+- **Tool secrets** with names like `GH_TOKEN`, `NPM_TOKEN`, `AWS_ACCESS_KEY_ID` are automatically categorized as "tool" secrets and injected into every worker subprocess as environment variables.
+- **Skills** provide the procedural knowledge — they tell workers *how* to use the CLI tools that those credentials unlock.
+- Workers see the secret names in their system prompt and can call `read_skill` to load full instructions on demand.
+
+This pattern works for any external tool that authenticates via environment variables. See [Secret Store](/docs/configuration/secrets) for details on credential storage and auto-categorization.
+
 ## Installation
 
 ### Via CLI

diff --git a/docs/content/docs/(features)/tools.mdx b/docs/content/docs/(features)/tools.mdx
@@ -205,7 +205,7 @@ Shell and exec commands run inside an OS-level sandbox (bubblewrap on Linux, san
 
 Worker subprocesses also start with a clean environment -- they never inherit the parent's environment variables. System secrets (LLM API keys, messaging tokens) are never visible to workers regardless of sandbox mode. See [Sandbox](/docs/sandbox) for full details.
 
-The `file` tool independently validates paths against the workspace boundary and rejects writes to identity files (`SOUL.md`, `IDENTITY.md`, `USER.md`). The `exec` tool blocks dangerous environment variables (`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, etc.) that enable library injection regardless of sandbox state.
+The `file` tool independently validates all paths against the workspace boundary. Identity files (`SOUL.md`, `IDENTITY.md`, `ROLE.md`) live in the agent root directory (`~/.spacebot/agents/{id}/`), outside the workspace, so they are naturally inaccessible to worker file tools. The `exec` tool blocks dangerous environment variables (`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, etc.) that enable library injection regardless of sandbox state.
 
 Leak detection (via `SpacebotHook`) scans all tool output for secret patterns (API keys, tokens, PEM keys) and terminates the process if a leak is found. This includes base64-encoded, URL-encoded, and hex-encoded variants.
 

diff --git a/docs/content/docs/(features)/workers.mdx b/docs/content/docs/(features)/workers.mdx
@@ -156,7 +156,7 @@ The agent's data directory (databases, config files) is explicitly re-mounted re
 
 Worker subprocesses also start with a **clean environment**. Workers only receive `PATH` (with `tools/bin` prepended), safe variables (`HOME`, `USER`, `LANG`, `TERM`, `TMPDIR`), tool-category secrets from the [secret store](/docs/secrets), and any explicitly configured `passthrough_env` entries. `HOME` is mode-dependent: workspace path when sandboxed, parent `HOME` in passthrough mode. System secrets like LLM API keys are hidden by default unless explicitly forwarded via `passthrough_env`. Environment sanitization applies regardless of whether the sandbox is enabled or disabled.
 
-The `file` tool validates paths against the workspace boundary and rejects writes to identity/memory paths (for example `SOUL.md`, `IDENTITY.md`, `USER.md`) with an explicit error directing the LLM to the appropriate tool. The `exec` tool blocks dangerous environment variables (`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, etc.) that enable library injection.
+The `file` tool validates all paths against the workspace boundary. Identity files (`SOUL.md`, `IDENTITY.md`, `ROLE.md`) live in the agent root directory (`~/.spacebot/agents/{id}/`), outside the workspace, so they are naturally inaccessible to worker file tools — no special-case rejection is needed. The `exec` tool blocks dangerous environment variables (`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, etc.) that enable library injection.
 
 See [Sandbox](/docs/sandbox) for full details on containment, environment sanitization, leak detection, and durable binaries.
 

diff --git a/docs/content/docs/(getting-started)/docker.mdx b/docs/content/docs/(getting-started)/docker.mdx
@@ -48,7 +48,10 @@ All persistent data lives at `/data` inside the container. Mount a volume here.
 ├── embedding_cache/         # FastEmbed model cache (~100MB, downloaded on first run)
 ├── agents/
 │   └── main/
-│       ├── workspace/       # identity files (SOUL.md, IDENTITY.md, USER.md)
+│       ├── SOUL.md          # agent personality and voice
+│       ├── IDENTITY.md      # agent purpose and scope
+│       ├── ROLE.md          # agent responsibilities
+│       ├── workspace/       # working directory (sandbox boundary)
 │       ├── data/            # SQLite, LanceDB, redb databases
 │       └── archives/        # compaction transcripts
 └── logs/                    # log files (daily rotation)

diff --git a/docs/content/docs/(getting-started)/quickstart.mdx b/docs/content/docs/(getting-started)/quickstart.mdx
@@ -132,7 +132,8 @@ On first launch, Spacebot automatically creates:
 
 - `~/.spacebot/` — instance directory
 - `~/.spacebot/agents/main/data/` — SQLite, LanceDB, and redb databases
-- `~/.spacebot/agents/main/workspace/` — identity files and ingest directory
+- `~/.spacebot/agents/main/` — identity files (`SOUL.md`, `IDENTITY.md`, `ROLE.md`)
+- `~/.spacebot/agents/main/workspace/` — working files and ingest directory (sandbox boundary for worker file tools)
 
 ## Daemon management
 
@@ -147,15 +148,15 @@ Logs go to `~/.spacebot/agents/{id}/data/logs/` in daemon mode, or stderr in for
 
 ## Identity files
 
-Each agent has three optional markdown files in its workspace (`~/.spacebot/agents/{id}/workspace/`):
+Each agent has optional identity files in its root directory (`~/.spacebot/agents/{id}/`):
 
 | File          | Purpose                                  |
 | ------------- | ---------------------------------------- |
 | `SOUL.md`     | Personality, values, communication style |
 | `IDENTITY.md` | Name, nature, purpose                    |
-| `USER.md`     | Info about the human the agent talks to  |
+| `ROLE.md`     | Responsibilities, scope, escalation rules |
 
-Template files are created on first run. Edit them to shape the agent's personality. Changes are hot-reloaded (no restart needed).
+Template files are created on first run. Edit them to shape the agent's personality. Changes are hot-reloaded (no restart needed). These files live outside the workspace so they are not accessible to worker file tools.
 
 ## Development setup