User Guide

Complete guide to day-to-day operation of PowerMarketing. For first-time setup, see the Quick Start. For core concepts, see Concepts.

0. Onboarding

There is no public signup. Workspaces are provisioned by a superadmin from inside the app, in two steps:

• Create the brand — brand selector → + Add brand (superadmin only). Creates the brand record and its ingest keys.
• Create the user — Users page → + Add User. Set username, password, role, and which brands the account may access.

Roles. superadmin manages the whole platform and is the only role that can create or delete a brand. admin and operator work within the brands they are granted.

1. Signing In

Go to /login.html and enter the username and password your administrator provided. Sessions last 8 hours. On 401 errors you are redirected to the login page automatically.

Change your password after first login: Settings → Users → Change My Password (or the Users page for superadmins).

1a. Navigating the App

The left sidebar is organised into collapsible groups by area of work, so the menu stays short. At the top is the Active Brand selector (switch brands here) and the pinned Command Center. Below are the workspace groups; the group containing your current page opens automatically, and the app remembers which groups you expand.

At the bottom of the sidebar, the 🌙 Dark mode / ☀️ Light mode button switches the colour theme. Your choice is remembered on this browser, including across sign-outs.

2. The Command Center (Daily Operations)

The Command Center (/index.html) is designed to be your only stop for the morning review. It opens on a hero area showing the brand name and current autopilot mode, followed by live stat tiles, the audience funnel, the Approvals queue, and today's pipeline.

Setup checklist

A checklist at the top of the Command Center shows every readiness check with its state — ✓ done, ⚠ warning, ✗ blocking — plus a progress count such as "5 of 8 complete". Each unfinished item carries a Fix → link straight to the right settings tab. "Run Agents Now" stays disabled until all blocking checks pass.

The checklist does not disappear once you finish: it collapses to a single Setup complete line, and Show / Hide lets you reopen it at any time. Your choice is remembered per brand.

Overnight summary bar

A green bar shows how many posts were auto-published since your last visit (Track 1). Click "View all →" to see them in Posts.

Live Stat Tiles & Audience Funnel

A row of stat tiles below the hero refreshes on page load and shows key numbers at a glance (contacts, open sequences, newsletters pending, posts approved, etc.). Below the tiles, the Audience Funnel visualises how contacts progress through the four lifecycle stages — Subscriber → Engaged → Hot → Converted — with a count and percentage for each band.

Autopilot Level

Moved. The autopilot control now lives in Settings → Automation, directly above the Publication Rules it governs — the two used to sit on different pages with neither referencing the other. The Command Center still shows the current level, with a Change in Settings → link, but is no longer where you change it.

Three positions are available:

Unified Approvals Queue

The Approvals section consolidates every item awaiting a human decision — social posts (Track 2), nurture messages, and newsletters — into a single list so you do not need to navigate between pages. Each card shows a content preview and the item type. Actions available inline:

• Approve — marks the item ready; it is dispatched on the next scheduler run or immediately if you click Run Agents Now.
• Reject — opens a short modal asking for a reason code (Off-brand / Factual issue / Wrong timing / Other). The reason is stored and surfaced in the Insights rejection-reason summary. The item returns to ai_draft status.

AI Command Box

A free-text input at the top of the Command Center accepts natural-language instructions for the AI agent — for example, "Draft three LinkedIn posts about our Q3 launch" or "Summarise last week's engagement." The agent executes the command and returns results in-line; longer tasks also appear in the Agent Log.

Today's Pipeline

One row per calendar entry for today. Each row shows a stepper: Draft → AI Draft → Approved → Published. When a post reaches ai_draft status an Approve button appears inline. When approved, a Publish → link appears.

Dispatch Panel

Shows today's pending entry count. Click Run Agents Now to trigger dispatch immediately outside the scheduled window. Result shows auto-published vs awaiting review counts.

Quick Actions

Six cards: Create Post · Plan this week ✦ · Repurpose · Add Lead · Newsletter · Agent Log.

2a. The Workflow Page

The Workflow page (🔁 in the sidebar) shows your automation pipeline as six connected stages — Plan → Calendar → Create → Review → Publish → Learn — refreshed every 30 seconds. Each node carries a status dot: green = healthy, blue = working, amber (pulsing) = needs your attention, grey = idle. Click a node to open a detail panel with its live numbers and a shortcut to the relevant page.

• Plan — the AI proposes a whole-funnel weekly plan every Monday 05:00 UTC. Unless autopilot is set to Manual, the plan is auto-approved and its items are inserted into the calendar; in Manual mode it waits in Decisions.
• Calendar / Create / Review / Publish — entries due today, drafts and failures this week, pending approvals, and what was published (and how much of it automatically).
• Learn — feedback signals collected from your approve/reject decisions, fed back to the AI.

3. Brand Setup

Quick-Start (new brands)

The Quick-Start card auto-appears in Settings → Brand Profile when the profile is empty. Fill three fields and click ✦ Generate All Settings. One LLM call fills brand voice, content pillars, messaging framework, and target segments simultaneously. Review and save.

Brand Profile Fields

Each field has a ✦ AI Assist button that opens a guided question flow and generates the field content using AI. Review, optionally regenerate with feedback, then apply.

AI Provider

Select the LLM provider (Claude / DeepSeek / Moonshot) and the default model. Click Test Connection to verify the API key works. The model list is populated from the global LLM Models registry in Settings → LLM Models.

4. API Keys (Settings → API Keys)

All API keys are stored per-brand in the database — not in environment variables.

Keys are masked on display. Enter a new value and save to update. Leave blank to keep the existing key.

4a. Settings → Ingestion

The Ingestion settings page is where you connect your product site (or any external source) to PowerMarketing's contact capture pipeline. It surfaces the brand's ingest credentials and lets you run connectors.

Finding your Ingest Public Key

Under Settings → Ingestion, the brand's ingest_public_key is displayed and can be copied to the clipboard with one click. This key is safe to embed in front-end code; it identifies the brand but does not grant write access to your account.

Embed Snippet

Click Copy Snippet to copy a ready-made embed for your product site. Paste it where you want the subscribe form to appear. The snippet renders a small email opt-in form that posts to the ingest endpoint and triggers double opt-in — no other tracking is added.

<!-- PowerMarketing capture widget -->
<script src="https://marketing.planningpowertools.com/embed/powermarketing-embed.js"
        data-brand-key="YOUR_INGEST_PUBLIC_KEY"
        data-api="https://marketing-api.planningpowertools.com"
        data-source="your-product"></script>

Rotating Keys

Click Rotate Keys to immediately replace the current ingest_public_key and webhook secret with a fresh pair. The previous key stops working as soon as you rotate, so update your embed snippet and any connector configurations with the new key right away.

Capture Paths

PowerMarketing supports three ways to get contacts and events into the pipeline. All three use double opt-in: a confirmation email is sent to the address before the contact moves from pending to subscriber status.

Confirmation & unsubscribe pages

The confirmation email's Confirm link and the public Unsubscribe link both open a branded, on-brand HTML page — not a raw JSON response. Each page is themed to the brand, shows a clear success (or expired/invalid) message, and offers a Visit our website button (when the brand has a website_url set) plus a Close window button. The same friendly pages are reused by any Resend-driven flow, so subscribers never see a technical screen.

What happens when someone subscribes again

Re-submitting an address that already exists does not blindly resend a confirmation. The ingest endpoint inspects the contact's current consent status and responds accordingly:

5. Owners (Settings → Owners)

Owners are people whose voice the AI should replicate when generating content. Add owners with a name, role, and voice description. Optionally add links (LinkedIn, email, website).

Calendar entries can be assigned to an owner. When assigned, the AI uses the owner's voice description to personalise the post.

6. Content Calendar

Calendar View

Monthly grid view. Days with entries show colour-coded pills (by platform). Click a day to add an entry for that date. Existing pills open the entry editor.

Adding Entries Manually

Click + Add Entry or any calendar day. Fill: Topic, Content Type, Platform(s) (checkboxes), Date, Notes. The Require approval checkbox forces Track 2 for this entry regardless of the brand's auto-publish settings.

Plan this week ✦

1. Click ✦ Plan this week (top right of Calendar page)
2. Pick week start date and number of entries (3 / 5 / 7)
3. Click Generate ✦ — AI reads content pillars and creates diverse entries
4. Edit topics inline in the preview table
5. Click Add All to Calendar to confirm

Content Type Routing

7. Automation Settings (Settings → Automation)

Dispatch Time

Set the UTC time for daily auto-dispatch. The scheduler polls every 15 minutes and fires this brand when its window matches. Each brand has an independent dispatch time. A mode selector lets you switch between Fixed time and Auto — learned from engagement: in auto mode, once the brand has enough published posts with metrics (≥10), the system dispatches at the hour that historically earned the most engagement. The learned time is shown as a hint next to the field.

Evergreen Recycling

When enabled, every Wednesday 05:30 UTC the recycler re-queues your top-performing published posts (by engagement score) once they are older than the cool-down period (default 21 days). The winning content is reused verbatim — not regenerated. Recycled posts follow the same approval rules as new ones: at auto-guardrails they publish automatically, otherwise they land in the Decisions inbox. A post is never recycled twice within one cool-down window.

Publication Rules Matrix

A table listing every content type with a checkbox. Checked = Track 1 (auto-publish). Unchecked = Track 2 (approval inbox). Video and email rows are locked to Track 2.

Web Search

Toggle to allow agents to fetch live trend data via Tavily. Requires a Tavily API key in Settings → API Keys.

Weekly Planning, Top-up & Retries (automatic)

Background behaviours that need no configuration: every Monday 05:00 UTC the planner fills the upcoming week's calendar for each brand (skipped if the week already has pending entries or a plan is awaiting approval); a daily top-up at 05:15 UTC re-plans any non-manual brand whose calendar has nothing scheduled for the next 3 days, so the queue never runs dry; an hourly retry pass (at :45) re-generates any post whose content generation failed earlier in the day; a daily metrics refresh at 04:00 UTC pulls engagement numbers for recently published posts and feeds them back into planning; and every Monday 05:45 UTC the autonomy check reviews your approval history (see Decisions).

Earned Autonomy (progressive auto-publish)

The system tracks whether you approve AI posts without editing them. When a content type reaches 20+ reviews with ≥95% approved unedited in the last 90 days, a 🎓 Autonomy Upgrade proposal appears in your Decisions inbox. Approving it lets that content type publish automatically from then on — video/email and per-entry "require approval" flags still always gate. This is how the product moves from "you approve everything" to "you only approve exceptions".

8. Creating Content Manually (Create page)

The Create page needs exactly one input: describe what the post should be about, pick the platform, and click Generate. Brand voice, pillars, and target audience are applied automatically from your brand profile; the post title is derived from the topic.

1. Type the topic (one sentence is enough) and select platform + content type
2. Click Generate Content → preview result in the textarea
3. Edit directly, or click Regenerate
4. Then act on it without leaving the page — Save changes, 📅 Schedule…, or 🚀 Publish now. View in Posts → is still there if you would rather work from the queue.

Schedule asks for a UTC date/time and sets the post to scheduled. Publish now runs the AI pre-flight check first and shows any warnings before going ahead; pre-flight is advisory and never blocks you.

Content type sets the writing angle. Picking News or Trend scan automatically uses live web research; everything else writes from your brand perspective. There is no separate "generation mode" to choose — the old two-dropdown model was the single most common source of confusion. Advanced options still expose an optional Angle override for the Competitor Signal case.

Advanced options (collapsed by default) hold everything else: custom title, angle override, objective, target audience, tone, CTA, key points, source material, things to avoid, and the Trend Research panel context. AI provider/model selection is only visible to superadmins.

9. Decisions & Approval

The Decisions page lists all pending Track 2 posts with content previews.

• Approve — marks post as approved, ready to publish
• Reject — opens a prompt asking for a reason code (Off-brand / Factual issue / Wrong timing / Other); post stays as ai_draft. Reason codes are aggregated in Insights → Rejection Summary.
• AI Guidance — get an AI recommendation on whether to approve
• Batch actions — tick the checkbox on any pending items (or Select all pending) and use ✓ Approve selected / ✗ Reject selected to resolve many at once

Daily approval digest: every day at 06:30 UTC, brands with pending decisions email a summary to every user with access to the brand (requires a Resend API key). Each item has a one-click Approve link — you can clear routine approvals from your inbox without opening the app.

Beyond post reviews, the inbox also carries 🎓 Autonomy Upgrade proposals (grant a content type auto-publish — see Automation) and ✨ Segment Proposals (AI-suggested audience segments — approving one saves it on the People page).

You can also approve or reject from the Command Center Approvals queue without navigating to this page. Email content type is always Track 2 and cannot be set to auto-publish.

10. Publishing (Publish page)

Select an approved post, choose the platform credential, and click Publish Now. Publishing requires an active credential configured in Settings → Credentials. Track 1 posts are published automatically by the dispatcher — you only visit this page for Track 2 posts.

11. Repurposing Content (Repurpose page)

Pick an existing published post and a target platform. Optionally specify emphasis, tone shift, audience notes, elements to keep, and elements to cut. The AI adapts the content for the new platform's format and audience expectations.

12. Posts

The Posts page lists all posts with filters by status, platform, and content type. You can edit content inline, change status, and view publish history. Status flow: draft → ai_draft → approved → published.

13. Videos

Generate AI video scripts and storyboards from a topic. Requires a video provider configured in Settings → Video (HeyGen, Runway, or a generic REST provider). The VideoCreator agent writes the script, storyboard, voiceover text, and caption.

14. Leads

Track prospects with warmth score and stage. Click Nurture on any lead to have the AI draft a personalised outreach message based on the lead's role, company, and the brand's voice. The draft appears in Lead Communications for review before sending.

15. People & Email

People page (/people.html) is the single audience view — everyone your brand talks to, whether they arrived as a newsletter subscriber, a lead, or an ingested contact. Adding a subscriber or a lead (with an email) anywhere in the app automatically creates or updates the matching person here, deduplicated by email.

• Filters — stage (subscriber/lead/customer), free-text search, and tag. Stats tiles show totals by stage and confirmed-consent count.
• ⬆ Import CSV — bulk-import a list with header email,name,company,role,tags. Rows are upserted by normalized email (re-imports update instead of duplicating); invalid emails are skipped and counted.
• Segments — set filters and click 💾 Save as segment to make them reusable; pick a saved segment from the dropdown to re-apply it. ✨ Suggest segments asks the AI to analyse your audience and propose up to 3 segments, delivered as approvals in the Decisions inbox.
• Manage → on any row opens the Contacts management view for individual-record work (event timeline, sequence enrolment).

Emails page: compose broadcast campaigns. Select audience segment, write subject and body, preview, and send via Resend. Requires Resend API key in Settings → API Keys.

16. Users (Superadmin only)

The Users page (/users.html) is only visible to superadmins.

Click + Add User to create a user, assign brands, and set a role. Edit to change role or reset password. Deactivate prevents login without deleting the account.

Any user can change their own password via the Change My Password form on the Users page.

17. Agent Log

The Log page (/log.html) shows all AI agent runs: agent name, trigger (scheduled or manual), status, duration, tokens used, and any errors. Use this to diagnose failed dispatches and understand what the system is doing.

18. Contacts

The Contacts page (/contacts.html) is the deep contact-management view — open it by clicking Manage → on any row of the People page. Where People is the day-to-day list (filters, import, segments), Contacts is where you work an individual record: event timeline, score history, sequence enrolment, and deletion.

Filters and Search

Four filter controls sit at the top of the list:

Stat Tiles

Above the list, four stat tiles show total contacts, confirmed subscribers, hot leads, and converted contacts. The tiles update in real time when filters change, giving a fast read on list health.

Stages and Scoring

Every contact has a lifecycle stage and a numeric engagement score. Stages advance automatically based on score thresholds:

Score events and their point values:

• Email open — +1 point
• Link click (in email or nurture message) — +3 points

Contact Detail Drawer

Click any contact row to open the detail drawer without leaving the list. The drawer contains three panels:

1. Profile — name, email, company, source, stage badge, consent status, and current score.
2. Event Timeline — chronological log of every tracked event (opt-in, email open, click, sequence enrol, newsletter open). Each event shows the timestamp and, for clicks, the destination URL.
3. Actions — Enrol in Sequence: a picker listing all active nurture sequences; select one and confirm to add the contact to that sequence's first step.
4. Danger zone — 🗑 Delete contact: permanently removes the contact. A confirmation dialog appears first; on confirm, the contact and all of their cascaded records (event history, consent log, and any sequence enrolments) are deleted. This cannot be undone.

19. Nurture

The Nurture page (/nurture.html) manages automated drip sequences — ordered sets of AI-generated messages sent to contacts at configured intervals.

Creating a Sequence

1. Name and describe the sequence

   Click + New Sequence. Give it a name (e.g., "Trial onboarding") and an optional goal description. The goal is passed to the AI when generating message copy.

2. Add steps

   Each step has three fields: Delay (hours or days after the previous step), Channel (email only in the current release), and Prompt (the instruction the AI uses to draft the message). Add as many steps as needed with + Add Step.

3. Preview an AI message

   Click Preview on any step to have the AI generate a sample message using that step's prompt and the brand voice. The preview is read-only — it does not create a draft or consume quota. Regenerate as often as needed.

4. Save and activate

   Click Save Sequence. Toggle the sequence to Active to allow enrolments. Inactive sequences accept no new contacts.

Enrolling a Contact

Open the Contacts page, click a contact's row to open the detail drawer, and click Enrol in Sequence. A picker lists all active sequences — select one and confirm. The contact enters the sequence at step 1; subsequent steps fire automatically per their delay settings.

You can also enrol directly from the Nurture page: each sequence card has a contact picker — search by name or email, select a contact, and enrol them.

Running Due Steps

The scheduler processes due nurture steps automatically about every 15 minutes. To send immediately, click Run Due Now on the sequence card — this processes all enrolled contacts whose next step delay has elapsed.

Autopilot and Approval Gates

Whether a nurture message is sent automatically or held for approval depends on the Autopilot Dial setting:

• Manual — every step message is queued in the Approvals queue before sending.
• Review or Auto-guardrails — messages are sent automatically unless a guardrail fires (e.g., the contact has unsubscribed, the brand's sending is paused, the monthly budget cap is hit, or no email provider is configured).

20. Newsletters

The Newsletters page (/newsletters.html) manages recurring broadcast emails sent to a segment of your contact list. Newsletter email is always Track 2 — it cannot be set to auto-send regardless of autopilot mode.

Creating a Newsletter Schedule

Click + New Newsletter and configure:

Building a Digest

Click Build Digest Now on any newsletter schedule to trigger immediate AI generation of the next issue. The agent compiles recent published content, recent trend signals (if web search is enabled), and the brand voice to draft the full email body. A Preview pane renders the HTML email so you can review formatting before approving.

Approving Pending Newsletters

Generated issues appear in the Approvals queue on the Command Center and on the Newsletters page under Pending Issues. Click Approve & Schedule to queue the send for the next dispatch window, or Edit to modify the body first. Rejecting a pending issue asks for a reason code (same flow as social post rejections).

Deliverability Auto-Pause

If a brand accumulates 3 or more spam-complaint or bounce events within 30 days, sending is automatically paused (the brand's sending_paused flag is set) and a warning card appears in the Command Center. Resolve the deliverability issue (clean your list, verify your sender domain), then clear the pause to resume sending.

Public Unsubscribe

Every newsletter issue includes a one-click unsubscribe link that resolves to a public page — no login required. Clicking it immediately sets the contact's consent status to Unsubscribed and removes them from all future newsletter sends and nurture sequences. Unsubscribed contacts remain in the Contacts list with their history intact.

21. Insights

The Insights page (/insights.html) surfaces AI-driven analysis of your content performance, audience behaviour, and content strategy suggestions.

Propose Plan (Planner)

Click Propose Plan to launch the Planner. The AI analyses recent post performance, rejection history, and current content pillars, then generates a strategic content plan as a set of editable content cards. Each card shows:

• Suggested topic and content type
• Rationale (why the AI recommends this)
• Target platform(s)
• Suggested publish date

You can edit any card's topic, type, or date inline. When satisfied, click Push to Create on individual cards (or Push All) to add them directly to the Content Calendar as draft entries — the AI then generates the full post content on the next dispatch cycle.

Rejection-Reason Summary

The Insights page aggregates all rejection reason codes collected from the Decisions and Approvals flows. The summary shows a breakdown by code (Off-brand, Factual issue, Wrong timing, Other) with counts and trend over the last 30 days. Use this to identify systemic issues with AI output — for example, a high "Off-brand" rate suggests the brand voice description needs refinement.

Suggest Prompt Tweaks

Based on the rejection-reason summary and post performance data, the AI can suggest specific edits to your brand voice, content pillars, or individual sequence prompts. Click Suggest Prompt Tweaks to generate these recommendations. Each suggestion shows the current text alongside the proposed replacement and the evidence behind the change. Accept individual suggestions with one click; rejected suggestions are dismissed and do not count toward future recommendations.