diff --git a/README.md b/README.md
index 27ae7934..fcf3c1b4 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,13 @@ A multi-component architecture for distributed agent systems.
 
 ```
 src/
-├── agent/      # Agent module
-├── gateway/    # Gateway module
-├── client/     # Client module
-└── shared/     # Shared types and utilities
+├── agent/          # Agent module
+│   ├── profile/    # Agent profile management
+│   ├── session/    # Session persistence
+│   └── tools/      # Agent tools (exec, process)
+├── gateway/        # Gateway module
+├── client/         # Client module
+└── shared/         # Shared types and utilities
 ```
 
 ## Getting Started
@@ -32,12 +35,77 @@ pnpm agent:cli --session demo "what's my name?"
 
 # Override provider/model
 pnpm agent:cli --provider openai --model gpt-4o-mini "hi"
+
+# Use an agent profile
+pnpm agent:cli --profile my-agent "hello"
+```
+
+## Agent Profiles
+
+Agent profiles define identity, personality, tools, and memory for an agent. Profiles are stored as markdown files in `~/.super-multica/agent-profiles/<id>/`.
+
+### Profile CLI
+
+```bash
+# Create a new profile with default templates
+pnpm agent:profile new my-agent
+
+# List all profiles
+pnpm agent:profile list
+
+# Show profile contents
+pnpm agent:profile show my-agent
+
+# Open profile directory in file manager
+pnpm agent:profile edit my-agent
+```
+
+### Profile Structure
+
+Each profile contains:
+
+- `identity.md` - Agent name and role
+- `soul.md` - Personality and behavioral constraints
+- `tools.md` - Tool usage instructions
+- `memory.md` - Persistent knowledge
+- `bootstrap.md` - Initial conversation context
+
+## Agent Tools
+
+### exec
+
+Execute short-lived shell commands and return output.
+
+```
+exec({ command: "ls -la", cwd: "/path/to/dir", timeoutMs: 30000 })
+```
+
+### process
+
+Manage long-running background processes (servers, watchers, daemons).
+
+```
+# Start a background process
+process({ action: "start", command: "npm run dev" })
+
+# Check process status
+process({ action: "status", id: "<process-id>" })
+
+# Read process output
+process({ action: "output", id: "<process-id>" })
+
+# Stop a process
+process({ action: "stop", id: "<process-id>" })
+
+# Clean up terminated processes
+process({ action: "cleanup" })
 ```
 
 ## Scripts
 
 - `pnpm dev` - Run in development mode
 - `pnpm agent:cli` - Run the agent CLI for module-level testing
+- `pnpm agent:profile` - Manage agent profiles
 - `pnpm build` - Build for production
 - `pnpm start` - Run production build
 - `pnpm typecheck` - Type check without emitting