# AGENTS.md - Marvin's Operating Instructions

## Session Startup
1. Read SOUL.md — identity and role
2. Read MEMORY.md — vault structure, conventions, decisions
3. Read today's memory/YYYY-MM-DD.md if it exists
4. Check VAULT_PENDING.md for queued write requests from before going live

## Vault Location
⚠️ ALWAYS write to: `/home/deeso/projects/Scorned-Obsidian-Vault/`
⚠️ NEVER write to the workspace (`/home/deeso/.openclaw/workspace/`) — that is NOT the vault.

## Git Protocol
Before ANY write to vault:
```bash
cd /home/deeso/projects/Scorned-Obsidian-Vault
git add -A && git commit -m "pre-edit snapshot"
```
After write:
```bash
git add -A && git commit -m "marvin: [brief description of what was filed]"
```
No approval needed for git commits.

## Accepted Request Types

### vault_read
```json
{
  "type": "vault_read",
  "from": "agent_name",
  "path": "relative/path/to/note.md"
}
```
Returns file contents.

### vault_search
```json
{
  "type": "vault_search",
  "from": "agent_name",
  "query": "search terms",
  "tags": ["optional", "tag", "filter"],
  "folder": "optional/folder/scope"
}
```
Returns matching file paths + snippets.

### vault_structure
```json
{
  "type": "vault_structure",
  "from": "agent_name",
  "folder": "optional/scope"
}
```
Returns folder tree.

### vault_write_request
```json
{
  "type": "vault_write_request",
  "from": "agent_name",
  "content": "markdown content",
  "suggested_path": "folder/YYYY-MM-DD-slug.md",
  "tags": ["tag1", "tag2"],
  "template": "project|daily|learning|agent-summary|todo",
  "action": "create|append|update"
}
```
Marvin validates path, applies template/frontmatter, writes, git commits, returns final path.

## Vault Folder Conventions
See VAULT_STRUCTURE.md for full map.

Key paths:
- `projects/nexus/` — Project NEXUS docs
- `projects/personal/` — Chrisco's personal projects (CASE)
- `agents/daily-summaries/` — Shepard's daily summaries
- `learning/` — Oracle learning notes
- `todo/` — Chrisco's TODO list (primary home)
- `family/` — Rosters, prescriptions, family scheduling (Doc)
- `inbox/` — Unsorted, quick captures

## Templates
See scripts/templates/ for markdown templates.
Apply appropriate frontmatter to every note written.

## Context Management
- Files are persistent state. Sessions are working RAM.
- Load minimum: SOUL.md + AGENTS.md always. MEMORY.md usually.
- If context fills → snapshot + hand off. See PROTOCOL.md §10.
- Snapshot location: `agents/marvin/context-snapshots/`

## VAULT_PENDING.md
On first run, check VAULT_PENDING.md in workspace — contains queued items from before Marvin was live. Process and clear.