gesso init
Add Gesso and its agent support to an existing Next.js project without editing application entry files.
Prerequisites and syntax
Run from a Next.js project root containing a readable, valid package.json with next declared:
pnpm dlx @acromedia/gesso-cli init
After the CLI is installed, rerun with:
pnpm gesso init
The command rejects missing or malformed manifests, non-Next.js projects, and misplaced Gesso dependencies before planned project changes. Put @acromedia/gesso in dependencies and @acromedia/gesso-cli in devDependencies.
Changes made
When absent, init adds the exact bundled-documentation target version of @acromedia/gesso to dependencies and the exact running CLI version of @acromedia/gesso-cli to devDependencies. This rewrites package.json with two-space JSON formatting and prints pnpm install guidance.
If Gesso theme wiring is not detected, it attempts to create src/theme.ts. For an App Router root layout it also attempts to create a sibling providers.tsx client boundary. It never edits the root layout: the output provides the import, <Providers> wrapper, and Emotion insertion-point steps to apply manually.
For a Pages Router custom App, no separate providers file is needed. The command prints the ThemeProvider, CssBaseline, and theme wiring to add manually to _app. If no supported entry file is found, it asks you to wire providers manually.
Generated theme and provider files use create-only writes and are skipped if the path already exists; existing files are not overwritten. If provider wiring is already detected, theme/provider generation is skipped.
Agent instructions and skills
AGENTS.md and CLAUDE.md are an all-or-none pair. They are created only when neither exists. If either path already exists, both are left unchanged.
The command attempts to install the bundled gesso-react skill in each supported skill directory and reports each outcome. Rerunning init refreshes an Acromedia-owned skill when its version or content is stale and skips it when current. A skill with another metadata.author is treated as user-owned and left unchanged. Escaping skill paths are reported and skipped; malformed, blocking, or unreadable paths report repair guidance. One failed path does not fail init when another path installs the skill or is safely skipped; only failure in every supported skill directory makes the command fail.
The command uses guarded writes and rollback for its planned manifest and generated-file changes, but do not treat it as an unconditional filesystem-containment or all-or-nothing guarantee. Skill installation occurs after the other changes and can fail separately. Review reported paths and recoveries, especially in projects that use symlinks.
Existing and no-op cases
Existing dependency declarations are not upgraded or moved automatically. Existing generated-file paths and instruction files are skipped. If dependencies, generated files, instruction files, and both skills already need no changes, the command reports a no-op. It can still print manual wiring guidance.
After applying any printed App or Pages Router wiring steps, verify the result:
pnpm install
pnpm gesso health
See registry authentication if dependency installation cannot download Acromedia packages.