camox 0.58.1 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camox",
-  "version": "0.58.1",
+  "version": "0.59.0",
   "license": "MIT",
   "bin": {
     "camox": "./bin/camox.mjs"
@@ -135,9 +135,9 @@
     "takumi-js": "^2.18.1",
     "unhead": "^3.4.3",
     "zod": "^4.6.7",
-    "@camox/cli": "0.58.1",
-    "@camox/ui": "0.58.1",
-    "@camox/api-contract": "0.58.1"
+    "@camox/cli": "0.59.0",
+    "@camox/api-contract": "0.59.0",
+    "@camox/ui": "0.59.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.3.0",

package/skills/camox/references/block-definitions.md

@@ -156,7 +156,7 @@ icon: field.icon({ default: "lucide:zap", title: "Icon" })
 
 Icons are decorative unless given `aria-label` or `aria-labelledby`. Clicking an icon in preview opens the searchable collection picker. Values remain namespaced strings; editors cannot select another collection or an empty value.
 
-Run `pnpm exec camox typegen` **before TypeScript checking in CI**, for example `camox typegen && tsc --noEmit`. This resolves Vite config without starting a server or requiring Camox login. It generates `src/camox/icons.gen.d.ts`; ensure your tsconfig includes it. Dev and build regenerate it automatically. Generation requires network access to the pinned Iconify snapshot.
+Run `pnpm exec camox typegen` **before TypeScript checking in CI**, for example `camox typegen && tsc --noEmit`. This resolves Vite config without starting a server. It generates `src/camox/icons.gen.d.ts`; ensure your tsconfig includes it. Dev and build regenerate it automatically. Generation requires network access to the pinned Iconify snapshot.
 
 Camox resolves selected SVGs from that same versioned snapshot and serves them through its API. Server rendering preloads selected/default SVGs into hydration data; no visitor requests to Iconify and no rebuild is needed when content changes. Only the editor fetches collection metadata and picker previews, not a whole SVG catalog.
 

package/dist/features/vite/publishSeededContent.js

@@ -1,30 +0,0 @@
-//#region src/features/vite/publishSeededContent.ts
-/**
-* Publishes the content dev mode seeded into the development draft, so a fresh database starts
-* with it on Live and the draft only holds the developer's own changes. Failures are warnings:
-* the content stays in the draft, where it can still be published by hand.
-*/
-async function publishSeededContent(options) {
-	const { client, projectUuid, logger } = options;
-	try {
-		const project = await client.projects.getByUuid({ projectUuid });
-		const preview = await client.drafts.previewPublish({ projectId: project.id });
-		if (preview.changes.length === 0) return;
-		if (preview.blockers.length > 0) {
-			const blockers = preview.blockers.map((blocker) => blocker.message).join("; ");
-			logger.warn(`[camox] Seeded content stays in your development draft; publishing is blocked: ${blockers}`, { timestamp: true });
-			return;
-		}
-		await client.drafts.publish({
-			projectId: project.id,
-			token: preview.token,
-			publishAnyway: true
-		});
-		logger.info(`[camox] Published ${preview.changes.length} seeded change${preview.changes.length === 1 ? "" : "s"} to Live`, { timestamp: true });
-	} catch (error) {
-		logger.warn(`[camox] Publishing seeded content failed: ${String(error)}`, { timestamp: true });
-	}
-}
-
-//#endregion
-export { publishSeededContent };

package/skills/camox-cli/SKILL.md

@@ -1,15 +0,0 @@
----
-name: camox-cli
-description: Use when running the Camox CLI to read or change a Camox project's Pages, Blocks, content, layout assignments or metadata, to preview a change, or to publish or delete the development draft.
----
-
-# Camox CLI
-
-For any CLI operation, first read [CLI common guidance](references/cli-common.md), then only the relevant command reference:
-
-- Pages, metadata, layout assignments, Blocks, content, or ordering:
-  [CLI Content](references/cli-content.md).
-- Where the CLI writes, publishing or deleting the development draft, or its status:
-  [CLI Publishing](references/cli-publishing.md).
-
-The CLI changes content, never code. To create or change Block or Layout Definitions first, follow the [`camox` skill](../camox/SKILL.md), then wait for the dev server to discover the new definition before placing or assigning it.

package/skills/camox-cli/references/cli-common.md

@@ -1,58 +0,0 @@
-# Camox CLI common guidance
-
-Use the Camox CLI for CRUD operations on Pages, Blocks, Layout assignments, and metadata. Follow the [`camox` skill](../../camox/SKILL.md) instead when changing Block Definitions or Layout Definitions in `src/blocks/` or `src/layouts/`.
-
-If a change should be visible without a code deployment, it is usually a CLI content operation. Some requests require both code and CLI work: define the new type first, wait for the dev server to discover it, then create or assign its content through the CLI.
-
-## Run the installed CLI
-
-Detect the package manager from the closest `package.json#packageManager` or lockfile, then use its local Camox binary:
-
-| Package manager | Command      |
-| --------------- | ------------ |
-| pnpm            | `pnpm camox` |
-| Bun             | `bunx camox` |
-| npm             | `npx camox`  |
-
-In the examples below, replace `{{CAMOX_CMD}}` with that command.
-
-## Discover the current command surface
-
-Before a write, verify the relevant subcommand's `--help` unless already checked for the installed version in this session:
-
-```sh
-{{CAMOX_CMD}} pages create --help
-```
-
-Use root or group help only to discover unfamiliar commands. Reuse verified help within the session; recheck if the installed version changes. Installed help overrides these examples—do not guess commands or flags.
-
-## Dev-first workflow
-
-Every command reads and writes the current developer's development draft, never Live. Make content changes there and summarize them for review; they reach Live only when the draft is published (see [CLI Publishing](cli-publishing.md)). Don't publish unless the user asks.
-
-- If a command fails with "run the site locally first", the development draft doesn't exist yet: the dev server creates it on its first sync after `camox login`.
-
-## Verify changes in a browser
-
-CLI credentials and browser sessions are separate. A fresh browser isn't signed in, even when CLI writes succeeded.
-
-1. Start the app's dev server and check `{{CAMOX_CMD}} preview --help`.
-2. Generate a handoff for the page you changed:
-   `{{CAMOX_CMD}} preview --url http://localhost:3000/about --json`
-   (Use the actual port; add `--cwd apps/site` in a monorepo.)
-3. Open the returned `url` in your verification browser, not a separate default browser.
-4. Wait for `[data-camox-preview="ready"]`. Its text identifies the project and the development draft; the server has loaded authenticated content. `[data-camox-preview="error"]` means verification failed, not that the write failed.
-5. Inspect the changed content.
-
-The URL is a single-use sign-in credential valid for three minutes. Do not share, commit, or include it in reports. Generate a new URL if expired or consumed. Only loopback HTTP(S) destinations are supported; previewing a deployed site is intentionally unsupported. The SDK must support this handoff: if the ready marker never appears, check the installed SDK version rather than assuming the write failed. A project or backend mismatch requires correcting `--cwd` or `--url` (or restarting a dev server running under another account).
-
-## Write grounded content
-
-Before writing Content:
-
-1. Inspect existing Pages, Blocks, and Block type descriptions to learn the site's voice, positioning, names, and factual claims.
-2. Use facts and copy supplied by the user. Research external facts with an available retrieval tool; ask when a material fact cannot be established.
-3. Never invent filler copy, statistics, testimonials, company details, asset filenames, or URLs.
-4. Leave `File`, `Embed`, or `Image` values empty when no real asset is available, and tell the user what remains to be supplied.
-
-After writes, report the affected Pages and Blocks and the notable content or structural changes.

package/skills/camox-cli/references/cli-content.md

@@ -1,181 +0,0 @@
-# Managing Pages and Blocks with the Camox CLI
-
-Read [cli-common.md](cli-common.md) first for `{{CAMOX_CMD}}`, help verification, and the dev-first workflow.
-
-Use these commands for Pages, metadata, Layout assignments, Blocks and their Content, and review. To create or change Block or Layout Definitions, follow the [`camox` skill](../../camox/SKILL.md).
-
-## Pages
-
-### Create a Page with an existing Layout
-
-```sh
-{{CAMOX_CMD}} layouts list
-{{CAMOX_CMD}} pages create --path-segment about --layout-id default
-```
-
-`--layout-id` takes a Layout's name, the `layoutId` listed by `layouts list`.
-
-Use `--parent-page-id <ID>` to nest the Page under another Page.
-
-### Read and edit SEO metadata
-
-```sh
-{{CAMOX_CMD}} pages get --path /about
-{{CAMOX_CMD}} pages set-seo --path /about --meta-title "About us" --meta-description "Meet the team."
-{{CAMOX_CMD}} pages set-seo --id <PAGE_UUID> --meta-description ""
-{{CAMOX_CMD}} pages set-seo --id <PAGE_UUID> --ai-seo on
-{{CAMOX_CMD}} pages set-seo --id <PAGE_UUID> --ai-seo off
-```
-
-`set-seo` accepts exactly one of `--id` or `--path` and requires at least one of
-`--meta-title`, `--meta-description` or `--ai-seo`. The meta title and
-description are one group: writing either field makes both manual, keeping the
-current value of the other, and cannot be combined with `--ai-seo on`.
-`--ai-seo off` keeps current metadata as manual; `--ai-seo on` schedules
-asynchronous generation, so read the Page again to inspect results. An empty
-meta title blocks publishing.
-
-Metadata edits apply right away in the development draft. Read metadata
-with `pages get`.
-
-## Blocks
-
-### Inspect before changing
-
-Look up the Page before creating or moving Blocks so you have its `id`, current Blocks, and any sibling ids. Describe the Block type before constructing Content:
-
-```sh
-{{CAMOX_CMD}} pages get --path /
-{{CAMOX_CMD}} blocks describe --type hero
-```
-
-### Find shared navigation and footer Blocks
-
-`pages get` returns page-owned Blocks, not the Layout's shared shell. Inspect
-the Layout to discover navigation, footer, and other layout-owned block IDs:
-
-```sh
-{{CAMOX_CMD}} layouts list
-{{CAMOX_CMD}} layouts get --layout-id default
-{{CAMOX_CMD}} blocks get --id <BLOCK_UUID>
-{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{"title": "Updated title"}'
-```
-
-Pass the Layout's name, the `layoutId` from `layouts list` (also the Page's
-`layoutId`), to `layouts get --layout-id`. The response
-includes `blocks` with `id`, `type`, `slot`, and Content, plus
-`layout.beforeBlockIds` and `layout.afterBlockIds`. Pass a Block's `id` to
-`blocks get` and `blocks edit`; do not use the Layout ID or Block type.
-Inspect the Block's schema and current Content before editing, and preserve
-repeatable items as described below.
-
-Keep `--project` and `--cwd` consistent across the discovery and editing
-commands. Shared shell edits affect every Page using that Layout,
-and synced Block types can share Content across Layouts.
-
-### Create and position a Block
-
-```sh
-{{CAMOX_CMD}} blocks create --page-id <PAGE_UUID> --type hero --content '{...}' --position first
-```
-
-Creation initializes omitted Content and Settings fields from the Block definition's defaults, including when `--content '{}'` is supplied. Explicit values are not replaced by defaults and must satisfy the field's JSON Schema; defaults do not merge into a supplied Link object. Omitted Repeaters initialize their default item count (or minimum count) with item defaults. Supplied arrays use exactly those items and must satisfy `minItems`/`maxItems`; `[]` is accepted only when the minimum allows it. Asset placeholders are not stored. Existing synced Block data still takes precedence for synced types.
-
-Content and Settings writes are validated server-side against the development draft's definitions before mutation. Validation errors include field paths. String fields contain Markdown strings (not rich-text JSON objects); Embed fields contain strings matching their pattern. Assets use managed `{ "_fileId": "<file UUIDv7>" }` references, with asset lists stored as arrays of references. Asset normalization drops hydrated URL metadata and converts placeholders to null.
-
-Updates validate only submitted fields, so unrelated historical invalid values do not prevent an edit. New records validate after defaults are applied. Unknown properties follow the schema's `additionalProperties` policy (allowed when unspecified); missing definitions retain legacy permissive behavior. Saved snapshots are not retroactively migrated or revalidated when restored.
-
-Supply reference-specific copy, links, assets, and items directly as instance Content. Definition defaults should remain neutral, reusable examples—not a way to populate a reference site.
-
-`blocks create` and `blocks move` accept the same positioning flags. Pass at most one:
-
-| Flag                      | Meaning                                         |
-| ------------------------- | ----------------------------------------------- |
-| `--position first`        | Put the Block first.                            |
-| `--position last`         | Put the Block last; this is the create default. |
-| `--after-id <ID>`         | Put it immediately after a sibling Block.       |
-| `--before-id <ID>`        | Put it immediately before a sibling Block.      |
-| `--after-position <KEY>`  | Insert after a known fractional-index key.      |
-| `--before-position <KEY>` | Insert before a known fractional-index key.     |
-
-Prefer `--position`, `--after-id`, and `--before-id`. A move requires one positioning flag.
-
-### Edit Block Content
-
-Content patches merge ordinary fields, so send only fields that should change:
-
-```sh
-{{CAMOX_CMD}} pages get --path /pricing
-{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{"headline": "New headline"}'
-```
-
-### Set string fields from files
-
-Use `--field-file <NAME>=<PATH>` on `blocks create` and `blocks edit` to set a top-level string field to a file's raw contents, without escaping it into JSON. It suits long Markdown and [Artifact](../../camox/references/artifacts.md) sources. Repeat the flag to set several fields. It merges with `--content`; when both set the same field, the file wins. On `blocks create`, pass `--content`, `--field-file`, or both.
-
-```sh
-{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{"title": "Orbit"}' --field-file source=./orbit.html
-```
-
-Every file is read before anything is written, so a missing or unreadable file fails the command without changing anything.
-
-To build an Artifact source, loop until it renders correctly:
-
-1. Write the source to a local file, such as `./orbit.html`.
-2. Push it with `blocks edit --id <ID> --field-file <NAME>=./orbit.html` (or `blocks create` for a new Block).
-3. Check the rendered page with `{{CAMOX_CMD}} preview`, following [CLI common guidance](cli-common.md).
-4. Edit the file and push again.
-
-### Edit repeatable Content safely
-
-A repeatable field's array is replacement-shaped: omitting an existing item deletes it and cascades to its file references, settings, and nested items. Fetch the Block, preserve every existing item with `_itemId`, and add changes only to the intended entries:
-
-```sh
-{{CAMOX_CMD}} blocks get --id <BLOCK_UUID>
-
-{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{
-  "items": [
-    {"_itemId": "<ITEM_UUID_1>"},
-    {"_itemId": "<ITEM_UUID_2>", "answer": "Updated answer."},
-    {"_itemId": "<ITEM_UUID_3>"}
-  ]
-}'
-```
-
-The response's `repeatableItems` contains each item's `id`, `fieldName`, `parentItemId`, and Content. Use the same `_itemId` pattern recursively for nested repeatables. Fetch multiple Blocks together when useful:
-
-```sh
-{{CAMOX_CMD}} blocks get-many --id <BLOCK_UUID> --id <BLOCK_UUID> --id <BLOCK_UUID>
-```
-
-`blocks get-many` returns the same bundle shape as `blocks get`, in requested-id order.
-
-## Locales
-
-```sh
-{{CAMOX_CMD}} locales list
-{{CAMOX_CMD}} locales add --tag de
-{{CAMOX_CMD}} pages get --path /pricing --locale de
-{{CAMOX_CMD}} blocks edit --id <BLOCK_UUID> --content '{"title":"Hallo"}' --locale de
-{{CAMOX_CMD}} locales remove --tag de
-```
-
-Locales are content: adding or removing one changes the development draft, and
-publishing puts the change on Live. Adding a locale gives every Page, Block,
-repeatable item, synced Block and collection record a copy in it, keeping its
-id, which Camox translates in the background. Every later change to the default
-locale is translated into every other locale of the draft; edits made with
-`--locale` aren't translated anywhere. `pages`,
-`blocks edit/get/create/move/delete` and `layouts get` take `--locale <TAG>` to
-read or write that copy; without it they act on the default locale. Removing a locale deletes its content from Live for good once
-published. `locales set-default-tag --tag en-GB` corrects the default locale's
-tag, only while it's the only locale.
-
-## Review
-
-```sh
-{{CAMOX_CMD}} pages get --path /pricing
-{{CAMOX_CMD}} blocks get --id <BLOCK_UUID>
-```
-
-Reads return the content of the development draft, which shows Live wherever it changes nothing. Every edit lands in the development draft right away and reaches Live only when the draft is published (see [CLI Publishing](cli-publishing.md)).

package/skills/camox-cli/references/cli-publishing.md

@@ -1,26 +0,0 @@
-# Publishing with the Camox CLI
-
-Read [cli-common.md](cli-common.md) first for `{{CAMOX_CMD}}`, help verification, and the dev-first workflow.
-
-Every command works in the current developer's development draft. Its changes reach Live, the public site, only when the draft is published. Agents in parallel worktrees share their developer's development draft, so publishing or deleting it covers all of their changes.
-
-Don't publish or delete unless the user asks you to.
-
-```sh
-{{CAMOX_CMD}} status                   # whether the development draft exists, and how many changes it holds
-{{CAMOX_CMD}} publish                  # what publishing would do, with a token
-{{CAMOX_CMD}} publish --confirm TOKEN  # publish the whole draft to Live
-{{CAMOX_CMD}} delete --yes            # empty the development draft; Live is untouched
-```
-
-`publish` lists, in order:
-
-- **Blockers**: problems to fix in the draft before it can be published, such as an empty required reference or a page without a meta title. Definitions that differ from Live's are blockers too: local code changed a block, layout, or collection, and only a release can ship it to Live. Don't try to fix those through content; tell the user a release is needed.
-- **Conflicts**: content Live changed or deleted since the draft changed it, with who published it and when. Publishing overwrites Live's version.
-- **Lost changes**: changes publishing drops because what they belong to is gone.
-- **Warnings**: the same problems already on Live. They don't block.
-- **Changes**: everything the draft creates, changes, or deletes.
-
-Show the user the list, especially conflicts and lost changes, and get their confirmation before passing the token to `publish --confirm`. If Live changed since the list was printed, nothing is published: the command prints the new list with a new token and fails with `CONFLICTS_CHANGED`. Review the new list with the user before confirming again.
-
-After publishing, the development draft stays open and empty. `delete` empties it without publishing and can't be undone; it requires `--yes` when not run in a terminal.