@omega.js/manager 0.1.0

package/dist/services/edge/workers/omega-api-proxy.js

@@ -0,0 +1,43 @@
+/**
+ * Omega API Proxy Worker — for domains whose origin is NOT Firebase Hosting.
+ *
+ * Firebase-hosted api domains don't need this (hosting rewrites serve /omega
+ * directly). This worker is for brands that front a DEDICATED backend on the
+ * api domain (proxifly's shape: api.{domain} is its own API server) and still
+ * need the omega routes to reach the brand's Firebase Functions — the worker
+ * carves /omega (and the legacy /backend-manager alias) out at the Cloudflare
+ * edge and proxies it to
+ * us-central1-{FIREBASE_PROJECT_ID}.cloudfunctions.net/omega_api; everything
+ * else passes through to the origin untouched.
+ *
+ * Attach via edge.providers.cloudflare.workers config, e.g.:
+ *   { script: 'omega-api-proxy.js', route: 'api.{ domain }/omega*',
+ *     env: { FIREBASE_PROJECT_ID: '…' } }
+ */
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+
+    // Get Firebase project ID from environment variable
+    const firebaseProjectId = env.FIREBASE_PROJECT_ID;
+
+    // Check if path starts with /omega or the legacy /backend-manager alias
+    const prefix = ['/omega', '/backend-manager'].find((p) => url.pathname.startsWith(p));
+    if (prefix) {
+      // Build Firebase URL, removing the matched prefix
+      const firebasePath = url.pathname.replace(prefix, '') || '/';
+      const firebaseUrl = `https://us-central1-${firebaseProjectId}.cloudfunctions.net/omega_api${firebasePath}${url.search}`;
+
+      // Proxy the request
+      return fetch(firebaseUrl, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+      });
+    }
+
+    // Pass everything else through
+    return fetch(request);
+  }
+};

package/dist/services/email/data/baseline-filter.md

@@ -0,0 +1,4 @@
+-to:(
+  alerts@{ domain }
+  OR account@{ domain }
+)

package/dist/services/email/data/baseline-knowledge.md

@@ -0,0 +1,86 @@
+<billing_payments>
+  <cancellation_unsubscribe followup="0">
+    <reasoning>
+      - You CANNOT cancel a user's subscription for them, they must do it themselves. Emailing us is not a valid way to cancel a subscription.
+      - Users CANNOT upgrade or downgrade their plans. They must cancel their current plan and re-subscribe to the new plan they want.
+    </reasoning>
+    <facts>
+      - Users CAN cancel by visiting their account at { brand.url }/account#billing and clicking the "Manage Plan" button. From there, they can cancel their subscription.
+      - Users CAN change their payment method on an existing subscription by visiting their account at { brand.url }/account#billing and clicking the "Manage Plan" button.
+    </facts>
+  </cancellation_unsubscribe>
+
+  <subscription followup="0">
+    <facts>
+      - All current subscription plans and details are found at { brand.url }/pricing
+      - Users can cancel any time within their 14-day free trial and won't be charged.
+      - If the user is outside their free trial window, they can cancel their subscription at any time and won't be charged again.
+      - Sometimes, bank statements might show a charge during the free trial, but it's just a pre-authorization and will be refunded if the user cancels within the free trial period.
+    </facts>
+  </subscription>
+{discountSection}
+  <refund followup="0">
+    <reasoning>
+      - Before requesting a refund, users must cancel their subscription.
+      - DO NOT mention anything about a refund unless the user specifically asks for one.
+    </reasoning>
+    <facts>
+      - Users can receive a partial refund by visiting { brand.url }/refund and filling out the refund request form.
+      - Refunds are prorated based on the unused portion of the subscription.
+    </facts>
+  </refund>
+
+  <disputes followup="0">
+    <reasoning>
+      - DO NOT ever recommend that a user dispute their charge with their bank.
+      - Encourage the user to resolve disputes with us first.
+    </reasoning>
+  </disputes>
+</billing_payments>
+
+<delete_account_gdpr followup="0">
+  <facts>
+    - Users can delete their account, data, and request data by visiting { brand.url }/privacy
+  </facts>
+</delete_account_gdpr>
+
+<something_not_working followup="0">
+  <facts>
+    - Instruct users to try basic troubleshooting steps like signing out and back in, ensuring they are using the correct account, trying again later, etc.
+    - If they are using a browser, they should try clearing their cache and cookies and try a different browser.
+    - If they are using an app, they should try uninstalling and reinstalling the app.
+    - User should be instructed to send a screenshot of the issue.
+    - Getting "out of requests" error: Users need to upgrade their plan to get more requests or make sure they are using the right API key.
+  </facts>
+</something_not_working>
+
+<bug_bounty followup="0">
+  <reasoning>
+    - We ONLY reward for reports that have not been reported before.
+  </reasoning>
+  <facts>
+    - If the user has found a vulnerability, you can invite them to report it @ { brand.url }/security
+  </facts>
+</bug_bounty>
+
+<outreach_responses>
+  <reasoning>
+    - When the conversation starts with an outreach/marketing email from us (e.g. a discount nudge, a premium upgrade offer, a check-in), and the user replies positively or with interest, you MUST follow through on whatever was offered in that original email.
+    - If the original email offered a code, discount, upgrade, or link — provide it in your reply. DO NOT just say "you're welcome" or give a generic acknowledgment.
+    - Treat positive replies like "Thank you", "Yes please", "I'd love that", "Sure", "Sounds great" as the user ACCEPTING the offer. Deliver on it immediately.
+    - If you don't have the specific thing that was promised (e.g. a unique code that needs to be generated), acknowledge what was offered and provide the closest available resource (e.g. the discount code from the discount section, or a link to the pricing page).
+  </reasoning>
+</outreach_responses>
+
+<contact>
+  <reasoning>
+    - DO NOT agree to joining a phone call, video call, or any other form of communication outside of email. All communication should be done through this thread.
+  </reasoning>
+</contact>
+
+<resources>
+  <facts>
+    - Terms of Service: { brand.url }/terms
+    - Privacy Policy: { brand.url }/privacy
+  </facts>
+</resources>

package/dist/services/email/ensure/agent.js

@@ -0,0 +1,107 @@
+/**
+ * Ensure the brand's Replyify agent has the correct filter + knowledge.
+ *
+ * Filter = the brand's Gmail query (config/replyify.md `---filter---`
+ * section, or auto-generated to:(@domain)) ANDed with the baseline
+ * exclusion filter. Knowledge = the packaged baseline + the file's
+ * knowledge section appended (omega-manager read `.brands/{id}/replyify.md`).
+ *
+ * Diff-synced on the managed leaf fields and patched with a leaf mask so
+ * Replyify-owned fields (owner, id, metadata, other settings) survive —
+ * omega-manager merge-wrote on every run with no dry-run guard, and
+ * silently created an orphan agent document when the id was wrong; a
+ * missing agent is a visible error now (agents are created in the
+ * Replyify dashboard).
+ */
+const { join } = require('node:path');
+const fs = require('node:fs');
+const chalk = require('chalk').default;
+const { getBaselineKnowledge, getBaselineFilter } = require('../lib/baseline.js');
+const { parseKnowledgeFile } = require('../lib/knowledge-file.js');
+
+function extractDomain(websiteUrl) {
+  return websiteUrl.replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+}
+
+/**
+ * The default Gmail filter query — everything addressed to the brand's domain
+ */
+function generateFilterQuery(domain) {
+  return `(\n  to:(\n    @${domain}\n  )\n)`;
+}
+
+module.exports = async function ensureAgent(context) {
+  const { brandConfig, brandRoot, db, agentId, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  const brandName = brandConfig.brand.name;
+  const websiteUrl = brandConfig.brand.url;
+  const domain = extractDomain(websiteUrl);
+
+  // Brand-specific filter + knowledge file
+  const knowledgePath = join(brandRoot, 'config', 'replyify.md');
+  const rawContent = fs.existsSync(knowledgePath) ? fs.readFileSync(knowledgePath, 'utf8') : '';
+  const brandFile = parseKnowledgeFile(rawContent);
+
+  // Brand filter (file or auto-generated), merged with the baseline exclusions
+  const brandFilter = brandFile.filterQuery || generateFilterQuery(domain);
+  const filterQuery = `${brandFilter}\nAND\n${getBaselineFilter(brandConfig, domain)}`;
+
+  const baseline = getBaselineKnowledge(brandConfig, domain);
+  const knowledge = brandFile.knowledge ? `${baseline}\n\n${brandFile.knowledge}` : baseline;
+
+  const desired = {
+    name: `${brandName} - Customer Service`,
+    settings: {
+      filter: { query: filterQuery },
+      brand: {
+        name: brandName,
+        about: brandConfig.brand.description || '',
+        website: websiteUrl,
+        knowledge,
+      },
+    },
+  };
+
+  const fieldPaths = [
+    'name',
+    'settings.filter.query',
+    'settings.brand.name',
+    'settings.brand.about',
+    'settings.brand.website',
+    'settings.brand.knowledge',
+  ];
+
+  const agent = await db.getDoc(`agents/${agentId}`);
+
+  if (!agent) {
+    console.log(`      ${chalk.red('✗')} Agent ${chalk.cyan(agentId)} not found in Replyify — check inbound.email.providers.replyify.agentId (agents are created at ${chalk.cyan('https://replyify.app')})`);
+    return { status: 'error', error: `agent ${agentId} not found` };
+  }
+
+  const settings = agent.settings || {};
+  const drifted = agent.name !== desired.name
+    || settings.filter?.query !== filterQuery
+    || settings.brand?.name !== brandName
+    || settings.brand?.about !== desired.settings.brand.about
+    || settings.brand?.website !== websiteUrl
+    || settings.brand?.knowledge !== knowledge;
+
+  if (!drifted) {
+    console.log(`      ${chalk.green('✓')} Agent ${chalk.dim(agentId)} in sync ${chalk.dim(`(${desired.name})`)}`);
+    console.log(`        ${chalk.dim(`Knowledge: ${knowledge.length} chars (baseline + ${brandFile.knowledge.length} brand-specific)`)}`);
+    return { state: { agentId }, output: { agent: { synced: true } } };
+  }
+
+  if (dryRun) {
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would update agent ${chalk.cyan(agentId)} ${chalk.dim(`(${desired.name}, ${knowledge.length} chars knowledge)`)}`);
+    return { output: { agent: { planned: 'update' } } };
+  }
+
+  await db.patchDoc(`agents/${agentId}`, desired, fieldPaths);
+
+  console.log(`      ${chalk.green('✓')} Agent ${chalk.dim(agentId)} updated ${chalk.dim(`(${desired.name})`)}`);
+  console.log(`        ${chalk.dim(`Knowledge: ${knowledge.length} chars (baseline + ${brandFile.knowledge.length} brand-specific)`)}`);
+
+  return { state: { agentId }, output: { agent: { updated: true } } };
+};

package/dist/services/email/ensure/user.js

@@ -0,0 +1,45 @@
+/**
+ * Ensure the brand's Replyify owner account has the configured plan.
+ *
+ * The agent's owner UID identifies the user account; that user's
+ * subscription is set to inbound.email.providers.replyify.plan (DEFAULTS: Replyify's Max top tier)
+ * via the shared owner-plan reconciliation. omega-manager resolved the
+ * plan by reading the replyify brand's own config from `.brands/` (company
+ * mode); the port takes it from the brand's config with the top tier as
+ * the default.
+ */
+const chalk = require('chalk').default;
+const { ensureOwnerPlan } = require('../../../lib/owner-plan.js');
+
+module.exports = async function ensureUser(context) {
+  const { brandConfig, db, agentId, options } = context;
+
+  const plan = brandConfig.inbound?.email?.providers?.replyify?.plan;
+  if (!plan?.id) {
+    console.log(`      ${chalk.red('✗')} No inbound.email.providers.replyify.plan configured`);
+    return { status: 'error', error: 'no inbound.email.providers.replyify.plan.id configured' };
+  }
+
+  // The agent document carries the owner UID
+  const agent = await db.getDoc(`agents/${agentId}`);
+
+  if (!agent) {
+    console.log(`      ${chalk.red('✗')} Agent ${chalk.cyan(agentId)} not found in Replyify — check inbound.email.providers.replyify.agentId`);
+    return { status: 'error', error: `agent ${agentId} not found` };
+  }
+
+  const ownerUid = agent.owner;
+
+  if (!ownerUid) {
+    console.log(`      ${chalk.red('✗')} Agent ${chalk.cyan(agentId)} has no owner field`);
+    return { status: 'error', error: `agent ${agentId} has no owner` };
+  }
+
+  const result = await ensureOwnerPlan({ db, ownerUid, plan, dryRun: options?.dryRun || false });
+
+  if (result === 'planned') {
+    return { output: { user: { planned: plan.id } } };
+  }
+
+  return { state: { ownerUid }, output: { user: { plan: plan.id, [result]: true } } };
+};

package/dist/services/email/index.js

@@ -0,0 +1,138 @@
+/**
+ * Email service (`inbound.email.providers.replyify`) — the brand's
+ * customer-service email agent on Replyify (replyify.app): keeps the agent's
+ * Gmail filter + knowledge in sync (baseline templates with brand values +
+ * the brand repo's config/replyify.md merged in) and sets the agent-owner
+ * account to the configured plan (Replyify's top tier by default). Agents live in
+ * Replyify's own Firestore, so this service is for the Replyify operator:
+ * it needs a service account for Replyify's Firebase project.
+ *
+ * Auth tiers (2b, Ian 2026-07-13):
+ *   1. Operator SA — REPLYIFY_SERVICE_ACCOUNT in the brand .env (path to
+ *      the service-account JSON, absolute or brand-root-relative). Full
+ *      create + manage: a missing agentId with `inbound.email.providers.replyify.templateAgentId`
+ *      configured (the company layer's shape donor) MINTS the brand's own
+ *      agent — product user (email = brand contact email, password via the
+ *      account service's owner channels) + doc shape-templated from the
+ *      donor — and writes the new id back into omega.json5. The ensures
+ *      then converge filter/knowledge/plan in the same run.
+ *   2. User API key — REPLYIFY_API_KEY (the product accepts
+ *      user.api.privateKey): recognized, management via the product's
+ *      public API lands when those routes are verified.
+ *   3. Dashboard — interactive runs offer the setup flow (open
+ *      replyify.app, paste the agent id back — comment-preserving
+ *      writeback, with a Disable option that sets `replyify: false`).
+ *      Non-interactive and dry runs skip cleanly.
+ */
+const chalk = require('chalk').default;
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { FirestoreREST, loadServiceAccount } = require('../../lib/firestore-rest.js');
+const { createAuthAdmin } = require('../../lib/auth-admin.js');
+const { resolveConfigValue, landValue } = require('../../lib/config-flow.js');
+const { createProductAsset } = require('../../lib/product-create.js');
+const { createPasswordResolver } = require('../account/lib/resolve-password.js');
+
+const REPLYIFY_URL = 'https://replyify.app';
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const config = context.brandConfig.inbound?.email?.providers?.replyify;
+
+    if (config === false || config?.enabled === false) {
+      return { skip: true, reason: 'inbound.email.providers.replyify.enabled = false' };
+    }
+
+    // A shared agent managed by another brand must not be rewritten here
+    if (config?.updateAgentInfo === false) {
+      return { skip: true, reason: 'agent managed by another brand (inbound.email.providers.replyify.updateAgentInfo = false)' };
+    }
+
+    // The agent answers the brand's support email, which the backend serves
+    if (!context.brandConfig.targets?.backend) {
+      return { skip: true, reason: 'no backend target' };
+    }
+
+    // Operator credentials first — create-on-missing needs them before the
+    // id resolution. Tests inject fakes via context.replyifyDb/-AuthAdmin.
+    let db = context.replyifyDb;
+    let authAdmin = context.replyifyAuthAdmin;
+    if (!db) {
+      const envPath = process.env.REPLYIFY_SERVICE_ACCOUNT;
+      if (envPath) {
+        const serviceAccount = loadServiceAccount(envPath, context.brandRoot);
+        db = new FirestoreREST(serviceAccount);
+        authAdmin = createAuthAdmin(serviceAccount);
+      }
+    }
+
+    const brand = context.brandConfig.brand || {};
+    const dryRun = context.options?.dryRun || false;
+    let agentId = config?.agentId;
+
+    // 2b create-on-missing: operator SA + a template donor → a missing agent
+    // means MINT the brand's own (product user + doc), write the id back,
+    // and let the ensures below converge it in this same run.
+    if (!agentId && db && authAdmin && config?.templateAgentId && brand.contact?.email) {
+      const created = await createProductAsset({
+        db,
+        authAdmin,
+        collection: 'agents',
+        templateId: config.templateAgentId,
+        email: brand.contact.email,
+        resolvePassword: createPasswordResolver({
+          brandRoot: context.brandRoot,
+          domain: new URL(brand.url || 'https://invalid.test').hostname,
+          brand,
+          dryRun,
+        }),
+        dryRun,
+        log: (line) => console.log(`      ${line}`),
+      });
+
+      if (!created) {
+        return { skip: true, reason: 'dry run — agent creation planned (from inbound.email.providers.replyify.templateAgentId)' };
+      }
+
+      landValue(context, 'inbound.email.providers.replyify.agentId', created.id);
+      console.log(`      ${chalk.green('✓')} inbound.email.providers.replyify.agentId = ${chalk.cyan(created.id)} written to omega.json5`);
+      agentId = created.id;
+    }
+
+    if (!agentId) {
+      agentId = await resolveConfigValue(context, {
+        path: 'inbound.email.providers.replyify.agentId',
+        label: 'Replyify email agent',
+        instructions: [
+          `1. Create an account at ${chalk.cyan(REPLYIFY_URL)} (if you haven't already)`,
+          `2. Create an email agent for ${chalk.cyan(brand.name || context.brandId)}`,
+        ],
+        entry: { url: REPLYIFY_URL, message: 'Replyify agent ID:' },
+        disablePath: 'inbound.email.providers.replyify',
+      });
+    }
+    if (!agentId) {
+      return { skip: true, reason: 'no inbound.email.providers.replyify.agentId configured — set inbound.email.providers.replyify.templateAgentId + the operator SA to mint one automatically, create one at https://replyify.app (paste back interactively), or set it in omega.json5' };
+    }
+
+    if (!db) {
+      if (process.env.REPLYIFY_API_KEY) {
+        return {
+          skip: true,
+          reason: 'REPLYIFY_API_KEY recognized, but product-API management is not wired yet — use the operator SA (REPLYIFY_SERVICE_ACCOUNT) or the dashboard',
+        };
+      }
+
+      // The shared setup contract (#608): the operator SA is asked for right
+      // here — most brands are not the Replyify operator and answer Disable,
+      // which retires the ask for good.
+      const gate = await requestServiceInput(context, serviceInputSpec('email'));
+      if (gate) return gate;
+      db = new FirestoreREST(loadServiceAccount(process.env.REPLYIFY_SERVICE_ACCOUNT, context.brandRoot));
+    }
+
+    return { db, agentId };
+  },
+});

package/dist/services/email/lib/baseline.js

@@ -0,0 +1,82 @@
+/**
+ * Baseline templates for Replyify agents — the shared support knowledge and
+ * the baseline Gmail filter every brand agent gets, loaded from data/ with
+ * the brand's values filled in via the manager's templateObject (flat
+ * `{ brand.url }` / `{ domain }` placeholders).
+ *
+ * De-ITW'd from omega-manager's baseline: the company sponsorship business
+ * block (guest-post rules, the company sponsorship URL, its promo code) is
+ * GONE from the packaged template — company business prose belongs in the
+ * brand/company config/replyify.md that gets appended to the baseline. The
+ * discount section only renders when `inbound.email.providers.replyify.discount` is configured
+ * (omega-manager hardcoded the company's GIFT15 code for every brand); with
+ * no code configured the section is omitted entirely so agents can never
+ * invent one.
+ */
+const { join } = require('node:path');
+const fs = require('node:fs');
+const { templateObject } = require('../../../config.js');
+
+const BASELINE_KNOWLEDGE = fs.readFileSync(join(__dirname, '..', 'data', 'baseline-knowledge.md'), 'utf8').trimEnd();
+const BASELINE_FILTER = fs.readFileSync(join(__dirname, '..', 'data', 'baseline-filter.md'), 'utf8').trimEnd();
+
+// Spliced into baseline-knowledge.md's {discountSection} slot only when
+// inbound.email.providers.replyify.discount carries a code
+const DISCOUNT_SECTION = `  <discount followup="0">
+    <reasoning>
+      - DO NOT offer or mention a discount proactively. Only provide a code if the user SPECIFICALLY asks for one (e.g. they reply asking for a deal, a promo code, or a way to save).
+      - Provide the code warmly and only ONCE per conversation. DO NOT repeat the code if you have already shared it.
+      - DO NOT invent or guess a code. Only ever share the exact code below.
+    </reasoning>
+    <facts>
+      - Discount code: { discount.code } ({ discount.label }).
+      - Users redeem the code at checkout when subscribing at { brand.url }/pricing?utm_source=replyify&utm_medium=customer_support&utm_campaign=discount_code
+    </facts>
+  </discount>`;
+
+/**
+ * Build the flat placeholder context templateObject resolves against.
+ * Discount keys join only when configured — templateObject would stringify
+ * an undefined value.
+ */
+function templateContext(brandConfig, domain) {
+  const discount = brandConfig.inbound?.email?.providers?.replyify?.discount;
+
+  return {
+    'brand.name': brandConfig.brand.name,
+    'brand.url': brandConfig.brand.url,
+    domain,
+    ...(discount?.code ? { 'discount.code': discount.code, 'discount.label': discount.label || '' } : {}),
+  };
+}
+
+/**
+ * Get the baseline knowledge with placeholders replaced and the discount
+ * section rendered only when inbound.email.providers.replyify.discount is configured.
+ *
+ * @param {Object} brandConfig - The full brand config object
+ * @param {string} domain - Brand domain (e.g. "fixture-brand.test")
+ * @returns {string}
+ */
+function getBaselineKnowledge(brandConfig, domain) {
+  const discount = brandConfig.inbound?.email?.providers?.replyify?.discount;
+  const withDiscount = BASELINE_KNOWLEDGE.replace(
+    '{discountSection}',
+    discount?.code ? `\n${DISCOUNT_SECTION}\n` : '',
+  );
+
+  return templateObject(withDiscount, templateContext(brandConfig, domain));
+}
+
+/**
+ * Get the baseline Gmail filter with the brand's domain filled in.
+ *
+ * @param {Object} brandConfig - The full brand config object
+ * @param {string} domain - Brand domain
+ * @returns {string}
+ */
+function getBaselineFilter(brandConfig, domain) {
+  return templateObject(BASELINE_FILTER, templateContext(brandConfig, domain));
+}
+
+module.exports = { getBaselineKnowledge, getBaselineFilter };

package/dist/services/email/lib/knowledge-file.js

@@ -0,0 +1,53 @@
+/**
+ * Parser for the brand's config/replyify.md — an optional custom Gmail
+ * filter section plus brand-specific knowledge appended to the baseline
+ * (omega-manager read `.brands/{id}/replyify.md`).
+ *
+ * Supported formats:
+ *   1. Both delimiters:        ---filter---\n(query)\n---knowledge---\n(text)
+ *   2. Filter only:            ---filter---\n(query)
+ *   3. Knowledge delimiter:    ---knowledge---\n(text)
+ *   4. No delimiters:          the whole file is knowledge
+ */
+const FILTER_DELIMITER = '---filter---';
+const KNOWLEDGE_DELIMITER = '---knowledge---';
+
+/**
+ * @param {string} content - Raw file content
+ * @returns {{ filterQuery: string|null, knowledge: string }}
+ */
+function parseKnowledgeFile(content) {
+  const hasFilter = content.includes(FILTER_DELIMITER);
+  const hasKnowledge = content.includes(KNOWLEDGE_DELIMITER);
+
+  if (hasFilter && hasKnowledge) {
+    const afterFilter = content.split(FILTER_DELIMITER)[1];
+    const [filterPart, ...knowledgeParts] = afterFilter.split(KNOWLEDGE_DELIMITER);
+
+    return {
+      filterQuery: filterPart.trim(),
+      knowledge: knowledgeParts.join(KNOWLEDGE_DELIMITER).trim(),
+    };
+  }
+
+  if (hasFilter) {
+    return {
+      filterQuery: content.split(FILTER_DELIMITER)[1].trim(),
+      knowledge: '',
+    };
+  }
+
+  if (hasKnowledge) {
+    return {
+      filterQuery: null,
+      knowledge: content.split(KNOWLEDGE_DELIMITER)[1].trim(),
+    };
+  }
+
+  return {
+    filterQuery: null,
+    knowledge: content.trim(),
+  };
+}
+
+module.exports = { parseKnowledgeFile };

package/dist/services/forms/ensure/form.js

@@ -0,0 +1,46 @@
+/**
+ * Ensure the brand's Slapform contact form has the correct settings —
+ * name matches the brand, form enabled.
+ *
+ * Diff-synced: the form document is read first and only patched on drift
+ * (omega-manager merge-wrote it on every run, with no dry-run guard). A
+ * formId that points at no document is an error — the form must be created
+ * in the Slapform dashboard first (omega-manager silently created a
+ * name-only orphan document in that case).
+ */
+const chalk = require('chalk').default;
+
+module.exports = async function ensureForm(context) {
+  const { brandConfig, db, formId, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  const desiredName = `Contact Form - ${brandConfig.brand.name}`;
+
+  const form = await db.getDoc(`forms/${formId}`);
+
+  if (!form) {
+    console.log(`      ${chalk.red('✗')} Form ${chalk.cyan(formId)} not found in Slapform — check forms.providers.slapform.formId (forms are created at ${chalk.cyan('https://slapform.com')})`);
+    return { status: 'error', error: `form ${formId} not found` };
+  }
+
+  const drifted = form.name !== desiredName || form.settings?.enabled !== true;
+
+  if (!drifted) {
+    console.log(`      ${chalk.green('✓')} Form ${chalk.dim(formId)} in sync ${chalk.dim(`(${desiredName})`)}`);
+    return { state: { formId }, output: { form: { synced: true } } };
+  }
+
+  if (dryRun) {
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would update form ${chalk.cyan(formId)} ${chalk.dim(`(name → ${desiredName}, enabled → true)`)}`);
+    return { output: { form: { planned: 'update' } } };
+  }
+
+  await db.patchDoc(`forms/${formId}`, {
+    name: desiredName,
+    settings: { enabled: true },
+  }, ['name', 'settings.enabled']);
+
+  console.log(`      ${chalk.green('✓')} Form ${chalk.dim(formId)} updated ${chalk.dim(`(${desiredName})`)}`);
+
+  return { state: { formId }, output: { form: { updated: true } } };
+};

package/dist/services/forms/ensure/user.js

@@ -0,0 +1,45 @@
+/**
+ * Ensure the brand's Slapform owner account has the configured plan.
+ *
+ * The form's owner UID identifies the user account; that user's
+ * subscription is set to forms.providers.slapform.plan (DEFAULTS: Slapform's Grandmaster
+ * top tier) via the shared owner-plan reconciliation. omega-manager
+ * resolved the plan by reading the slapform brand's own config from
+ * `.brands/` (company mode); the port takes it from the brand's config
+ * with the top tier as the default.
+ */
+const chalk = require('chalk').default;
+const { ensureOwnerPlan } = require('../../../lib/owner-plan.js');
+
+module.exports = async function ensureUser(context) {
+  const { brandConfig, db, formId, options } = context;
+
+  const plan = brandConfig.forms?.providers?.slapform?.plan;
+  if (!plan?.id) {
+    console.log(`      ${chalk.red('✗')} No forms.providers.slapform.plan configured`);
+    return { status: 'error', error: 'no forms.providers.slapform.plan.id configured' };
+  }
+
+  // The form document carries the owner UID
+  const form = await db.getDoc(`forms/${formId}`);
+
+  if (!form) {
+    console.log(`      ${chalk.red('✗')} Form ${chalk.cyan(formId)} not found in Slapform — check forms.providers.slapform.formId`);
+    return { status: 'error', error: `form ${formId} not found` };
+  }
+
+  const ownerUid = form.owner;
+
+  if (!ownerUid) {
+    console.log(`      ${chalk.red('✗')} Form ${chalk.cyan(formId)} has no owner field`);
+    return { status: 'error', error: `form ${formId} has no owner` };
+  }
+
+  const result = await ensureOwnerPlan({ db, ownerUid, plan, dryRun: options?.dryRun || false });
+
+  if (result === 'planned') {
+    return { output: { user: { planned: plan.id } } };
+  }
+
+  return { state: { ownerUid }, output: { user: { plan: plan.id, [result]: true } } };
+};