Carto Frontsite AI Builder

Codex-first orchestration for creating complete Astro Carto Frontsites from natural language. The Builder guides AI work, while its pinned Carto Kit runtime dependency is the deterministic owner of connection, public Contract Bundles, verification, diagnostics, deployment adaptation, and secrets.

Current v0 capability

The lightweight CLI downloads a pinned, versioned Codex Skill Bundle from an immutable GitHub Release, verifies its SHA-256 and per-file manifest, caches it, then deterministically installs the Codex adapter into the project's .agents/skills discovery directory:

npx carto-frontsite-ai init --ai codex
# or during local development
node dist/src/cli.js init --ai codex --target /path/to/project

Use --offline to install only from an already verified cache and --json for one JSON result on stdout. Repeated installation is idempotent. A schema-v4 record containing bundle provenance, all managed Skill identities, and file SHA-256 hashes is written to .codex/carto-frontsite-ai.json; modified or untracked files in the managed Skill directories cause a conflict and are not overwritten. Unrelated user-owned Skills are preserved. Installations made by CLI 0.0.8 or earlier under .codex/skills are migrated automatically only when their contents still match the managed installation record.

Carto Kit is installed transitively at the version pinned by carto-frontsite-ai; users do not need a separate global CLI installation. The installer records the package-owned CLI entrypoint so the Skill can invoke it after the npx command exits. A compatible global carto-kit or carto remains a fallback for older installations.

The verified Bundle installs three separate Skills: $carto-frontsite-builder for Foundation projects, $carto-frontsite-starter for creating and branding an official Starter in the current workspace, and $carto-frontsite-rebrand for transforming an existing Starter. After installation, the CLI presents all three routes without preselecting one. Each selected Skill performs its own capability checks. The same neutral handoff is returned as structured nextSteps in --json output.

The installed Skill defines the full flow: capability check, progressive onboarding, initialization from a pinned and SHA-256-verified Carto Frontsite Foundation Release, a confirmed build brief, browser-mediated Carto connection, public Contract Bundle use, direct reference-driven brand assets without a concept-selection pause, complete zero/one/many-product presentation with stable direct checkout, and generate → verify → repair → verify quality gates.

Cross-Skill direct implementation, live-preview iteration, mobile-first, React component-boundary, and maintainability standards are authored once under templates/shared/carto-frontsite-standards. Bundle construction embeds the versioned standards into every Skill and rejects local shadow copies, preventing Builder, Starter creation, and Starter rebranding workflows from drifting apart.

Foundation initialization records protected and theme-only integrity baselines; final verification blocks unauthorized core changes or reduced transaction behavior instead of relying on prompt compliance.

Important limitation

End-to-end use requires a compatible Carto Kit plus a reachable Carto Private device-authorization and Contract Bundle service. The installed capability check blocks explicitly when required Carto Kit commands are missing. Verification remains blocked until the generated storefront provides real functional and desktop/mobile visual verification scripts. This project does not fake those operations, handle tokens, or inspect Carto Private implementation.

Codex is the only supported host. init installs the Skills; it does not itself generate a site. It downloads only the fixed github.com/miguba/carto-frontsite-ai Release asset declared by the installed CLI. Mutable Git branches and arbitrary runtime URLs are rejected.

Development

Requires Node.js 20+. The repository includes a self-contained Skill metadata validator; maintainers can additionally run Codex's upstream quick_validate.py when its Python dependencies are available.

npm install
npm run build
npm test
npm run typecheck
npm run validate:skill
npm run bundle:build
# all checks
npm run check

Skill Bundle release

Skill content and visual references are versioned independently from the npm CLI. Build and inspect the deterministic archive, commit its descriptor, then publish the matching immutable tag:

npm run bundle:build
git tag -a skill-v0.4.0 -m "Release Skill Bundle v0.4.0"
git push origin skill-v0.4.0

The tag creates a GitHub Release containing the archive and checksum. The npm release is allowed only after npm run bundle:verify-remote verifies that exact remote asset.

npm release

Releases use an exact-version dry run followed by an immutable semantic-version tag. The tag triggers GitHub Actions to publish through npm Trusted Publishing; ordinary branch pushes never publish.

Because npm only allows Trusted Publisher configuration for an existing package, the first registry release uses the documented one-time interactive bootstrap.

npm run release:npm -- 0.0.2 --dry-run
git tag -a v0.0.2 -m "Release v0.0.2"
git push origin v0.0.2

See docs/npm-release.md for the complete maintainer flow. The bundled $carto-frontsite-ai-release Skill can execute and verify it.

Product behavior is specified in docs/product-spec-v0.md; boundaries and component ownership are in docs/architecture-v0.md. Persistent agent rules are in AGENTS.md.