# Team Directory

This file is shared across all agents. Read it to understand who's on the team and how to collaborate.

## Agents

| Agent | Owner | Telegram Bot | Role | Notes |
|-------|-------|-------------|------|-------|
| Russ Assistant | Russ | @RussHuck_bot | TBD | — |
| Tracy Assistant | Tracy | @Leigh_Tracy_bot | TBD | — |
| Tom Assistant | Tom | @Resortment_bot | TBD | — |
| Denise Assistant | Denise | @Cybercosta_bot | TBD | — |
| Zac Assistant | Zac | @zac_resortments_bot | TBD | — |

## How We Collaborate

- **Shared directory:** `./company/` — all agents read and write here
- **Private directories:** `./personal/` — only your own agent can access yours
- **Task database:** Supabase — all agents can read and write tasks
- **Automation:** n8n monitors the database and delivers tasks to agents via Telegram
- **We cannot message each other directly.** Communication happens through the shared directory and the task database.

## Task System (Supabase)

All agents have access to the central task database via HTTP REST API.

### Supabase Connection
- **URL:** `https://ylayymyzmvfdydrtniyo.supabase.co`
- **API Key:** Use the key from your environment/instructions to authenticate
- **Header:** `apikey: <your_key>` on every request

### Tables

**`tasks`** — The task queue
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Auto-generated |
| name | TEXT | Task title |
| description | TEXT | What needs to be done |
| file_link | TEXT | Link to file, doc, or resource |
| notes | TEXT | Additional context |
| status | TEXT | Current status (see flow below) |
| priority | TEXT | normal, high, urgent |
| created_by | TEXT | Agent ID who created it |
| assigned_to | TEXT | Agent ID who should do it |
| created_at | TIMESTAMP | When created |
| updated_at | TIMESTAMP | Last modified |

**`task_log`** — Activity log for everything that happens on tasks
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Auto-generated |
| task_id | UUID | Which task |
| agent_id | TEXT | Which agent took action |
| action | TEXT | What happened (created, started, completed, etc.) |
| details | TEXT | Additional context |
| created_at | TIMESTAMP | When |

**`agents`** — Team directory (read-only reference)

### Task Status Flow
```
pending → ready_for_<agent> → sent_to_<agent> → in_progress → done
```

- `pending` — Created but not assigned
- `ready_for_tracy` — Assigned to Tracy, waiting for n8n to notify her
- `sent_to_tracy` — n8n has sent the notification to Tracy's Telegram
- `in_progress` — Tracy is working on it
- `done` — Completed

### How to Create a Task for Another Agent

To assign work to another agent, POST to the tasks table:

```
POST https://ylayymyzmvfdydrtniyo.supabase.co/rest/v1/tasks
Headers:
  apikey: <key>
  Content-Type: application/json

Body:
{
  "name": "Review the Q1 report",
  "description": "Check figures in section 3 and update charts",
  "status": "ready_for_tracy",
  "created_by": "russ",
  "assigned_to": "tracy",
  "priority": "high"
}
```

n8n will automatically pick this up and notify Tracy via Telegram.

### How to Check Your Tasks

```
GET https://ylayymyzmvfdydrtniyo.supabase.co/rest/v1/tasks?assigned_to=eq.<your_agent_id>&status=neq.done&select=*
Headers:
  apikey: <key>
```

### How to Update Task Status

```
PATCH https://ylayymyzmvfdydrtniyo.supabase.co/rest/v1/tasks?id=eq.<task_id>
Headers:
  apikey: <key>
  Content-Type: application/json

Body:
{
  "status": "in_progress"
}
```

### How to Log Activity

```
POST https://ylayymyzmvfdydrtniyo.supabase.co/rest/v1/task_log
Headers:
  apikey: <key>
  Content-Type: application/json

Body:
{
  "task_id": "<task_uuid>",
  "agent_id": "<your_agent_id>",
  "action": "started",
  "details": "Beginning work on the report review"
}
```

## Shared Directory Rules

1. **Sign your work.** When writing to `./company/`, always add a footer: `— Added by [Your Name] Assistant, YYYY-MM-DD`
2. **Don't overwrite others' files** without your owner's explicit instruction.
3. **Check existing files first** before creating new ones to avoid duplicates.
4. **Use clear filenames** that describe the content.
5. **Organize into subfolders:** `sops/`, `clients/`, `brand/`, `processes/`, `templates/`

## File Sharing

All agents can share files (PDFs, docs, images, etc.) with each other and their users via the file server.

### File Server URL
`https://files.187.124.227.42.nip.io`

### How to Share a File
1. Save the file to `./company/files/` (e.g. `./company/files/q1-report.pdf`)
2. The download link is: `https://files.187.124.227.42.nip.io/files/q1-report.pdf`
3. Include the link in a task or message

### CRITICAL: Verify Before Sharing
- **ALWAYS** verify the file exists at `./company/files/<filename>` BEFORE sharing a link
- **NEVER** generate a file server URL for a file you haven't confirmed exists on disk
- **NEVER** share links to files in `./personal/` — those are NOT served by the file server
- If you need to share a personal file, COPY it to `./company/files/` first
- Files saved to `./output/` or workspace root are NOT accessible via the file server

### Sharing a File with Another Agent
Create a task with the `file_link` field:
```
POST https://ylayymyzmvfdydrtniyo.supabase.co/rest/v1/tasks
{
  "name": "Review Q1 report",
  "description": "Please review the attached report",
  "file_link": "https://files.187.124.227.42.nip.io/files/q1-report.pdf",
  "status": "ready_for_tracy",
  "created_by": "russ",
  "assigned_to": "tracy"
}
```

The target agent and their user can click the link to download.

### File Organization
```
company/files/
├── reports/       ← Reports and analysis
├── presentations/ ← Slide decks
├── contracts/     ← Legal documents
└── misc/          ← Everything else
```

## Inter-Agent Communication Patterns

**For tasks:** Use the Supabase task system. Create a task with `status: "ready_for_<agent>"` and n8n will deliver it.

**For files:** Save to `./company/files/`, include the download link in the task's `file_link` field.

**For documents:** Write a file to `./company/` with a clear name (e.g. `for-tracy-q1-budget-notes.md`).

**For urgent items:** Set `priority: "urgent"` on the task.

## Google Workspace (Drive, Docs, Sheets, Calendar)

All agents can access Google Workspace via the service account. The service account email is `brain-resortments@resortments-491119.iam.gserviceaccount.com` — any Drive files/folders shared with this email are accessible to all agents.

### Getting an Access Token

Before making any Google API call, get a fresh token:

```
GET https://google.187.124.227.42.nip.io/token
```

Response: `{"access_token": "ya29.c...."}`

Use this token in all subsequent Google API calls as: `Authorization: Bearer <access_token>`

Tokens last ~1 hour and are cached automatically.

### Create a Google Doc

```
POST https://docs.googleapis.com/v1/documents
Headers:
  Authorization: Bearer <access_token>
  Content-Type: application/json

Body:
{
  "title": "My Document"
}
```

### Write to a Google Doc

```
POST https://docs.googleapis.com/v1/documents/<documentId>:batchUpdate
Headers:
  Authorization: Bearer <access_token>
  Content-Type: application/json

Body:
{
  "requests": [
    {"insertText": {"location": {"index": 1}, "text": "Hello world"}}
  ]
}
```

### Create a Google Sheet

```
POST https://sheets.googleapis.com/v4/spreadsheets
Headers:
  Authorization: Bearer <access_token>
  Content-Type: application/json

Body:
{
  "properties": {"title": "My Sheet"}
}
```

### Read/Write Sheet Data

```
GET https://sheets.googleapis.com/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1:Z100
Headers: Authorization: Bearer <access_token>

PUT https://sheets.googleapis.com/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1?valueInputOption=RAW
Headers: Authorization: Bearer <access_token>, Content-Type: application/json
Body: {"values": [["Name", "Email"], ["Russ", "russ@example.com"]]}
```

### List Drive Files

```
GET https://www.googleapis.com/drive/v3/files?q='<folderId>'+in+parents
Headers: Authorization: Bearer <access_token>
```

### Create Calendar Event

```
POST https://www.googleapis.com/calendar/v3/calendars/primary/events
Headers: Authorization: Bearer <access_token>, Content-Type: application/json
Body:
{
  "summary": "Team Meeting",
  "start": {"dateTime": "2026-03-26T10:00:00-06:00"},
  "end": {"dateTime": "2026-03-26T11:00:00-06:00"}
}
```

**Note:** The service account has its own calendar. To use a team member's calendar, they must share it with `brain-resortments@resortments-491119.iam.gserviceaccount.com`.

## Higgsfield AI (Video Generation)

All agents can generate videos using the Higgsfield API.

### Authentication
- **Base URL:** `https://platform.higgsfield.ai`
- **Auth Header:** `Authorization: Key 5e34ede1-acfa-4224-b75a-3ade2e576b2c:57e6b4dc3bdefdae67709544eaa5de4dd73eff13bdbb5d9d7f8e8844601630cd`

### Easy Method: Use the Higgsfield Proxy (RECOMMENDED)

Instead of calling the Higgsfield API directly, use the n8n proxy webhook. This handles authentication automatically and works with `web_fetch`:

**Endpoint:** `https://n8n.187.124.227.42.nip.io/webhook/higgsfield-generate` (POST, JSON body)

#### Generate video from text:
```json
{
  "action": "generate_from_text",
  "prompt": "A modern modular home being assembled by robots",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

#### Generate video from image:
```json
{
  "action": "generate_from_image",
  "image_url": "https://files.187.124.227.42.nip.io/files/your-image.jpg",
  "prompt": "Smooth camera push-in with gentle motion",
  "duration": 5
}
```

#### Check video status:
```json
{"action": "status", "request_id": "your-request-id-here"}
```

#### Cancel a request:
```json
{"action": "cancel", "request_id": "your-request-id-here"}
```

Response includes `request_id` and `status_url` for tracking. When status is `completed`, the response includes `video.url` with the download link.

### Direct API Method (Advanced)

### Generate Video from Image

```
POST https://platform.higgsfield.ai/higgsfield-ai/dop/standard
Headers:
  Authorization: Key 5e34ede1-acfa-4224-b75a-3ade2e576b2c:57e6b4dc3bdefdae67709544eaa5de4dd73eff13bdbb5d9d7f8e8844601630cd
  Content-Type: application/json

Body:
{
  "image_url": "https://example.com/your-image.jpg",
  "prompt": "Description of the motion/animation you want",
  "duration": 5
}
```

Response includes a `request_id` for tracking.

### Generate Video from Text

```
POST https://platform.higgsfield.ai/higgsfield-ai/soul/standard
Headers:
  Authorization: Key 5e34ede1-acfa-4224-b75a-3ade2e576b2c:57e6b4dc3bdefdae67709544eaa5de4dd73eff13bdbb5d9d7f8e8844601630cd
  Content-Type: application/json

Body:
{
  "prompt": "Description of the video you want",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

### Check Status

```
GET https://platform.higgsfield.ai/requests/<request_id>/status
Headers:
  Authorization: Key 5e34ede1-acfa-4224-b75a-3ade2e576b2c:57e6b4dc3bdefdae67709544eaa5de4dd73eff13bdbb5d9d7f8e8844601630cd
```

Statuses: `queued` → `in_progress` → `completed` (or `failed` / `nsfw`)

When completed, response includes `video.url` with the download link.

### IMPORTANT: Video Generation Best Practices
- **DO NOT poll in a tight loop.** Check status at most 3 times with 30-second waits between checks.
- If the video is still `queued` or `in_progress` after 3 checks (~90 seconds), STOP polling and tell the user: "Your video is being generated. Check back in a few minutes or ask me to check the status."
- **Save the `request_id`** to `./company/files/pending_videos.md` so any agent can check later.
- **When video completes:** Download it to `./company/files/` and share the file server link — do NOT share the temporary Higgsfield URL.
- **Context warning:** Repeated API polling will bloat your session. If you've polled 3+ times, use `/new` to start fresh before continuing other work.

### Available Models
- `higgsfield-ai/dop/standard` — Image to video (Higgsfield native)
- `higgsfield-ai/soul/standard` — Text to video
- `kling-video/v2.1/pro/image-to-video` — Kling video model
- `bytedance/seedance/v1/pro/image-to-video` — ByteDance Seedance
- More at https://cloud.higgsfield.ai/explore

## Company Knowledge Base Structure

```
company/
├── TEAM.md          ← This file
├── sops/            ← Standard Operating Procedures
├── clients/         ← Client records and notes
├── brand/           ← Brand guidelines, voice, visual identity
├── processes/       ← Internal workflows
└── templates/       ← Document templates
```