How to use BrandGrowth OS

The practical guide for end users (brand owners, marketers) and the founder/operator. This doc mirrors the product's structure — open the product and follow along. For editing the public pages (marketing/website team), read WEBSITE_HANDOFF.md instead.

---

1. Get in

• URL: https://productiveit.in/products/brandgrowth-os
• Sign up: Sign up → name, email, password → a verification email arrives from BrandGrowth OS <noreply@brandtroveglobal.com> → click the link → log in.
• Sign-in options: password, Google, GitHub, Microsoft (link additional providers later under Settings → Sign-in providers).
• 2FA (recommended): Settings → Two-factor authentication → scan the QR with Google Authenticator/Authy → confirm with a live code → save the 8 recovery codes somewhere safe (each works once; they are the lost-phone path).
• Docs: the Docs ↗ link in the header opens the public documentation (how-to guides, scoring rules, AI overview) on productiveit.in.
• Theme: light / dark / system — selector in the header; choice is remembered per browser.
• Works on mobile, tablet, desktop; the layout adapts down to small phones (iOS safe areas handled).

2. The workspace model

One organization (org) per brand/team. Everything you create — profiles, scans, campaigns — lives inside your workspace and is never visible to other workspaces. Plan limits (seats, scans/month, matches/month) come from your org's plan.

3. The engines — what each one does, in order of use

1. Profiles (set up first): create a Business Profile — brand name, industry, audience segments, geography, website, budget range, AOV, contribution margin. This data feeds every other engine, so the more honest the inputs, the better the outputs.
2. Visibility Radar — run a scan against your website (or the demo sites) and get a trust-scored report: SEO basics, structured data, socials, NAP consistency, content signals. Each finding carries a severity and a concrete fix. Findings roll up into the dashboard score.
3. BrandMatch — from your profile, runs partner candidates against your category/audience/geography and scores the fit. Every recommendation shows its source, freshness, and confidence — never a bare "trust me" list. Save the interesting ones.
4. Sponsorship Intelligence — sponsorship/influencer opportunities scored for relevance to your brand scope and budget; move them through new → considering → pursued → won/declined states.
5. Partnership ROI — model a campaign's return: enter spend, expected reach/conversion inputs, and compare scenarios side by side before committing money.
6. Opportunity Engine + Action Plan — the central engine turns everything above into ranked opportunities and a concrete recommended action plan with statuses. This is the "what do I do Monday morning" page.

4. The AI assistant

• "Explain in plain English" on a visibility finding (scan report) and on an action-plan item: a short AI-written paragraph that uses only that row's measured facts — no invented prices, quotes, or timelines. It is cached, and it is rewritten automatically when the underlying measurement or the scoring rules change, so it never describes an older version of the audit. If our AI providers are briefly unreachable, the last saved paragraph is shown instead — clearly labelled (an amber notice on the report, a possibly older rules chip on the action plan) with a Regenerate control, rather than passed off as current prose.
• Floating Ask button on every signed-in page.
• Practical growth questions: campaign planning, partnership comparisons, how to interpret a finding. It knows your workspace name and plan, and it will say "not measured in your workspace yet" rather than invent numbers.
• Remembers your conversation across devices and browsers — the thread is stored on the server against your account (last 40 messages, kept 180 days), so signing in anywhere continues where you left off. Clear (top of the dialog) wipes it everywhere; deleting your account deletes it with everything else.
• Rate limit: 20 messages / 5 minutes per user. Backed by free-tier models only (details in AI.md).

5. Notifications & weekly digest

• Inbox (header): engine events, team invites, and workspace plan changes. Operators also get a complete money-state trail in audit_logs: payment attempts, order links/outcomes, seat and pending-invite changes, live plan price/limit edits, and partner rate-card ranges are recorded by database triggers, including direct SQL changes. See BILLING.md and DATABASE.md for the operator audit query and scope.
• Monday email: "Weekly intelligence" digest per workspace — last week's findings, new opportunities, plan changes, plus a short AI-written "This week in numbers" summary (labeled as AI-assisted, generated only from your measured rows). Toggle per user under Settings → Notifications.
• The AI summary is cached per workspace and week, and never stale: it is kept with a fingerprint of the measurement it describes, so re-running the digest repeats the same sentence (a corrected email stays a correction) — but the moment an engine changes or the week's numbers change, the paragraph is rewritten, so nobody keeps reading a summary of pre-change rules. Operator controls: --regenerate-insight (force a rewrite) and --dry-run (read the cache, write nothing) — DEPLOY.md §4.2.
• The digest@ convention (team): the Monday cron mails every workspace member whose toggle is on, at their account email. To receive your digest in a specific inbox without putting your main address in the product, use a delivery alias: digest@brandtroveglobal.com (operator-managed in the mail admin, forwards to your real mailbox) — register or invite that alias as the workspace member and the digest lands wherever the alias points. Keep it to one hop (alias → real mailbox); never chain aliases through auto-forwarders — bulk machine mail landing in a personal Gmail is exactly what triggered Gmail's 2026-09-18 rate-limit on this domain (see the appendix in MAIL_MIGRATION_PLAN.md). Machine reports (DMARC aggregates) must use the dedicated dmarc-reports@… sinks, never a person's mailbox.
• Quiet-workspace notice: a workspace that records no findings, opportunities, or plan changes for two or more consecutive weekly windows gets an explicit notice at the top of the digest — the streak length, the window it covers, and the likely cause (a scan that never ran, or a site URL that changed) — instead of the same empty shell every Monday. It invents nothing: the notice only describes the absence of measured rows. The operator's Monday healthcheck (08:15 UTC) carries the same fact — a [WARN] (stale) line per quiet workspace and its streak length, measured with the same helpers the notice uses — so a workspace going quiet is caught without waiting for the customer to say so. It is a warning, not a failure: nothing in the pipeline broke, so it must not page like a broken run.
• Delivery mechanics (operator): cron runs Mondays 07:00 UTC and is idempotent per workspace+week via the weekly_digest_runs ledger — a week with an existing ledger row is skipped, even if it was generated early and empty. To re-send a week: delete that ledger row, then run the script (see §9). The script also refuses a live run for a week that has not completed (its ending Monday 00:00 UTC is still in the future) — a premature run can no longer write the empty ledger row that would make Monday skip the week; preview mid-week with --dry-run.
• Transactional email (verification, password reset OTP, invites) comes from noreply@brandtroveglobal.com; replies/contact go to info@productiveit.in.

6. Team

Team page: invite members by email (role: owner/admin/member/viewer — capability matrix enforced server-side). Invites arrive by email; accept from the link. Seats are plan-limited. Removing a member revokes access immediately.

7. Account safety & data control

• Settings: change password (invalidates other sessions), manage 2FA, manage linked providers, notification preferences.
• Delete account (Settings → danger zone): requires password; removes your user; workspaces are never silently deleted — an org without owners is removed by explicit operator action only.

8. Plans & paying

• Free — 1 scan/mo, 1 seat, 1 ROI analysis. Genuinely useful standalone.
• Pro ₹999/mo — 4 scans, BrandMatch runs, 3 seats.
• Business ₹2,999/mo — all engines + Opportunity Engine at scale, 10 seats.
• Enterprise — custom limits/billing.
• Checkout is enabled only when the Razorpay flag and valid credentials are present; otherwise paid tiers are activated by direct UPI/bank transfer — email info@productiveit.in, we send account details, payment activates the plan (usually same day) with a receipt. See BILLING.md for the checkout status and operator go-live procedure. Annual (2 months free) on request.
• Operator: to change a plan's price/limits, edit plans/plan_limits on the VPS (see the header comment in app/src/app/(marketing)/pricing/page.tsx) — goes live without a deploy, and is recorded (billing.plan_priced / billing.plan_limit_changed), so a hand-edited price leaves a trace like any other money change.

9. Founder/operator quick ops

Task	How
Deploy an update	push to master, then on the VPS: cd /opt/brandgrowth-os && scripts/deploy.sh --skip-migrate (the script finds Node ≥ 22 itself and restarts the systemd unit safely)
Approve or reject an upgrade request	/admin → Plan change requests → Approve & apply / Reject. Approving applies the plan (orgs.plan_key moves in the same transaction that records decided_by), so the request queue is the whole loop — no SQL. A double-click answers 409 ALREADY_DECIDED, and a request naming a retired plan is refused rather than granted
Check health	curl -s https://productiveit.in/products/brandgrowth-os/api/v1/healthz
See who's on	VPS: journalctl -u brandgrowth-os -n 50
Re-run weekly digest manually	VPS: node scripts/weekly-digest.mjs --dry-run (preview), then without --dry-run. Idempotent per workspace+week: if a week was generated early/empty, delete its weekly_digest_runs row first, then re-run
Re-send one week after a renderer/content fix	VPS: node scripts/weekly-digest.mjs --resend --org "<workspace name or UUID>" --week-start YYYY-MM-DD, then scripts/mail.sh. --resend is the narrow path: it requires --org, refuses an ambiguous name, and never touches the ledger — it exists precisely to push a corrected email for a week that was already generated (DEPLOY.md §4.2). The AI paragraph is reused from the cache while the measurement is unchanged; add --regenerate-insight to rewrite it
Watch for churn	the hourly plan-change notice emails every orgs.plan_key change (written by a trigger, so an operator's SQL is caught like a Razorpay capture). A downgrade carries its churn context: why (the request note when an operator approved one, otherwise the audit source), how old the workspace is, and when it was last used — a line marked ← REASON NOT RECORDED is the one to chase. Preview one without sending: node scripts/plan-change-notify.mjs --dry-run
Drain the email queue	automatic every 5 min; manual: node scripts/mail.mjs
Backups	automatic daily 03:15 + WAL continuous; offsite copy lands on the founder Mac daily; restore drills in DISASTER_RECOVERY.md
Monday health at a glance	the Monday ops dashboard email (08:30 UTC) merges the digest pipeline, AI free tiers, and backup freshness into one verdict — ALL CLEAR or N fail, M warn in the subject; sections name what broke and the documented fix
Inspect one section only	VPS: node scripts/digest-healthcheck.mjs --dry-run (digest), node scripts/ai-health-report.mjs --dry-run (AI), node scripts/ops-dashboard.mjs --dry-run (all three) — the dashboard prints the exact merged email without sending
AI providers down?	logs show [ai-gateway] all providers failed; features degrade, nothing breaks. Details in AI.md

10. Known limits (honesty section)

• Payments are manual (email/UPI) until a gateway is wired.
• BrandMatch/Sponsorship data quality depends on configured sources; recommendations show their evidence, and unknowns are marked "needs confirmation".
• The AI layer uses free tiers — throughput caps exist per provider; the fallback chain usually absorbs them.
• productiveit.in mail still lives at Zoho; the digest to a @productiveit.in address bounces until the planned mail migration (send to Gmail or a @brandtroveglobal.com alias meanwhile).