@gradial/aci 0.1.20-preview.3 → 0.1.20

package/templates/common/.agents/skills/aci/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: aci
+description: Onboarding, running builds, validating, and troubleshooting ACI sites. Use when understanding ACI architecture, running CLI commands, diagnosing build errors, or checking project health.
+---
+
+# ACI — Onboarding and Troubleshooting
+
+## How ACI Works
+
+```
+.content/  ──aci build──▶  .aci/compiled/  ──framework build──▶  dist/
+   JSON                      compiled JSON            static HTML
+```
+
+1. You author content as JSON files under `.content/`.
+2. The `aci` CLI compiles contracts (component schemas) and content into
+   `.aci/compiled/`.
+3. Your framework (Astro or Next.js) reads the compiled content at build
+   or render time and produces HTML.
+
+## Contracts vs Runtime
+
+The most important architectural rule: **contracts are separate from
+runtime components**.
+
+| Layer | Location | Imports | Purpose |
+|-------|----------|---------|---------|
+| Contracts | `src/cms/contracts/` | `@gradial/aci`, `zod` only | Component IDs, Zod schemas, image slots, block refs |
+| Runtime | `src/components/` | Framework code, CSS, contract types | Actual UI components (Astro, React) |
+
+The ACI compiler imports only `src/cms/contracts/**`. Contract files must
+never import framework components, CSS, browser globals, or runtime
+modules. Runtime components may import contract types to keep props
+connected to schemas.
+
+## Framework Integration
+
+Each framework uses a packaged SDK adapter for ACI dev/build behavior:
+
+- **Astro**: `withAci()` in `astro.config.mjs`
+- **Next.js**: `withAci()` in `next.config.ts`
+
+These adapters own canonical ACI behavior: content watch/reload, local DAM
+derivative serving at `/.gradial-dam/*`, and asset path rewrites. Do not
+copy site-local middleware for these concerns.
+
+Only Next.js and Astro are supported. SvelteKit support has been removed.
+
+## CLI Commands
+
+All commands run from the site directory (where `.aci.yaml` lives).
+
+| Command | Purpose |
+|---------|---------|
+| `npm run aci:compile` | Compile contract registry. Run after changing contracts. |
+| `npm run content:compile` | Compile content from `.content/` into `.aci/compiled/`. |
+| `npm run aci:validate` | Validate content against schemas without building. |
+| `npm run aci:doctor` | Check project health: config, content, schemas, routes. |
+| `npm run aci:build` | Full build: contracts + content + framework. |
+| `npm run typecheck` | TypeScript type checking. |
+| `npm run build` | Framework build. |
+| `npm run dev` | Start dev server with content hot-reload. |
+
+## Development Workflow
+
+### Start dev server
+
+```bash
+npm install
+npm run aci:compile
+npm run dev
+```
+
+The dev server watches for content changes and re-compiles automatically
+via the framework's ACI adapter. Edit `.content/` files and see changes
+in the browser.
+
+### Full local build
+
+```bash
+npm run aci:compile
+npm run content:compile
+npm run typecheck
+npm run build
+```
+
+### Content editing loop
+
+1. Edit `.content/pages/{slug}/_index.json` or `.content/config/site.json`.
+2. Run `npm run aci:validate` to check content is valid.
+3. Run `npm run content:compile` to compile content.
+4. Run `npm run build` to build the site.
+5. Check the output for your changes.
+
+## Test Order (Fastest to Slowest)
+
+1. `npm run aci:validate` — content validation
+2. `npm run aci:compile` — contract compile
+3. `npm run typecheck` — TypeScript
+4. `npm run content:compile` — content compile
+5. `npm run build` — framework build
+6. `npm run build:storybook` — Storybook (if configured)
+
+## Troubleshooting
+
+### "Unknown component" error during content compile
+
+The content JSON references a `component` name that is not in the contract
+barrel (`src/cms/contracts/components/index.ts`). Add the contract or fix
+the content.
+
+### Contract compile fails with CSS/framework import error
+
+A contract file is importing runtime code. Contract files may only import
+`@gradial/aci`, `zod`, and shared schema helpers. Move the import to a
+runtime component file.
+
+### Images not loading in dev
+
+Check that `ACI_CONTENT_ROOT` is set and the framework adapter is wired.
+Compiled DAM derivatives should be served at `/.gradial-dam/*`. Verify:
+
+```bash
+curl -I http://localhost:4321/.gradial-dam/derivatives/sha256/.../image.webp
+```
+
+Expected: `200` with `Content-Type: image/webp` (or similar image type).
+
+### `aci` command not found
+
+The CLI is provided by `@gradial/aci`. Run `npm install` first. The npm
+scripts use `node ./node_modules/@gradial/aci/bin/aci.js` to find it
+locally.
+
+### Content value not surviving compile/build
+
+If a value doesn't survive the round-trip, check:
+- The field is in the contract schema (or it will be stripped).
+- The field name matches between content JSON and contract schema.
+- The field type matches (string vs number vs object).
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `.aci.yaml` | ACI config: contract paths, framework, routes, capabilities |
+| `src/cms/contracts/components/index.ts` | Component contract barrel |
+| `src/cms/contracts/layouts/index.ts` | Layout contract barrel |
+| `src/cms/registry.ts` | Component registry (`createRegistry` with `[contract, component]` tuples) |
+| `src/components/` | Runtime component implementations |
+| `src/design-system/` | Design tokens and global styles |
+| `.content/` | Local content for development |
+
+## Deep Dive: Authoring
+
+Read `.agents/skills/authoring/SKILL.md` for content authoring, component
+development, design tokens, and the full contract/runtime split.
+
+## Deep Dive: Migration
+
+Read `.agents/skills/migration/SKILL.md` for reverse-engineering a live
+site or design into ACI.