feat: release Fulldev UI 0.10 component refresh

.agents/skills/fulldev/SKILL.md

@@ -5,185 +5,149 @@ description: Guides Fulldev client projects using Astro, Fulldev UI, content/sch
 
 # Fulldev
 
-Fulldev projects are content-driven Astro sites that use Fulldev UI components
-and blocks through the shadcn-compatible `@fulldev` registry.
-
-This skill is for using Fulldev in client projects. If the current repository
-has its own `AGENTS.md`, contributing guide, or project instructions, those
-local instructions own repo-specific workflow.
-
-If you encounter problems with Fulldev UI, discover missing guidance, or see
-reusable improvements while using this skill, ask the user whether the agent should
-create a pull request for the Fulldev UI library so the improvement can be
-shared back with future contributors and agents. Use the Fulldev UI
-contributing guide for that workflow:
-https://github.com/fulldotdev/ui/blob/main/CONTRIBUTING.md
+Fulldev projects are content-driven Astro sites that use Fulldev UI components through the shadcn-compatible `@fulldev` registry. This skill is for using Fulldev in client projects, not for maintaining the Fulldev UI registry itself.
 
 ## Project Model
 
+Inspect the current repo before enforcing conventions. Fulldev architecture is the target for client projects, but do not silently migrate an existing different architecture.
+
 Preferred page flow:
 
 ```text
 content frontmatter/body -> schema validation -> layout orchestration -> components/blocks
 ```
 
-Content owns authored copy and semantic configuration. Schemas own contracts.
-Layouts own page orchestration. Components and blocks own DOM, behavior,
-accessibility, styling, and implementation details.
+Before changing core doctrine around content/schema/layout separation, layout-owned orchestration, component/block boundaries, or Fulldev UI usage, surface the tradeoff first.
 
-Inspect the current project before enforcing conventions. Fulldev architecture
-is the target for client projects, but do not silently migrate an existing
-different architecture.
+## Principles
 
-## Core Rules
+1. **Preserve ownership boundaries.** Content owns authored copy and semantic configuration; schemas own contracts; layouts own page orchestration; components and blocks own DOM, behavior, accessibility, styling, and implementation details.
+2. **Keep routes and shell boring.** `src/pages/[...page].astro` stays a handoff route, `src/components/layout-renderer.astro` stays generic, and `src/layouts/base.astro` stays shell-only.
+3. **Install before inventing.** Prefer existing `@fulldev` components through the shadcn CLI before creating local reusable UI.
+4. **Compose locally when needed.** Project-specific components and blocks are fine, but they are local application code, not Fulldev registry items.
+5. **Keep the feedback loop light.** During development, prefer a running dev server and occasional log checks. Save full build/check validation for release prep or clearly risky changes.
 
-- Routes stay thin and hand work to generic rendering or layouts.
-- Shared base layouts stay shell-only.
-- Page orchestration belongs in layouts.
-- Content must not contain raw Astro components, imported icons, SVG/HTML,
-  Tailwind class strings, or DOM details.
-- Content-owned icons are plain names rendered through a project icon component.
-- Globals are for cross-page site data, not page-specific block data.
-- Components and blocks receive data through props and slots.
-- Reusable blocks stay schema-agnostic and do not import content collections,
-  page schemas, layouts, routes, or other private page architecture.
+## Critical Rules
 
-## Fulldev UI Usage
+These rules are always enforced. Load the linked file for detailed examples and edge cases.
 
-Install Fulldev UI through shadcn-compatible tooling. Do not invent a `fulldev`
-CLI command unless the project actually provides one.
+### Source Ownership -> [source-ownership.md](./rules/source-ownership.md)
 
-Use the project package runner equivalent of:
+- Page flow is `content frontmatter/body -> schema validation -> layout orchestration -> block/component props`.
+- Content cannot contain raw Astro components, imported icons, SVG/HTML, Tailwind class strings, or DOM details.
+- Content-owned icons are plain names rendered through `src/components/ui/icon`.
+- Globals are for cross-page locale-aware site data, not page-specific block data.
 
-```bash
-npx shadcn@latest add @fulldev/<name>
-```
+### Layouts -> [layouts.md](./rules/layouts.md)
 
-Prefer existing `@fulldev` components and blocks before creating local reusable
-UI or complete page sections. Read installed source when behavior or API is
-unclear.
+- Routes stay thin.
+- `layout-renderer.astro` stays generic.
+- Page orchestration belongs only in `src/layouts`.
+- `base.astro` is shared shell only.
+- Layout props use `{ global, page }`, plus required `headings` only when used.
 
-## Components
+### Components -> [components.md](./rules/components.md)
 
-Reusable UI components commonly live in `src/components/ui/<component-name>/`,
-unless the project has a different established convention.
+- UI components live in `src/components/ui/<component-name>/`.
+- Use `type Props`, destructure `Astro.props` once, and keep Astro frontmatter contracts obvious.
+- Use native attribute types, `class: className`, `props`, and `cn(...)`.
+- Prefer installing existing `@fulldev` components before creating local reusable UI.
+- Fulldev components use shadcn-compatible installation, but avoid duplicating the whole `shadcn` skill here.
 
-For Astro component frontmatter:
+### Blocks -> [blocks.md](./rules/blocks.md)
 
-- Use `type Props`.
-- Destructure `Astro.props` once near the top.
-- Destructure `class` as `class: className`.
-- Name pass-through props `props`.
-- Merge classes with the project's class helper, commonly `cn(...)`.
-- Keep content-specific data out of generic UI primitives.
+- Blocks are project compositions that receive data through props and slots.
+- Blocks stay schema-agnostic and do not import page content collections.
+- Blocks expose `class?: string`, apply it to the root, and use plain inline prop types.
+- Block props use semantic names such as `title`, `description`, `buttons`, `features`, `href`, and `icon`.
+- Button size belongs to the block design, not button data.
 
-Local components are application code unless repo-specific instructions say
-otherwise.
+### CLI -> [cli.md](./cli.md)
 
-## Blocks
+- Fulldev UI is installed through the shadcn CLI using the `@fulldev` registry.
+- Do not invent a `fulldev` CLI command unless the project actually provides one.
+- Use `npx shadcn@latest add @fulldev/<component>` or the project package runner equivalent.
 
-Blocks commonly live in `src/components/blocks`, unless the project has a
-different established convention.
+### Customization -> [customization.md](./customization.md)
 
-Blocks are production-leaning compositions for content-driven pages. They should
-receive project-specific data through props and slots while layouts map
-schema-backed content into those props.
+- Prefer semantic CSS variables and Fulldev/shadcn component variants.
+- Customize theme variables before editing installed component source.
+- Use local wrappers/compositions when behavior is project-specific.
 
-Block conventions:
+### MCP -> [mcp.md](./mcp.md)
 
-- Expose `class?: string` and apply it to the root.
-- Keep prop types plain and local.
-- Use semantic prop names such as `title`, `description`, `buttons`,
-  `features`, `services`, `reviews`, `href`, and `icon`.
-- Avoid generic collection names like `items`, `entries`, `cards`, or `actions`
-  unless the block is genuinely generic.
-- Button data should not include size when size is a block design decision.
-- Images, links, labels, CTAs, and content-owned icons that vary by project,
-  page, block instance, or locale should come through props.
+- If a shadcn MCP server is configured, use it as registry tooling for `@fulldev` items.
+- Use CLI inspection when MCP cannot reveal local project configuration.
 
-## Customization
+### Validation -> [validation.md](./rules/validation.md)
 
-Customize theme variables and component variants before editing installed
-component source. Use local wrappers or compositions when behavior is
-project-specific.
+- Use the project package manager.
+- During development, run or reuse the dev server and read logs occasionally.
+- Do not run full builds or checks after every small edit.
+- For release prep, run the release validation sequence in `rules/validation.md`.
 
-Prefer semantic CSS variables over one-off style overrides. Keep customization
-at the lowest level that owns the decision: theme tokens for global look,
-variants for component behavior, layouts for page orchestration, and local
-wrappers for project-specific composition.
+### Anti-Patterns -> [anti-patterns.md](./rules/anti-patterns.md)
 
-## Validation
-
-Use the project's package manager and local instructions. Keep development
-feedback fast:
-
-- Start or reuse the dev server when presentation, routing, or content changed.
-- Read dev server logs occasionally.
-- Format touched files when a change is settled.
-- Do not run full checks or builds after every small edit.
-- Run focused validation for contract changes and broader validation only when
-  requested or when the change is risky.
+- Do not add page orchestration to routes, content files, `base.astro`, or reusable blocks.
+- Do not move implementation details into content.
+- Do not create local reusable UI before checking whether a Fulldev component already exists.
+- Do not silently restructure a client project into Fulldev architecture without surfacing the migration.
 
 ## Workflows
 
 ### Standard Change
 
 1. Identify the touched responsibility tier.
-2. Inspect nearby implementation and naming/composition patterns.
-3. Make the smallest coherent change that preserves project architecture.
-4. Use the dev server and logs for feedback when presentation or routing is
-   affected.
-5. Run only the relevant validation subset unless final validation is requested.
+2. Load the matching rule files from `rules/`.
+3. Inspect nearby implementation and existing naming/composition patterns.
+4. Make the smallest coherent change that preserves the project architecture.
+5. Use the dev server/logs for feedback when presentation or routing is affected.
+6. Run full validation only for release prep, risky structural changes, or when the user asks.
 
 ### Add Fulldev UI to a Project
 
-1. Inspect whether the project already has shadcn-compatible configuration.
-2. If needed, initialize shadcn-compatible component installation.
-3. Ensure `@fulldev` is configured as a registry.
-4. Install requested components or blocks with shadcn-compatible tooling.
-5. Read installed files and adapt imports only when the project requires it.
+1. Load `cli.md` and `customization.md`.
+2. Inspect whether the project already has `components.json`.
+3. If needed, initialize shadcn-compatible component installation.
+4. Ensure `@fulldev` is configured as a registry.
+5. Install requested components with `npx shadcn@latest add @fulldev/<name>`.
+6. Read installed files and adapt imports only when the project requires it.
 
 ### New or Changed Page Type
 
-1. Update the layout schema.
-2. Add it to the page schema union if the project uses one.
-3. Create or update the layout.
-4. Add or update content.
-5. Keep route files thin.
+1. Load `rules/source-ownership.md`, `rules/layouts.md`, and `rules/validation.md`.
+2. Add or update the layout schema in `src/schemas/layouts`.
+3. Add it to the union in `src/schemas/page.ts`.
+4. Create or update the layout in `src/layouts`.
+5. Add or update content under `src/content/pages`.
+6. Keep route files unchanged.
 
 ### Local Component or Block
 
-1. Check whether an existing `@fulldev` component or block covers the need.
-2. Keep the API small, semantic, and content-first.
-3. Keep content and schema concerns out of reusable components/blocks.
-4. Treat the result as local application code unless repo-specific instructions
-   say otherwise.
+1. Check whether an existing `@fulldev` component covers the need.
+2. Load `rules/components.md` or `rules/blocks.md`.
+3. Keep the API small, semantic, and content-first.
+4. Keep content and schema concerns out of reusable components/blocks.
+5. Treat the result as local app code unless repo-specific instructions say otherwise.
 
 ### Docs or Examples
 
-Treat docs as descriptions of the API, not the source of truth for the API. If
-docs and implementation disagree, fix the implementation or local contract
-first.
+1. Load the rules for the thing being documented.
+2. Treat docs as descriptions of the API, not the source of truth for the API.
+3. If docs and implementation disagree, fix the implementation or local contract first.
 
 ## Progressive Disclosure
 
-When this skill package includes detailed rule files, load only the files
-relevant to the current change:
-
-- `rules/source-ownership.md` for `src/content`, `src/schemas`, content schemas,
-  icons, and content/code boundaries.
-- `rules/layouts.md` for `src/layouts`, generic layout renderers, base layouts,
-  and route boundaries.
-- `rules/components.md` for reusable UI components and Astro component
-  conventions.
-- `rules/blocks.md` for block prop naming, portability, and layout-to-block
-  mapping.
+Detailed project doctrine lives in `rules/`. Load only the files relevant to the current change:
+
+- `rules/source-ownership.md` for `src/content`, `src/schemas`, content schemas, icons, and content/code boundaries.
+- `rules/layouts.md` for `src/layouts`, `src/components/layout-renderer.astro`, `src/layouts/base.astro`, and `src/pages/[...page].astro`.
+- `rules/components.md` for `src/components/ui`, local reusable UI, Fulldev component usage, and Astro component conventions.
+- `rules/blocks.md` for `src/components/blocks`, block prop naming, block portability, and layout-to-block mapping.
 - `cli.md` for installing Fulldev UI through shadcn-compatible tooling.
 - `customization.md` for theming, CSS variables, and component customization.
-- `mcp.md` for using shadcn-compatible MCP tooling with the `@fulldev`
-  registry.
-- `rules/validation.md` before finishing changes, to choose validation commands.
-- `rules/anti-patterns.md` when reviewing architecture or investigating drift.
+- `mcp.md` for using shadcn-compatible MCP tooling with the `@fulldev` registry.
+- `rules/validation.md` before finishing changes, to choose the right `pnpm` commands.
+- `rules/anti-patterns.md` when reviewing architecture, investigating drift, or deciding whether a proposed shortcut violates Fulldev doctrine.
 
-The core guidance above must stand on its own because a new project may not yet
-have any of these files.
+If a change crosses boundaries, load every relevant file. Component installation commonly needs `cli.md`, `customization.md`, `rules/components.md`, and `rules/validation.md`.

.agents/skills/fulldev/cli.md

@@ -1,6 +1,6 @@
 # Fulldev CLI Reference
 
-Fulldev UI uses the shadcn CLI and registry protocol. There is no assumed `fulldev` binary. Say "install the Fulldev component" or "install the Fulldev block", but run shadcn-compatible commands against the `@fulldev` registry.
+Fulldev UI uses the shadcn CLI and registry protocol. There is no assumed `fulldev` binary. Say "install the Fulldev component", but run shadcn-compatible commands against the `@fulldev` registry.
 
 ## Project Setup
 
@@ -42,7 +42,7 @@ Inspect project configuration:
 npx shadcn@latest info
 ```
 
-Install Fulldev components or blocks:
+Install Fulldev components:
 
 ```bash
 npx shadcn@latest add @fulldev/button
@@ -68,6 +68,6 @@ npx shadcn@latest view @fulldev/button
 
 - Do not invent Fulldev CLI flags or commands.
 - Do not fetch registry files manually when the shadcn CLI can preview, diff, view, or install them.
-- Before creating local UI or page sections, check whether an `@fulldev` component or block already exists.
-- After installing a component or block, read the added files when behavior, imports, or API details matter.
+- Before creating local UI, check whether an `@fulldev` component already exists.
+- After installing a component, read the added files when behavior, imports, or API details matter.
 - If a third-party registry item hardcodes aliases, adjust imports to the project's actual aliases.

.agents/skills/fulldev/rules/blocks.md

@@ -13,10 +13,9 @@ Blocks should:
 - Not import page schemas or content collection types.
 - Not import from `src/content`, `src/layouts`, route files, or private page architecture.
 - Not hardcode content-meaningful icons, entries, CTAs, links, labels, or images when they should vary by project, page, block instance, or locale.
-- Not import docs-site assets, placeholder images, or other project-owned media. Images rendered by installable blocks should be passed in through props.
 - Let layouts map schema-backed content into block props.
 
-It is fine to import fixed code-owned UX/control icons inside a block. Use the `Icon` component only when the icon name is content/config-owned data.
+It is fine to hardcode code-owned UX/control icons inside a block.
 
 Layouts importing reusable blocks and passing schema-backed content into them is the preferred orchestration pattern. In client projects, local blocks are application code unless repo-specific instructions say otherwise.
 

.agents/skills/fulldev/rules/components.md

@@ -9,17 +9,15 @@ Reusable UI components live in `src/components/ui/<component-name>/`.
 - Use the existing `@/*` import alias for `src/*`.
 - Preserve nearby naming and composition patterns.
 
-Prefer existing `@fulldev` components before creating local reusable UI. For complete page sections, check existing `@fulldev` blocks first. Local components are application code unless repo-specific instructions say otherwise.
+Prefer existing `@fulldev` components before creating local reusable UI. Local components are application code unless repo-specific instructions say otherwise.
 
 ## Astro Frontmatter
 
 Astro frontmatter should make the file's contract obvious:
 
 - Use `type Props`, not `interface Props`.
 - Define `type Props` before reading `Astro.props`.
-- Keep `Props` local to the component frontmatter. Do not `export type Props` from `.astro` files unless an external TypeScript module explicitly imports it.
 - Let Astro infer prop types from `Props`; do not annotate the assignment or destructuring with `: Props`.
-- Do not cast `Astro.props` with `as Props`. If Astro cannot associate a complex local `Props` type with the destructuring, prefer simplifying the type shape or using `satisfies Props`.
 - Destructure `Astro.props` once near the top of the frontmatter.
 - Derive local values after destructuring.
 

.agents/skills/fulldev/rules/source-ownership.md

@@ -45,7 +45,6 @@ Treat icons as one example of the broader content/code boundary:
 - UX/control icons belong in code: chevrons, close icons, menu icons, search icons, disclosure arrows, loading indicators, carousel arrows, and form affordances.
 - Content/meaning icons may come from content as plain icon names when the icon changes with the surrounding content, project, or locale.
 - Render content-owned icons through `src/components/ui/icon` with `<Icon name={item.icon} />`.
-- Import fixed code-owned icons directly from the static SVG packages, using local names with an `Icon` suffix such as `ArrowRightIcon`.
 - Keep the current `Icon` contract: plain names are normalized, Lucide is preferred by default, and Simple Icons is used as a fallback mainly for brand/social icons.
 
 ## Global Content