@once-ui-system/core 1.7.12 → 1.8.0

package/AGENTS.md

@@ -0,0 +1,53 @@
+# @once-ui-system/core — agent harness
+
+This package ships an agent-first codegen harness under `ai/`. Use it when **writing Once UI code**, not full MDX documentation pages.
+
+## Entry point
+
+```
+@once-ui-system/core/ai/manifest.json
+```
+
+Or from disk:
+
+```
+node_modules/@once-ui-system/core/ai/manifest.json
+```
+
+## Bootstrap workflow
+
+1. Read `ai/manifest.json`
+2. Load bootstrap files: `ai/rules.compact.md` + `ai/catalog.json` (~6KB)
+3. Match intent via `ai/tasks/index.json` → e.g. `ai/tasks/pricing.json`
+4. Fetch component slices listed in the task bundle (`ai/components/*.json`)
+5. Read the gold example referenced by the task; for production fidelity, read Pro blocks from `ai/examples/blocks/manifest.json`
+6. Validate generated code: `npx once-ui-validate-ai-code path/to/file.tsx`
+
+## npm exports
+
+```tsx
+// Readable paths (version-pinned to your install)
+import manifest from '@once-ui-system/core/ai/manifest.json';
+```
+
+```bash
+# One-time project setup (writes AGENTS.md + Cursor rule in consumer app)
+npx once-ui-init-agent
+```
+
+## Remote fallback
+
+If you cannot read `node_modules`, use the docs host (may not match your installed version exactly):
+
+- https://docs.once-ui.com/ai/manifest.json
+- https://docs.once-ui.com/ai/rules.compact.md
+- https://docs.once-ui.com/once-ui/ai-coding
+
+## Key rules (summary)
+
+- Use `Column` / `Row`, not `Flex` unless direction changes at breakpoints
+- Use `fill`, not `fillWidth fillHeight`; use `center`, not `horizontal="center" vertical="center"`
+- Static panels: `Column background="surface" border="neutral-alpha-weak" radius="l" padding="24"`
+- `Card` is interactive only (`href` or `onClick`)
+
+Full rules: `@once-ui-system/core/ai/rules.compact.md`

package/README.md

@@ -35,6 +35,33 @@ Learn how to set up and build with Once UI at [docs.once-ui.com](https://docs.on
 npm install @once-ui-system/core
 ```
 
+## AI codegen harness
+
+This package includes an agent-first harness under `ai/` for generating Once UI code with minimal context (~6–10KB per task).
+
+| Resource | Path |
+|----------|------|
+| Entry point | `@once-ui-system/core/ai/manifest.json` |
+| Compact rules | `@once-ui-system/core/ai/rules.compact.md` |
+| Component catalog | `@once-ui-system/core/ai/catalog.json` |
+| Task bundles | `@once-ui-system/core/ai/tasks/index.json` |
+
+**One-time setup in your app** (writes project `AGENTS.md` + Cursor rule):
+
+```bash
+npx once-ui-init-agent
+```
+
+**Validate generated code:**
+
+```bash
+npx once-ui-validate-ai-code src/app/page.tsx
+```
+
+Full guide: [docs.once-ui.com/once-ui/ai-coding](https://docs.once-ui.com/once-ui/ai-coding)
+
+Machine-readable discovery: see the `onceUi` field in this package's `package.json`.
+
 ## Authors
 
 Built and maintained by [**Lorant One**](https://lorant.one).

package/agent/once-ui-codegen.mdc

@@ -0,0 +1,27 @@
+---
+description: Load Once UI agent harness before generating UI code
+globs: "**/*.{tsx,jsx}"
+alwaysApply: false
+---
+
+# Once UI codegen harness
+
+Before generating or editing Once UI UI code in this project:
+
+1. Read `@once-ui-system/core/ai/manifest.json` (or `node_modules/@once-ui-system/core/ai/manifest.json`)
+2. Load bootstrap files from the manifest: `rules.compact.md` + `catalog.json`
+3. Resolve intent via `ai/tasks/index.json` → fetch the matching task bundle
+4. Fetch only the component slices listed in that task (`ai/components/*.json`)
+5. Read the task's gold example; for production layouts, read matching Pro blocks from `ai/examples/blocks/manifest.json`
+6. Validate output: `npx once-ui-validate-ai-code path/to/file.tsx`
+
+## Do not
+
+- Use full documentation MDX pages for codegen (too large; use the harness)
+- Use `Flex direction="column"` when `Column` works; same for `Row`
+- Use `fillWidth fillHeight` when `fill` works
+- Use `Card` for static panels (use the surface recipe on `Column`)
+
+## Remote fallback
+
+https://docs.once-ui.com/ai/manifest.json