hubspot-cms-sync 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# hubspot-cms-sync
+
+Git-backed bidirectional HubSpot CMS sync for themes, site pages, page module
+content, blogs, forms, and assets.
+
+The package provides the `hubspot-cms-sync` CLI plus the short `hcms` alias.
+It reads account and site settings from `hubspot-cms-sync.config.mjs`, stores
+per-account identity in a gitignored `.sync-state/` directory, and refuses to
+push to configured read-only portal ids.
+
+## Install
+
+```bash
+npm install --save-dev hubspot-cms-sync
+```
+
+For local development from a sibling checkout:
+
+```bash
+npm install --save-dev ../hubspot-cms-sync
+```
+
+## Commands
+
+```bash
+hcms doctor
+hubspot-cms-sync pull prod
+hubspot-cms-sync preflight dev
+hubspot-cms-sync push dev --publish
+hcms push dev --dry-run
+hubspot-cms-sync republish dev --all --blog
+hubspot-cms-sync corpus
+hcms manifest validate
+```
+
+## Configuration
+
+Copy `examples/hubspot-cms-sync.config.mjs` into the consuming repo, then set
+the theme name, manifest path, read-only portal ids, and account registry path.
+Account keys live outside git at `$HUBSPOT_KEY_DIR/<portalId>.key` or
+`~/.hubspot/<portalId>.key`.
+
+## Tests
+
+```bash
+npm test
+npm run lint
+npm pack --dry-run
+```
+
+Live HubSpot round-trip tests are skipped by default and require
+`RUN_INTEGRATION=1` plus sandbox credentials.

package/bin/hubspot-cms-sync.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { loadConfig } from '../src/config.mjs';
+import { pull } from '../src/pull.mjs';
+import { push } from '../src/push.mjs';
+import { main as preflightMain } from '../src/preflight.mjs';
+import { main as republishMain } from '../src/republish.mjs';
+import { main as manifestMain } from '../src/manifest.mjs';
+
+function usage() {
+  console.log(`usage: hcms [--root <path>] <command> [args]
+
+commands:
+  pull <account>
+  push <account> [--publish] [--dry-run]
+  preflight <account>
+  republish <account|portalId> [--all] [--blog] [slugs...]
+  corpus [paths...]
+  manifest [args...]
+  doctor
+`);
+}
+
+function parseGlobal(argv) {
+  const out = { root: process.cwd(), args: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--root') {
+      out.root = argv[++i];
+    } else {
+      out.args.push(a);
+    }
+  }
+  return out;
+}
+
+function runNodeScript(script, args, { cwd }) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [script, ...args], { cwd, stdio: 'inherit' });
+    child.on('exit', (code) => resolve(code ?? 1));
+  });
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const { root, args } = parseGlobal(argv);
+  const [cmd, ...rest] = args;
+  if (!cmd || cmd === '-h' || cmd === '--help') {
+    usage();
+    return cmd ? 0 : 2;
+  }
+
+  const config = await loadConfig({ root });
+
+  if (cmd === 'doctor') {
+    console.log(`root: ${config.root}`);
+    console.log(`accounts: ${config.accountsPath}`);
+    console.log(`content: ${config.contentDirPath}`);
+    console.log(`manifest: ${config.manifestFilePath}`);
+    console.log(`sync state: ${config.syncStateDirPath}`);
+    console.log(`theme: ${config.theme.name}`);
+    return 0;
+  }
+
+  if (cmd === 'pull') {
+    const account = rest[0];
+    if (!account) throw new Error('pull requires <account>');
+    await pull(account, { config });
+    return 0;
+  }
+
+  if (cmd === 'push') {
+    const publish = rest.includes('--publish');
+    const dryRun = rest.includes('--dry-run');
+    const account = rest.find((a) => !a.startsWith('--'));
+    if (!account) throw new Error('push requires <account>');
+    if (dryRun) {
+      // Current engine preflight is the no-write plan surface. A future plan command
+      // can add per-adapter write summaries.
+      const { preflightRefs } = await import('../src/push.mjs');
+      preflightRefs(config.contentDirPath);
+      console.log(`dry-run push preflight passed for ${account}`);
+      return 0;
+    }
+    await push(account, { publish, config });
+    return 0;
+  }
+
+  if (cmd === 'preflight') {
+    return preflightMain(rest, { config });
+  }
+
+  if (cmd === 'republish') {
+    return republishMain(rest, { config });
+  }
+
+  if (cmd === 'manifest') {
+    return manifestMain(rest, { config });
+  }
+
+  if (cmd === 'corpus') {
+    const script = new URL('../src/corpus-scan.mjs', import.meta.url).pathname;
+    return runNodeScript(script, rest, { cwd: config.root });
+  }
+
+  usage();
+  return 2;
+}
+
+main().then((code) => {
+  process.exitCode = code;
+}).catch((e) => {
+  console.error(`hcms failed: ${e.message}`);
+  process.exitCode = 1;
+});

package/docs/CONFIGURATION.md

@@ -0,0 +1,83 @@
+# Configuration Plan
+
+The package should be driven by `hubspot-cms-sync.config.mjs` in the consuming
+repo root.
+
+Example:
+
+```js
+export default {
+  accountsFile: 'sync/accounts.json',
+  keyDirEnv: 'HUBSPOT_KEY_DIR',
+  contentDir: 'content',
+  syncStateDir: '.sync-state',
+  manifestPath: 'site.manifest.json',
+  readOnlyPortalIds: ['529456'],
+  knownPortalIds: ['529456', '246389711'],
+  assetHosts: {
+    canonicalizeHostPatterns: [
+      'hubfs',
+      'hubspotusercontent',
+      'cdn\\d*\\.hubspot\\.net'
+    ],
+    legacySiteHosts: []
+  },
+  adapters: {
+    externalDirs: []
+  },
+  theme: {
+    name: 'seventh-sense-theme',
+    dirs: ['templates', 'modules', 'css', 'js', 'images'],
+    files: ['theme.json', 'fields.json']
+  },
+  blog: {
+    slug: 'blog',
+    itemTemplate: 'seventh-sense-theme/templates/blog-post.html',
+    listingTemplate: 'seventh-sense-theme/templates/blog.html'
+  },
+  uiGated: [
+    'blogContainerCreate',
+    'domainConnect',
+    'homepageDesignation',
+    'themeSettingsValues',
+    'nativeMenus'
+  ],
+  verification: {
+    baseUrlEnv: 'SITE_BASE_URL',
+    commands: {
+      unit: 'npm run test:unit',
+      corpus: 'hcms corpus',
+      playwright: 'npx playwright test verify/fidelity.spec.mjs verify/forms.spec.mjs verify/links.spec.mjs'
+    }
+  }
+};
+```
+
+## Design Requirements
+
+- Config paths are relative to `--root` / `process.cwd()`.
+- The CLI resolves config once, derives absolute paths, and passes that object
+  explicitly. Avoid hidden module-level global state.
+- Package defaults are safe and minimal.
+- No consumer-specific portal IDs are hardcoded in source.
+- The config loader validates shape and prints remediation, not stack traces.
+- `site.manifest.json` remains the deploy surface for content, pages, forms, and
+  blog.
+- `hubspot-cms-sync.config.mjs` controls environment policy and filesystem
+  layout.
+
+## Open Config Questions
+
+- Should the package support TypeScript configs or only ESM?
+- Should CTA/menu adapters be optional plugins or built-in later?
+
+## Decisions From Plan Review
+
+- Project-specific adapters should be supported only after core extraction works.
+  If supported, they should come from explicit `adapters.externalDirs` entries and
+  participate in the same `dependsOn` validation as built-in adapters.
+- `knownPortalIds` cannot remain hardcoded. For v1, require explicit config or
+  derive from `accountsFile` plus any registry portal IDs; tests must cover both
+  behaviors before generic publication.
+- `readOnlyPortalIds` must be an array. Push/preflight checks use membership,
+  not a single hardcoded production portal.

package/docs/GITHUB_ACTIONS.md

@@ -0,0 +1,70 @@
+# GitHub Actions Examples
+
+This package is currently a planning scaffold. The workflows in
+`examples/github-actions/` are distribution templates for future consuming
+repositories after the `hubspot-cms-sync` CLI is published.
+
+Copy the examples into a consuming repo's `.github/workflows/` directory and
+adjust portal names, credentials, branch policy, and verification commands to
+match that repo's `hubspot-cms-sync.config.mjs`.
+
+## Shared Assumptions
+
+- The consuming repo has a committed `hubspot-cms-sync.config.mjs`.
+- The consuming repo has a committed `site.manifest.json`.
+- The CLI is available through either a project dependency or
+  `npx --yes hubspot-cms-sync@latest`.
+- `HUBSPOT_KEY_DIR` points at credentials hydrated during the workflow.
+- Workflow targets such as `dev`, `preview`, and `prod` are examples. Use the
+  names defined by the consuming repo's accounts file and config.
+- Production portals should be protected by GitHub Environments and should not
+  be used for pull request previews.
+
+## Secrets
+
+Use repository or environment secrets. Exact secret names can vary, but the
+workflow should hydrate whatever credential files the consuming repo's
+`accountsFile` expects.
+
+Suggested baseline:
+
+- `HUBSPOT_DEV_PRIVATE_APP_TOKEN`
+- `HUBSPOT_PREVIEW_PRIVATE_APP_TOKEN`
+- `HUBSPOT_PROD_PRIVATE_APP_TOKEN`
+- `SITE_BASE_URL` or an environment-specific equivalent
+
+Do not commit generated credential files or `.sync-state` mutations from CI
+unless the consuming repo intentionally uses a reviewed pull flow for state
+updates.
+
+## Example Workflows
+
+- `examples/github-actions/ci.yml`: read-only checks for pull requests and
+  pushes.
+- `examples/github-actions/preview.yml`: deploy a pull request to a non-prod
+  preview portal and run verification.
+- `examples/github-actions/publish.yml`: manually publish to a protected target.
+
+## Command Policy
+
+The examples prefer this sequence for write-capable operations:
+
+1. `hcms doctor`
+2. `hcms corpus`
+3. `hcms preflight <target>`
+4. `hcms push <target> --dry-run`
+5. `hcms push <target> --publish`
+6. `the consuming repo verification commands`
+
+For read-only CI, omit write steps and keep production credentials unavailable.
+
+## Guardrails
+
+- Do not bypass `readOnlyPortalIds`.
+- Do not use production credentials in `pull_request` workflows.
+- Keep publish workflows behind `workflow_dispatch` and a protected GitHub
+  Environment.
+- Treat surviving `@cta:*` and `@menu:*` references as closed failures until
+  producer adapters exist.
+- Treat HubSpot writes as rerun-to-convergence operations, not transactional
+  rollbacks.

package/docs/MIGRATION_PLAN.md

@@ -0,0 +1,361 @@
+# Migration Plan
+
+This plan extracts the HubSpot CMS sync system from
+`../7thsense-website/sync` into this standalone npm package.
+
+The goal is not just moving files. The goal is to turn a repo-specific set of
+working scripts into a reusable product surface:
+
+- npm CLI for deterministic local and CI execution.
+- Config-driven adapters instead of Seventh Sense constants in code.
+- Clean import path from a consuming website repo.
+- Optional Codex skill that uses the npm CLI rather than duplicating the engine.
+
+---
+
+## Current Source Inventory
+
+Move or port these from `../7thsense-website/sync`:
+
+| Source file | Package target | Notes |
+| --- | --- | --- |
+| `sync/pull.mjs` | `src/commands/pull.mjs` | Convert CLI parsing to shared command runner |
+| `sync/push.mjs` | `src/commands/push.mjs` | Keep prod guard, make read-only portals config-driven |
+| `sync/preflight.mjs` | `src/commands/preflight.mjs` | Make theme/blog expectations config-driven |
+| `sync/republish.mjs` | `src/commands/republish.mjs` | Convert raw portal arg to account resolution |
+| `sync/manifest.mjs` | `src/manifest.mjs` | Generalize theme name and page filters |
+| `sync/cta-inventory.mjs` | `src/cta-inventory.mjs` | Keep as optional read-only CTA normalization helper |
+| `sync/lib/*.mjs` | `src/lib/*.mjs` | Remove hardcoded repo roots and known portals |
+| `sync/adapters/*.mjs` | `src/adapters/*.mjs` | Make paths and constants config-driven |
+| `scripts/corpus-scan.mjs` | `src/commands/corpus.mjs` | Required for `hcms corpus`; currently outside `sync/` |
+| `test/unit/**/*.test.mjs` | `test/unit/` | Engine tests move with the engine and import from `src/` |
+| `test/integration/**/*.test.mjs` | `test/integration/` | Live/dev-account engine integration tests move with package |
+
+Leave these behind or archive as legacy in the website repo:
+
+| Legacy file | Action |
+| --- | --- |
+| `sync/blog-sync.mjs` | Remove after adapter parity is confirmed |
+| `sync/cms-pull.mjs` | Remove after unified `pull` covers page definitions |
+| `sync/forms-sync.mjs` | Remove after forms adapter handles push/pull |
+| `sync/page-content.mjs` | Remove after content adapter covers widgets |
+
+Keep these in the website repo:
+
+| Website-local files | Reason |
+| --- | --- |
+| `verify/**/*.spec.mjs` | Site-specific Playwright fidelity/forms/links gates |
+| `verify/**/*-snapshots/**` | Site-specific visual baselines |
+| `content/**`, `templates/**`, `modules/**`, `css/**`, `js/**`, `images/**` | The consuming site source of truth |
+
+---
+
+## Target Package Layout
+
+```text
+hubspot-cms-sync/
+├── bin/
+│   └── hubspot-cms-sync.mjs
+├── src/
+│   ├── index.mjs
+│   ├── cli.mjs
+│   ├── config.mjs
+│   ├── manifest.mjs
+│   ├── commands/
+│   │   ├── init.mjs
+│   │   ├── pull.mjs
+│   │   ├── push.mjs
+│   │   ├── preflight.mjs
+│   │   ├── republish.mjs
+│   │   ├── corpus.mjs
+│   │   └── verify.mjs
+│   ├── adapters/
+│   │   ├── assets.mjs
+│   │   ├── blog.mjs
+│   │   ├── content.mjs
+│   │   ├── forms.mjs
+│   │   ├── pages.mjs
+│   │   └── theme.mjs
+│   └── lib/
+│       ├── canonical.mjs
+│       ├── hub.mjs
+│       ├── orchestrate.mjs
+│       ├── refs.mjs
+│       └── sync-state.mjs
+├── examples/
+│   ├── hubspot-cms-sync.config.mjs
+│   └── site.manifest.json
+├── test/
+└── docs/
+```
+
+---
+
+## Phase 1: Extract Without Generalizing Too Much
+
+Objective: prove the package can run the Seventh Sense workflow from outside the
+website repo.
+
+Steps:
+
+1. Copy unified sync files into `src/`.
+2. Add a CLI wrapper with these commands:
+   - `pull <account>`
+   - `preflight <account>`
+   - `push <account> [--publish]`
+   - `republish <account|portalId> [--all] [--blog]`
+   - `corpus [paths...]`
+3. Add `--root <path>` and default it to `process.cwd()`.
+4. Replace package-relative repo roots with an explicit resolved config object,
+   built once in `src/cli.mjs` and passed into commands/libs/adapters. Do **not**
+   use module-level `configure()` global state.
+   Modules that currently need root/config threading:
+   - `hub.mjs`: accounts path currently resolves from `__dirname`.
+   - `manifest.mjs`: repo root and manifest path currently resolve from `__dirname`.
+   - `sync-state.mjs`: `content/` and `.sync-state/` currently resolve from package source.
+   - `theme.mjs`: theme root and temp `.sync-state` build path currently resolve from package source.
+   - `preflight.mjs`: repo root and theme name currently resolve from package source.
+   - `refs.mjs`: known portal IDs are currently hardcoded.
+5. Keep the current adapter names and behavior.
+6. Run the package against `../7thsense-website` using `node ../hubspot-cms-sync/bin/... --root .`.
+7. Do not delete website repo scripts yet.
+
+Acceptance:
+
+```bash
+cd ../7thsense-website
+node ../hubspot-cms-sync/bin/hubspot-cms-sync.mjs corpus
+node ../hubspot-cms-sync/bin/hubspot-cms-sync.mjs preflight dev
+node ../hubspot-cms-sync/bin/hubspot-cms-sync.mjs push dev --dry-run
+```
+
+The first extraction is allowed to still require a Seventh Sense-shaped config.
+It must also prove the engine works when `cwd` is the website repo and package
+source lives elsewhere; no command may accidentally read/write inside
+`node_modules/hubspot-cms-sync` or `../hubspot-cms-sync`.
+
+---
+
+## Phase 2: Config-Drive Repo-Specific Values
+
+Objective: make the package reusable for another HubSpot CMS site.
+
+Replace hardcoded values with `hubspot-cms-sync.config.mjs`:
+
+- Account registry path.
+- Key directory env var.
+- Read-only portal IDs.
+- Known portal IDs for canonicalization.
+- Theme name.
+- Theme roots and files.
+- Content directory.
+- Sync-state directory.
+- Manifest path.
+- Blog slug and template paths.
+- UI-gated prerequisites.
+- Asset host canonicalization policy.
+- Forms desired-state path.
+- CTA inventory behavior.
+- Optional external adapter search paths, if plugin adapters are supported.
+
+Acceptance:
+
+- No `seventh-sense`, `theseventhsense`, `246389711`, or `529456` hardcoded in
+  package source except examples/tests.
+- Tests cover config loading and defaults.
+- Package can run from a fixture project with a different theme name.
+- `READ_ONLY_PORTAL` is replaced by `config.readOnlyPortalIds` membership checks.
+- `KNOWN_PORTALS` is replaced by config-derived known portal IDs, or by a
+  documented discovery rule from accounts + registry.
+- Config loader behavior is tested: missing config, invalid config, missing
+  accounts file, missing key file, and invalid manifest all print remediation
+  and exit non-zero.
+
+---
+
+## Phase 3: Public CLI Surface
+
+Objective: make the tool understandable and safe for normal users.
+
+Add:
+
+- `init`: writes example config and manifest.
+- `doctor`: checks Node version, config, accounts, keys, manifest, and theme paths.
+- `plan`: dry-run pull or push and print a resource summary.
+- `push --dry-run`: resolves refs and preflights without writes.
+- `verify`: orchestrates configured local/remote verification commands.
+- `preview`: optional wrapper around push-to-dev plus verification.
+
+Target command set:
+
+```bash
+hcms init
+hcms doctor
+hcms pull prod
+hcms corpus
+hcms preflight dev
+hcms push dev --dry-run
+hcms push dev --publish
+hcms republish dev --all --blog
+repo verification dev
+```
+
+Guardrails:
+
+- Read-only portal IDs refuse push and preflight-by-default.
+- Any unsupported logical ref fails before network writes.
+- Missing UI-gated prerequisites produce remediation text.
+- `--force-read-only` should not exist.
+- Command outputs that agents/CI need to parse should have a stable JSON mode,
+  e.g. `--json` for `doctor`, `plan`, `preflight`, and `verify`.
+
+### Engine limitations carried into v1
+
+The first public CLI should be honest about known limits:
+
+- CTA and menu producer adapters do not exist yet. Any surviving `@cta:*` or
+  `@menu:*` token fails closed at push preflight.
+- Legacy image host canonicalization is best-effort and may need project policy
+  for non-HubSpot or unrecoverable asset URLs.
+- HubSpot writes are not globally transactional. A transient API failure after
+  earlier writes can leave a partial target state; rerun-to-convergence is the
+  recovery model.
+
+---
+
+## Phase 4: Move Website Repo To The Package
+
+Objective: remove local sync implementation from `../7thsense-website`.
+
+Website repo changes:
+
+1. Add package dependency:
+   ```json
+   "devDependencies": {
+     "hubspot-cms-sync": "file:../hubspot-cms-sync"
+   }
+   ```
+2. Add `hubspot-cms-sync.config.mjs`.
+3. Update `package.json` scripts:
+   ```json
+   {
+     "sync:pull": "hcms pull",
+     "sync:push": "hcms push",
+     "sync:preflight": "hcms preflight",
+     "sync:republish": "hcms republish",
+     "corpus": "hcms corpus"
+   }
+   ```
+4. Delete local unified sync files after parity:
+   - `sync/pull.mjs`
+   - `sync/push.mjs`
+   - `sync/preflight.mjs`
+   - `sync/republish.mjs`
+   - `sync/manifest.mjs`
+   - `sync/cta-inventory.mjs`
+   - `sync/lib/**`
+   - `sync/adapters/**`
+5. Delete legacy scripts:
+   - `sync/blog-sync.mjs`
+   - `sync/cms-pull.mjs`
+   - `sync/forms-sync.mjs`
+   - `sync/page-content.mjs`
+6. Keep only project-local config, content, theme, tests, and docs.
+7. Repoint or remove website unit tests before deleting `sync/**`. Engine tests
+   should have moved to the package; website repo tests should import package
+   exports only if they are validating website-specific integration behavior.
+
+Acceptance in website repo:
+
+```bash
+npm ci
+npm run test:unit
+npm run corpus
+npm run sync:preflight -- dev
+npm run sync:push -- dev --dry-run
+```
+
+This gate is only valid after test ownership is resolved. Do not delete
+`sync/**` while website tests still import `../../sync/...`.
+
+If credentials are present and the operator intends to write:
+
+```bash
+npm run sync:push -- dev --publish
+npm test
+```
+
+---
+
+## Phase 5: CI And PR Gates
+
+Objective: make preview and deploy flows package-owned.
+
+Package should provide reusable CI examples:
+
+- `examples/github-actions/ci.yml`
+- `examples/github-actions/publish.yml`
+- `examples/github-actions/preview.yml`
+
+Website repo should use:
+
+- Unit/corpus checks on every PR.
+- Optional `hcms preview dev --publish --verify` for preview environment.
+- Manual `Publish` workflow for deployment.
+- Environment-scoped `HUBSPOT_PORTAL_KEY`.
+
+PR gates should include:
+
+- `hcms corpus`
+- `hcms push dev --dry-run`
+- `npm run test:unit` or package-provided unit fixtures
+- Playwright fidelity/forms/links checks against the preview URL
+
+---
+
+## Phase 6: npm Publication
+
+Objective: publish as an installable CLI.
+
+Before publication:
+
+- Rename package if needed (`@seventhsense/hubspot-cms-sync` vs `hubspot-cms-sync`).
+- Set `"private": false`.
+- Add `LICENSE`.
+- Add full README.
+- Add fixture tests.
+- Add provenance-capable GitHub release workflow.
+- Add semver policy.
+- Scrub private portal IDs from `examples/` and docs shipped in the npm tarball,
+  or exclude those docs from `package.json#files`.
+- Flip `"private": false`.
+- Bump from `0.0.0` to an intentional prerelease version.
+- Add `prepublishOnly` that runs the real test suite, lint, and `npm pack --dry-run`.
+- Confirm package tarball contents contain no keys, `.sync-state`, private portal
+  IDs, or customer-specific docs.
+
+Release commands:
+
+```bash
+npm pack --dry-run
+npm publish --provenance
+```
+
+---
+
+## Phase 7: Codex Skill Companion
+
+Objective: create a `hubspot-cms-sync` skill that tells Codex how to operate the
+npm CLI safely.
+
+The skill should not duplicate the sync engine. It should:
+
+- Detect whether the npm CLI is installed.
+- Read `hubspot-cms-sync.config.mjs`.
+- Run `hcms doctor`, `hcms corpus`, `hcms preflight`, `hcms push --dry-run`, `hcms push`,
+  and `repo verification`.
+- Interpret common HubSpot errors.
+- Guide PR preview/deployment workflows.
+- Capture screenshots via the consuming repo's Playwright commands.
+
+See [SKILL_DISTRIBUTION.md](./SKILL_DISTRIBUTION.md).