# Agent Cody — Full Agent Guide

> Agent Cody is a content operations platform for Social Media Marketing Agencies. It manages brands, deliverables, scheduling, approvals, research, and AI-assisted script generation from templates and reels.

## Domain concepts

**Brand** — a tenant client. Every page under `/brands/[brandSlug]` is scoped to one brand. The active organization owns one or more brands.

**Deliverable** — one piece of content (a reel, post, story) that moves through statuses on the board: idea → script → review → ready → scheduled → published.

**Reel** — a piece of competitor / inspiration content captured into the research database. Reels are the source for the Steal-from-reel flow that adapts a transcript into 5 niche-fit scripts (saved as `stolen_scripts`).

**Template** — a proven script structure extracted from a Reel. Used as input to the quick-steal flow that fills 4 verbatim-copy options.

**Playbook** — a copywriting rule, framework, checklist, or reference. Modular: whole-post or scoped (hook / structure / formatting / etc.).

**PESTO framework** — Topic ▸ Pillar ▸ Angle ▸ Format. Every deliverable is tagged on these four dimensions.

**Steal flows** —
  - **Steal-from-reel**: open a reel → adapt its transcript into 5 niche-fit scripts → review/edit at `/scripts` → promote to a deliverable.
  - **Quick-steal (template)**: pick a template → generate 4 verbatim-copy options → promote one to a deliverable.

## Public

### Sign In — `/login`

Email + password or Google OAuth sign-in.

Auth: `public`.

Actions:

- **sign-in-email** — Sign in with email and password
- **sign-in-google** — Sign in with Google

### Agent Guide — `/agent-guide`

Public navigation map for AI agents — the same content as llms-full.txt rendered as HTML.

Auth: `public`.

## Core

### Home — `/`

Authenticated landing page: greeting, brand list with active project counts, quick action to create a new brand.

Auth: `session` (requires sign-in).

Actions:

- **open-brand** — Jump into a brand workspace
- **create-brand** — Open the create-brand dialog from home

### In-app Guide — `/guide`

Interactive help / onboarding documentation: PESTO framework, research, board, calendar, performance, inbox, roles, glossary.

Auth: `session` (requires sign-in).

## Brands

### Brands — `/brands`

List of all brands in the active organization with search, filter, and a create dialog.

Auth: `session` (requires sign-in).

Actions:

- **create-brand** — Open the create-brand dialog and submit a new brand
  - selector: `[data-testid="brand-create-button"]`
- **open-brand** — Navigate to a brand workspace by clicking a row
  - selector: `[data-testid="brand-row-{slug}"]`
- **search-brands** — Filter the list by typing into the search input
  - selector: `[data-testid="brand-search-input"]`

### Brand Overview — `/brands/[brandSlug]`

Brand dashboard with stats, upcoming content, recent deliverables, and quick links.

Auth: `session` (requires sign-in).

Actions:

- **edit-brand** — Open the brand-settings dialog
  - selector: `[data-testid="brand-edit-button"]`
- **open-board** — Jump to the deliverables board
  - selector: `[data-testid="brand-action-board-link"]`
- **open-calendar** — Jump to the scheduling calendar
  - selector: `[data-testid="brand-open-calendar-link"]`
- **open-approvals** — Jump to the approvals queue
  - selector: `[data-testid="brand-action-approvals-link"]`

## Brand Profile

### Brand Profile — `/brands/[brandSlug]/profile`

Editable brand profile across identity, audience/ICP, voice, pillars, visual identity, sponsored content, offer, tone, guardrails, brand story, differentiation, and per-platform voice.

Auth: `session` (requires sign-in).

Actions:

- **expand-section** — Expand or collapse a profile section
  - selector: `[data-testid="profile-section-{section}-toggle"]`
- **save-section** — Save edits to a section
  - selector: `[data-testid="profile-section-{section}-save-button"]`

### Brand Profile Wizard — `/brands/[brandSlug]/profile/wizard`

Step-by-step onboarding for a new brand: identity, audience/ICP, voice/tone, topics, brand story.

Auth: `session` (requires sign-in).

Actions:

- **wizard-next** — Advance to the next step
  - selector: `[data-testid="profile-wizard-next-button"]`
- **wizard-back** — Return to the previous step
  - selector: `[data-testid="profile-wizard-back-button"]`
- **wizard-finish** — Submit the wizard and persist the profile
  - selector: `[data-testid="profile-wizard-finish-button"]`

## Board & Deliverables

### Deliverables Board — `/brands/[brandSlug]/board`

Kanban view of every deliverable for a brand with platform/media/pillar/format/angle filters and create actions.

Auth: `session` (requires sign-in).

Actions:

- **create-deliverable** — Open the single-deliverable create dialog and submit
  - selector: `[data-testid="deliverable-create-button"]`
- **create-deliverables-batch** — Generate a batch of deliverables from a brief
  - selector: `[data-testid="deliverable-batch-create-button"]`
- **open-deliverable** — Navigate to a deliverable detail page by clicking a card
  - selector: `[data-testid="board-card-{deliverableId}"]`
- **change-card-status** — Drag a card between kanban columns to change its status
  - selector: `[data-testid="board-column-{status}"]`
- **apply-filters** — Open the filters popover and toggle pillar/angle/format/platform/media filters
  - selector: `[data-testid="board-filters-trigger"]`

### Deliverable Detail — `/brands/[brandSlug]/board/[deliverableId]`

Full view of a single deliverable: script, caption/hashtags, posting URLs, scheduled date, status stepper, performance, tasks, and activity timeline.

Auth: `session` (requires sign-in).

Actions:

- **edit-script** — Edit the script body inline
  - selector: `[data-testid="deliverable-script-input"]`
- **edit-caption** — Edit the caption + hashtags
  - selector: `[data-testid="deliverable-caption-input"]`
- **change-status** — Move the deliverable through its status stepper
  - selector: `[data-testid="deliverable-status-stepper"]`
- **set-schedule** — Pick a posting date and time
  - selector: `[data-testid="deliverable-schedule-input"]`
- **add-platform-url** — Add a published-post URL for IG/TikTok/YouTube
  - selector: `[data-testid="deliverable-platform-url-input"]`

## Calendar

### Calendar — `/brands/[brandSlug]/calendar`

Monthly calendar with drag-to-schedule from an unscheduled tray and a per-deliverable detail sheet.

Auth: `session` (requires sign-in).

Actions:

- **navigate-month** — Move forward or back one month
  - selector: `[data-testid="calendar-month-prev-button"]`
- **go-to-today** — Jump back to the current month
  - selector: `[data-testid="calendar-today-button"]`
- **drag-to-schedule** — Drag an unscheduled item from the tray onto a date cell
  - selector: `[data-testid="calendar-cell-{yyyy-mm-dd}"]`
- **open-deliverable-sheet** — Click a calendar event to open its detail sheet
  - selector: `[data-testid="calendar-event-{deliverableId}"]`

## Inbox

### Inbox — `/inbox`

Unified action list — research-profile decisions, deliverable approvals, and triage items.

Auth: `session` (requires sign-in).

Actions:

- **filter-tab** — Switch between action / resolved tabs
  - selector: `[data-testid="inbox-tab-{tab}"]`
- **open-item** — Open the preview panel for an inbox row
  - selector: `[data-testid="inbox-row-{itemId}"]`
- **approve-item** — Approve the selected item
  - selector: `[data-testid="inbox-approve-button"]`
- **reject-item** — Reject the selected item with a reason
  - selector: `[data-testid="inbox-reject-button"]`

## Research

### Brand Research — `/brands/[brandSlug]/research`

Redirects into the brand competitors view; entry point for research surfaces.

Auth: `session` (requires sign-in).

### Swipe File — `/brands/[brandSlug]/research/swipe`

Reference-content library per brand: drag-drop upload, URL ingest, tagging, and pillar/category assignment.

Auth: `session` (requires sign-in).

Actions:

- **add-swipe-item** — Open the add-swipe-item dialog (upload, paste URL, link Drive)
  - selector: `[data-testid="swipe-add-button"]`
- **apply-tags** — Apply pillar / category / tags to a swipe row
  - selector: `[data-testid="swipe-row-{itemId}-tag-button"]`

### Research Profile — `/brands/[brandSlug]/research/profiles/[username]`

Per-brand creator profile view fed by research database (used as input for script generation).

Auth: `session` (requires sign-in).

### Research Reel — `/brands/[brandSlug]/research/reels/[reelId]`

Reel detail from research — metadata, hooks, transcript, Adapt action.

Auth: `session` (requires sign-in).

Actions:

- **adapt-reel** — Adapt a reel into N brand-voice scripts via the adapt pipeline
- **view-transcript** — View the transcript
- **tag-reel** — Apply pillar / angle / format tags

### Brand Hooks — `/brands/[brandSlug]/research/hooks`

Per-brand hook templates (subset of the global hooks library).

Auth: `session` (requires sign-in).

## Competitors

### Competitors — `/brands/[brandSlug]/competitors`

Per-brand list of competitors / creator profiles with sort + filter by platform/niche/followers; add or import.

Auth: `session` (requires sign-in).

Actions:

- **search-creators** — Filter creators by name
- **sort-followers** — Sort by follower count
- **add-profile** — Add a new creator profile
- **import-video** — Import a reel from a URL
- **open-creator** — Open a creator detail page

### Competitor Detail — `/brands/[brandSlug]/competitors/[username]`

Detail view of a single competitor / creator — metadata, follower counts, related content.

Auth: `session` (requires sign-in).

### Creator Intel — `/brands/[brandSlug]/competitors/[username]/intel`

Deep dive into a creator — niche, top hooks, performance patterns, AI-extracted insights.

Auth: `session` (requires sign-in).

## Playbooks

### Playbooks — `/playbooks`

Reusable copywriting playbooks (frameworks / checklists / references / transcripts) — org-wide and per-brand.

Auth: `session` (requires sign-in).

Actions:

- **create-playbook** — Open the new-playbook page
  - selector: `[data-testid="playbook-create-link"]`
- **edit-playbook** — Edit an existing playbook
  - selector: `[data-testid="playbook-row-{id}-edit-button"]`
- **delete-playbook** — Delete a playbook (with confirm)
  - selector: `[data-testid="playbook-row-{id}-delete-button"]`

### New Playbook — `/playbooks/new`

Form to create a playbook (name, type, scope, body).

Auth: `session` (requires sign-in).

Actions:

- **submit-playbook** — Submit the new playbook form
  - selector: `[data-testid="playbook-submit-button"]`

## Hooks

### Hooks — `/hooks`

Hook-template library used to seed new scripts — CRUD + duplicate + categorize.

Auth: `session` (requires sign-in).

Actions:

- **create-hook** — Create a new hook template
  - selector: `[data-testid="hook-create-button"]`
- **edit-hook** — Edit a hook template
  - selector: `[data-testid="hook-row-{id}-edit-button"]`
- **duplicate-hook** — Duplicate a hook template
  - selector: `[data-testid="hook-row-{id}-duplicate-button"]`
- **delete-hook** — Delete a hook template
  - selector: `[data-testid="hook-row-{id}-delete-button"]`

## Library (global)

### Content Library — `/content`

Global reel database across the org — search, filter (pillar / platform / angle), tag, manage taxonomy.

Auth: `session` (requires sign-in).

Actions:

- **search-reels** — Search reels by title / hook / transcript
- **add-reel** — Add a reel by URL
- **apply-tags** — Tag with pillar / angle / format

### Reel Detail — `/content/[reelId]`

Full reel view: metrics, hooks, tags, creator info; copy hashtags, bookmark, view/create hooks, Adapt.

Auth: `session` (requires sign-in).

Actions:

- **view-metrics** — View reel performance metrics
- **copy-hashtags** — Copy hashtags to clipboard
- **create-hook** — Create a hook template from this reel
- **adapt-reel** — Adapt this reel into brand-voice scripts
- **tag-reel** — Tag with pillar / angle / format
- **open-external** — Open the reel on its source platform

### Global Taxonomy — `/content/taxonomy`

Org-wide pillar + angle taxonomy: add / edit / delete pillars and angles; manage angle options.

Auth: `session` (requires sign-in).

Actions:

- **add-pillar** — Add a new pillar
- **add-angle** — Add an angle to a pillar
- **edit-pillar-or-angle** — Edit a pillar or angle
- **inspect-taxonomy** — Read the org-wide pillar + angle taxonomy

### Brand Taxonomy — `/brands/[brandSlug]/content`

Per-brand pillar + angle overrides on top of the global taxonomy.

Auth: `session` (requires sign-in).

### Templates — `/templates`

Redirects to /content. Kept for backward-compatible deep links.

Auth: `session` (requires sign-in).

### Creators — `/creators`

Global creator browser across the org — search, filter, sort, bulk-assign creators to brands.

Auth: `session` (requires sign-in).

Actions:

- **search-creators** — Search creators across the org
- **add-profile** — Add a creator profile
- **bulk-assign** — Assign selected creators to a brand

### Creator Profile — `/creators/[username]`

Global creator profile view (org-wide, not brand-scoped).

Auth: `session` (requires sign-in).

## Analytics & Reports

### Analytics — `/analytics`

Placeholder that prompts you to switch the active brand; per-brand performance lives under /brands/[slug]/performance.

Auth: `session` (requires sign-in).

### Brand Performance — `/brands/[brandSlug]/performance`

Per-brand performance dashboard: engagement rates, top performers, content breakdowns, AI-generated insights for published content.

Auth: `session` (requires sign-in).

Actions:

- **view-engagement** — See engagement-rate breakdowns
- **drill-into-post** — Click a published post to view its detail
- **generate-insights** — Run insight generation across recent posts

### Reports — `/brands/[brandSlug]/reports`

Historical performance reports per brand by date range; summary metrics + export.

Auth: `session` (requires sign-in).

Actions:

- **pick-date-range** — Select a date range to summarize
- **export-report** — Export the report

## Settings

### Brand Settings — `/brands/[brandSlug]/settings`

Edit brand basic info, social handles + follower counts, posting goals, social integrations; archive or permanently delete the brand.

Auth: `session` (requires sign-in).

Actions:

- **save-brand** — Persist brand info changes
- **archive-brand** — Archive the brand
- **delete-brand** — Permanently delete the brand (with name-confirmation)
- **connect-social** — Connect or disconnect IG / TikTok / YouTube / Drive

### API keys — `/settings/api-keys`

Self-serve provisioning of bearer tokens for the MCP server, the Chrome extension, and any server-to-server caller. The raw key is shown once on creation and stored only as a SHA-256 hash.

Auth: `session` (requires sign-in).

Actions:

- **create-api-key** — Mint a new API key (name + optional expiry); raw key shown once
  - selector: `[data-testid="api-key-create-button"]`
- **copy-claude-code-command** — Copy a pre-filled `claude mcp add` snippet from the reveal dialog
- **revoke-api-key** — Revoke a key (soft-delete, immediate)
  - selector: `[data-testid="api-key-revoke-trigger"]`

## Public Share Links

### Public Report — `/report/[token]`

Token-gated public performance report (optionally password-protected).

Auth: `token` (requires sign-in).

Actions:

- **verify-password** — Submit the report password if required
- **download-report** — Download the report

### Shared Insights — `/share/insights/[token]`

Token-gated insights / performance narrative — read-only embeddable view.

Auth: `token` (requires sign-in).

Actions:

- **view-insights** — Read the insights breakdown
- **print** — Print or export the insights view

## Selectors and testids

Where actions list a `selector`, the element carries a stable `data-testid`. Use it as a fallback when an accessible name is ambiguous. Selectors with `{placeholder}` segments are templated — substitute the dynamic id (e.g. brand slug, deliverable id, ISO date) when constructing the live selector.

Per-page testid sweeps roll out in priority order; not every action listed above has a testid attached yet. When in doubt, prefer the visible text or accessible name.