GapWrite

Turn content gaps into articles that grow. GapWrite audits a website, finds genuine content gaps, turns them into editable article drafts, and tracks how published content performs after the user publishes through their existing workflow.

Setup

1. Copy .env.local.example to .env.local.
2. Fill Convex, llmgateway.io, Google PageSpeed, and crawler worker values.
3. Run pnpm install.
4. Run pnpm exec auth once per Convex deployment to configure Convex Auth.
5. Run pnpm convex:codegen.
6. Install the worker dependencies:

cd worker
npm install
cp .env.example .env

7. Run the app, Convex, and worker as separate local processes:

pnpm dev
npx convex dev
pnpm worker:dev

Convex Auth stores its issuer and signing keys in the Convex deployment environment. The initializer configures SITE_URL, JWT_PRIVATE_KEY, and JWKS; use the same setup against production before deploying production auth.

Convex crawler actions also need CRAWLER_WORKER_URL and WORKER_SECRET to use the Playwright worker. When using hosted Convex dev or production, localhost points at the Convex runtime, not your laptop. Use a tunnel or deployed worker URL for CRAWLER_WORKER_URL, and set the same WORKER_SECRET in worker/.env and the Convex environment.

Do not set Convex CRAWLER_WORKER_URL to http://localhost:8008 unless the Convex action runtime is on the same machine as the worker. With the hosted npx convex dev deployment, either expose the worker through a public tunnel and use that URL, or unset CRAWLER_WORKER_URL to intentionally use the static crawler fallback.

If the worker is not configured or cannot be reached, the crawler falls back to a static HTML crawl so audits can still complete, but JavaScript-rendered content may be incomplete.

Content loop

The audit model classifies only genuine missing-topic findings as content opportunities. Eligible findings expose Add to content queue; technical and copy fixes remain regular audit findings.

The top-level Content workspace holds the opportunity queue, manual opportunities, a reusable content profile per site, selectable marketing-skill writing approaches, editable starter briefs, generated Markdown drafts, and the publication step.

Publishing remains CMS-agnostic: publish through the user's existing workflow, then record the exact live URL. Published articles can be tracked through Google Search Console and PostHog from the site Integrations screen.

Article performance integrations

Set these values in the Convex deployment environment (never as NEXT_PUBLIC_* variables):

• GOOGLE_OAUTH_CLIENT_ID
• GOOGLE_OAUTH_CLIENT_SECRET
• GOOGLE_OAUTH_REDIRECT_URI (for example, https://app.example.com/dashboard/integrations/google/callback)
• INTEGRATION_ENCRYPTION_KEY (exactly 32 random bytes encoded as base64; generate with openssl rand -base64 32)

In Google Cloud Console, enable the Search Console API, configure the exact callback URI, and request only https://www.googleapis.com/auth/webmasters.readonly. Start Google's OAuth verification immediately after creating the OAuth app: this sensitive scope is test-user limited until Google approves the app, and review can outlast implementation.

PostHog uses a read-only Personal API Key, Project ID, and PostHog host entered by the site owner. The key is validated against the project before it is encrypted and stored. Do not use the write/project key embedded in a website's tracking snippet.

The daily job stores rolling 28-day snapshots. Search Console commonly trails by 2–3 days. PostHog signup and paid conversion totals are credited to the last tracked article the same identified person viewed within the preceding seven days; reliable conversion totals therefore depend on correct event names and person identity instrumentation in the connected project.