@fluid-app/fluid-cli-portal 0.1.32 → 0.1.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-portal",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Fluid CLI plugin for building portal applications",
   "files": [
     "dist",
@@ -32,7 +32,7 @@
     "p-limit": "^7.3.0",
     "prompts": "^2.4.2",
     "tsx": "^4.21.0",
-    "@fluid-app/fluid-cli": "0.1.11"
+    "@fluid-app/fluid-cli": "0.1.12"
   },
   "devDependencies": {
     "@swc/core": "^1.15.18",

package/templates/base/.gitignore.template

@@ -0,0 +1,27 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Editor directories
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Portal sync metadata (generated by fluid portal pull/push)
+.portal-sync/
+
+# Logs
+*.log
+pnpm-debug.log*

package/templates/base/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+Guidance for AI coding tools working in this generated Fluid portal project.
+
+This project is primarily authored through the Fluid OS portal definition sync workflow. Author portal structure, routes, and content through pulled Fluid OS JSON under `portal/` unless a human explicitly asks for a different architecture.
+
+## Source of truth
+
+- Use `.agents/skills/fluid-portal-authoring/SKILL.md` for portal definition work.
+- Use `.agents/skills/fluid-widget-authoring/SKILL.md` for company widget creation with `pnpm widget:create`, widget manifests, property schemas, runtime CSS, validation, build, and publish work.
+- `.claude/skills/...` contains the same generated skills for Claude-compatible tools.
+
+## Portal workflow
+
+1. Run `pnpm pull` to sync the remote Fluid OS definition into `portal/`.
+2. Edit the pulled JSON under `portal/`.
+3. Validate locally with `pnpm typecheck`, `pnpm lint`, and `pnpm build` when applicable.
+4. Run `pnpm push` to sync local `portal/` JSON back to the remote working/draft definition.
+5. Run `pnpm exec fluid portal version create --activate` only when the pushed definition should become live.
+
+Do not edit `.portal-sync/` by hand. It is generated sync metadata.
+
+## Command boundaries
+
+- `pnpm pull` / `fluid portal pull`: downloads the portal definition into `portal/`.
+- `pnpm push` / `fluid portal push`: updates the remote working/draft definition from local JSON.
+- `fluid portal version create --activate`: publishes the remote working/draft definition as the live version.
+- `pnpm build`: builds the hosted portal shell assets into `dist/`.
+- `fluid portal deploy`: publishes company-owned widget runtime artifacts, not portal JSON and not shell assets.
+
+## Quality bar
+
+- Keep portal JSON valid and references consistent.
+- Preserve stable IDs and slugs unless the change intentionally renames them.
+- Keep the portal shell thin; do not fork SDK internals into this app.
+- For widget changes, use `pnpm widget:create <name>` / `fluid portal widget create <name>` and follow the copied `fluid-widget-authoring` skill before editing manifests or schemas.

package/templates/base/skills/fluid-portal-authoring/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: fluid-portal-authoring
+description: Use when modifying this generated Fluid portal project through the supported pull/edit/push/version workflow, including portal/ JSON, themes, navigations, screens, profiles, local validation, and distinguishing portal definition sync from widget artifact deployment.
+---
+
+# Fluid Portal Authoring
+
+Use this skill before changing a generated Fluid portal project.
+
+## Supported authoring model
+
+This template is a Fluid portal shell plus a local copy of the Fluid OS portal definition.
+The supported workflow is:
+
+1. Pull the remote portal definition into `portal/`.
+2. Edit the pulled JSON files locally.
+3. Validate and preview locally.
+4. Push the JSON changes back to the remote working/draft definition.
+5. Create and activate a version when the pushed definition should go live.
+
+In generated portal projects, routes, portal structure, screens, themes, profiles, and definition metadata are owned by Fluid OS JSON under `portal/` after pull.
+
+## Important files and directories
+
+- `src/main.tsx`: portal shell bootstrap. Keep this small.
+- `src/portal.config.ts`: portal SDK integration and widget/package exports when present.
+- `src/index.css`: app-level CSS imports and global styles.
+- `portal/`: pulled Fluid OS definition JSON. This is the primary editing surface for portal content.
+- `.portal-sync/`: generated sync metadata used by pull/push diffing. Do not edit by hand.
+- `.fluidrc`: generated CLI profile binding for this portal project.
+- `.agents/skills/fluid-widget-authoring/SKILL.md`: widget authoring guidance when this portal owns widget packages or widget manifests.
+
+## Pull before editing
+
+Run:
+
+```bash
+pnpm pull
+```
+
+Expected result:
+
+- `portal/` contains local JSON for Fluid OS resources such as screens, themes, navigations, profiles, and definition metadata.
+- `.portal-sync/` contains sync state used to compute future diffs.
+- `.fluidrc` pins the CLI profile when the project was created with a profile.
+
+Pull before making changes unless you intentionally want to overwrite local work. If local JSON and remote state may both have changed, inspect the diff before pushing.
+
+## Edit pulled portal JSON
+
+Work inside `portal/` for portal definition changes.
+
+Guidelines:
+
+- Keep JSON valid and deterministic.
+- Preserve stable IDs, slugs, and cross-resource references unless intentionally changing them.
+- Update references together. If a navigation item points to a screen/theme/profile slug or ID, make sure the target exists in `portal/`.
+- Prefer small, reviewable edits. One portal content change per PR is easier to validate.
+- Do not hand-edit `.portal-sync/`; it is sync metadata, not source content.
+- Do not invent unsupported fields. Match the shapes produced by `pnpm pull`.
+
+## Validate locally
+
+Run the checks that match the change:
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+```
+
+For portal JSON changes, also run a push dry run or validation command if available in your CLI version. If a command reports broken cross-references, fix the JSON references before pushing.
+
+Use local preview for visual/content changes:
+
+```bash
+pnpm dev
+```
+
+Expected result: the portal shell starts and can load the local pulled portal definition for preview where supported by the SDK/tooling.
+
+## Push definition changes
+
+Run:
+
+```bash
+pnpm push
+```
+
+What push does:
+
+- Reads local `portal/` JSON.
+- Compares it against `.portal-sync/` state.
+- Shows or applies a diff to the remote working/draft Fluid OS definition.
+- Updates the remote draft/working state.
+
+What push does not do:
+
+- It does not create a live Fluid OS version by itself.
+- It does not upload hosted portal shell assets from `dist/`.
+- It does not publish widget runtime artifacts.
+
+After a successful push, inspect the remote portal definition if possible and run the app locally or against the target environment.
+
+## Publish a live portal version
+
+After pushing and verifying the working/draft definition, create and activate a version when the change should become live:
+
+```bash
+pnpm exec fluid portal version create --activate
+```
+
+Use this only when the pushed definition is ready for users. If activation should be coordinated with a release or content review, stop and ask the project owner before running it.
+
+## Distinguish the three deploy/sync paths
+
+Do not mix these up:
+
+- `pnpm push` / `fluid portal push`: syncs `portal/` JSON to the remote working/draft Fluid OS definition.
+- `fluid portal version create --activate`: snapshots the remote working/draft definition and makes it live.
+- GitHub Actions or hosting deployment: uploads the built portal shell assets from `dist/`.
+- `fluid portal deploy`: publishes company-owned widget runtime artifacts. It is not the portal JSON push command and it is not the hosted shell asset deployment.
+
+## Widget work inside a portal project
+
+Company-owned portal widgets are still supported. Use the widget scaffold command, then follow the copied `fluid-widget-authoring` skill for detailed manifest, property schema, theme token, validation, build, and publish rules.
+
+```bash
+pnpm widget:create my-widget
+# or
+pnpm exec fluid portal widget create my-widget
+```
+
+Short version:
+
+- Keep widget code under the scaffolded `src/widgets/<name>/` directory.
+- Keep widget metadata serializable.
+- Keep `defaultProps` aligned with property schema defaults.
+- Use semantic theme tokens.
+- Import runtime CSS from the widget build graph.
+- Validate/build widget artifacts before publishing them.
+
+## Preflight checklist
+
+Before considering portal work complete:
+
+- [ ] Pulled the latest remote definition or intentionally worked from current local JSON.
+- [ ] Edited only supported files for the change.
+- [ ] Preserved JSON validity and cross-resource references.
+- [ ] Kept portal structure, routes, and content changes in pulled Fluid OS JSON under `portal/`.
+- [ ] Ran typecheck/lint/build or the closest available checks.
+- [ ] Ran push only when the local `portal/` diff was understood.
+- [ ] Created/activated a version only when the definition should go live.

package/templates/base/src/main.tsx

@@ -1,5 +1,5 @@
 import { createPortal } from "@fluid-app/portal-sdk";
-import { customPages, customWidgets } from "./portal.config";
+import { customWidgets } from "./portal.config";
 import "./index.css";
 
-createPortal({ customPages, customWidgets });
+createPortal({ customWidgets });

package/templates/base/src/portal.config.ts

@@ -1,40 +1,14 @@
-/**
- * Portal Configuration
- *
- * Register custom page components and widget plugins here.
- *
- * - customPages: rendered by AppShell when a navigation slug matches
- * - customWidgets: registered as plugin widgets in the builder and SDK
- *
- * Navigation structure is defined in navigation.config.ts and synced
- * to the Fluid OS API on `fluid deploy`.
- */
-
-import type { ComponentType } from "react";
 import type { WidgetManifest } from "@fluid-app/portal-sdk";
-import { DashboardScreen } from "./screens/Dashboard";
 
 /**
- * Custom page components keyed by navigation slug.
+ * Portal SDK integration point.
  *
- * When AppShell resolves a navigation item, it checks this map first.
- * If a matching slug is found here, the custom component is rendered
- * instead of the default system screen or placeholder.
- */
-export const customPages: Record<string, ComponentType> = {
-  dashboard: DashboardScreen,
-  // Add more custom screens here:
-  // "example-form": ExampleFormScreen,
-};
-
-/**
- * Custom widget plugins.
+ * Portal screens, themes, navigations, and profiles are authored through
+ * the Fluid OS definition sync workflow: `pnpm pull`, edit `portal/`,
+ * then `pnpm push`. Keep portal structure, routes, and content in the
+ * pulled Fluid OS JSON files.
  *
- * Each manifest registers a widget in both the builder palette
- * and the SDK runtime. Add manifests here after scaffolding
- * with `fluid widget create <name>`.
+ * Keep this file for widget manifests or source widget packages that need
+ * to be available to the SDK preview/runtime.
  */
-export const customWidgets: WidgetManifest[] = [
-  // Import and add widget manifests here:
-  // stockTicker,
-];
+export const customWidgets: WidgetManifest[] = [];

package/templates/starter/README.md.template

@@ -1,243 +1,184 @@
 # {{projectName}}
 
-A custom Fluid portal built with [@fluid-app/portal-sdk](https://github.com/fluidcommerce/portal-sdk).
+A Fluid portal shell built with `@fluid-app/portal-sdk` and the Fluid portal CLI.
 
-This is the **Starter** template - includes a dashboard with multiple widgets plus all core screens.
+This starter is designed for the Fluid OS definition workflow: pull the portal definition into local JSON, edit `portal/`, push the working/draft definition back to Fluid OS, then create and activate a version when it should go live.
 
-## What's Included
+## What's included
 
-### Core Screens (Built-in)
-- **Messages** - Conversation management (MessagingScreen)
-- **Contacts** - Contact directory (ContactsScreen)
+- **Portal shell** — Vite builds the hosted SDK shell assets.
+- **Portal definition sync** — `pnpm pull` and `pnpm push` manage local Fluid OS JSON under `portal/`.
+- **Deployment workflow** — GitHub Actions can build and upload the hosted shell assets in `dist/`.
+- **Widget authoring support** — `pnpm widget:create <name>` scaffolds company-owned portal widgets.
+- **AI authoring kit** — generated `AGENTS.md`, `CLAUDE.md`, `.agents/skills/...`, and `.claude/skills/...` files explain the supported portal and widget workflows.
 
-### Custom Screens
-- **Dashboard** - Overview screen demonstrating:
-  - TextWidget - Welcome message and tips
-  - ToDoWidget - Task list (uses `useTodos` hook)
-  - RecentActivityWidget - Activity feed (uses `useActivities` hook)
-  - ChartWidget - Performance visualization
-  - CalendarWidget - Event calendar (uses `useCalendarEvents` hook)
-
-## Getting Started
-
-### Development
-
-Start the development server:
+## Quick start
 
 ```bash
+pnpm install
+pnpm pull
 pnpm dev
 ```
 
-Open [http://localhost:5173](http://localhost:5173) in your browser.
-
-### Building for Production
-
-```bash
-pnpm build
-```
-
-The output will be in the `dist/` folder.
+Open the local URL printed by Vite, usually [http://localhost:5173](http://localhost:5173).
 
-### Preview Production Build
+Useful commands:
 
 ```bash
-pnpm preview
+pnpm dev        # Start Vite
+pnpm build      # TypeScript build plus production bundle
+pnpm preview    # Preview dist locally
+pnpm typecheck  # TypeScript checks
+pnpm lint       # OxLint
+pnpm pull       # fluid portal pull
+pnpm push       # fluid portal push
+pnpm widget:create <name>  # scaffold a company-owned portal widget
 ```
 
-## Project Structure
-
-```
-src/
-├── main.tsx              # App entry with FluidProvider setup
-├── App.tsx               # Main app with screen routing
-├── index.css             # Global styles (Tailwind CSS)
-├── fluid.config.ts       # API and auth configuration
-├── portal.config.ts      # Navigation and screen registration
-├── navigation/
-│   └── index.tsx         # Sidebar navigation component
-└── screens/
-    └── Dashboard.tsx     # Dashboard with multiple widgets
+Set `VITE_API_URL` in `.env` if you need to point the SDK at a non-default Fluid API host.
+
+## Project structure
+
+```text
+.
+├── AGENTS.md                                      # AI-agent guidance
+├── CLAUDE.md                                      # Bridge to AGENTS.md
+├── .agents/skills/fluid-portal-authoring/         # Portal sync workflow skill
+├── .agents/skills/fluid-widget-authoring/         # Widget authoring skill
+├── .claude/skills/fluid-portal-authoring/         # Claude-compatible copy
+├── .claude/skills/fluid-widget-authoring/         # Claude-compatible copy
+├── .github/workflows/deploy.yml                   # Hosted shell asset deployment
+├── src/
+│   ├── main.tsx                                   # createPortal bootstrap
+│   ├── index.css                                  # Tailwind and SDK globals
+│   ├── portal.config.ts                           # SDK/widget package integration
+│   ├── preview-entry.tsx                          # Builder/widget preview entry
+│   └── widgets/                                   # Created by pnpm widget:create
+├── portal/                                        # Created/refreshed by fluid portal pull
+└── .portal-sync/                                  # Generated sync metadata
 ```
 
-## Deployment
+## Supported portal authoring workflow
 
-This project includes a GitHub Actions workflow (`.github/workflows/deploy.yml`) that deploys your portal to Google Cloud Storage + Cloud CDN.
+### 1. Pull remote Fluid OS definitions
 
-### How it works
+```bash
+pnpm pull
+```
 
-1. **Trigger** — pushes to `main` (or manual dispatch)
-2. **Build** — runs `pnpm build`, producing stable filenames (`portal.js`, `portal.css`)
-3. **Upload** — syncs `dist/` to `gs://portals-cdn/{{projectName}}/assets/` via `gcloud storage rsync`
-4. **Invalidate** — clears the CDN cache for your tenant's asset prefix
+This runs `fluid portal pull` and writes `portal/` plus `.portal-sync/`.
 
-### Setup
+- `portal/` contains local JSON for Fluid OS resources such as screens, themes, navigations, profiles, and definition metadata.
+- `.portal-sync/` contains generated sync state for future diffs. Do not edit it by hand.
 
-1. Create a GCP service account with Storage Object Admin and Compute Load Balancer Admin roles
-2. Add the service account JSON key as a GitHub Actions secret named `GCP_SA_JSON`
-3. Set `CDN_HOSTNAME` in `.github/workflows/deploy.yml` to your Cloud CDN load balancer's frontend domain
-4. Update `GCP_PROJECT` and `CDN_URL_MAP` if your project differs from the defaults
+Pull before editing unless you intentionally want to work from the current local JSON.
 
-### Environment variables
+### 2. Edit `portal/` JSON
 
-| Variable | Where | Purpose |
-|----------|-------|---------|
-| `GCP_SA_JSON` | GitHub secret | GCP service account credentials |
-| `GCP_PROJECT` | Workflow env | Google Cloud project ID |
-| `CDN_URL_MAP` | Workflow env | Cloud CDN URL map name for cache invalidation |
-| `CDN_HOSTNAME` | Workflow env | CDN frontend domain (load balancer hostname) |
-| `VITE_ASSET_BASE` | Build env | Derived from `CDN_HOSTNAME` (set automatically) |
+Make portal definition changes inside `portal/`.
 
-## Customization
+Guidelines:
 
-### Modify Navigation
+- Keep JSON valid and deterministic.
+- Preserve stable IDs, slugs, and cross-resource references unless intentionally changing them.
+- Update related files together when a resource reference changes.
+- Do not invent unsupported fields. Match the shapes produced by `pnpm pull`.
+- Keep changes small enough to review.
 
-Edit `src/portal.config.ts` to add, remove, or reorder navigation items:
+### 3. Validate locally
 
-```typescript
-navigation: [
-  // Your custom screens
-  { id: "dashboard", label: "Dashboard", icon: "LayoutDashboard", screen: "custom:dashboard" },
+Run checks that match the change:
 
-  // Built-in core screens
-  { id: "messaging", label: "Messages", icon: "MessageSquare", screen: "core:messaging" },
-  // ...
-],
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
 ```
 
-### Add Custom Screens
-
-1. Create a screen component in `src/screens/`:
+For visual/content changes, use local preview:
 
-```tsx
-// src/screens/Orders.tsx
-import { TableWidget, TextWidget } from "@fluid-app/portal-sdk";
-
-export function OrdersScreen() {
-  return (
-    <div className="space-y-6">
-      <TextWidget title="Orders" titleEnabled padding={4} borderRadius="lg" />
-      {/* Add more widgets */}
-    </div>
-  );
-}
+```bash
+pnpm dev
 ```
 
-2. Register in `portal.config.ts`:
+Expected result: the portal shell starts and can load the local pulled portal definition where supported by the SDK/tooling.
 
-```typescript
-import { OrdersScreen } from "./screens/Orders";
+### 4. Push local definition changes
 
-customScreens: {
-  dashboard: DashboardScreen,
-  orders: OrdersScreen,  // Add here
-},
+```bash
+pnpm push
 ```
 
-3. Add to navigation:
+This runs `fluid portal push`, compares local `portal/` JSON against sync state, and updates the remote working/draft definition.
 
-```typescript
-{ id: "orders", label: "Orders", icon: "ShoppingCart", screen: "custom:orders" },
-```
+Push does **not** publish changes live by itself.
 
-### Connect to Fluid API
+### 5. Publish a live Fluid OS version
 
-Edit `src/fluid.config.ts` to configure your API connection:
+When the pushed working/draft definition is ready for users:
 
-```typescript
-export const fluidConfig: FluidSDKConfig = {
-  baseUrl: import.meta.env.VITE_API_URL ?? "https://api.fluid.app",
-  getAuthToken: () => getStoredToken() ?? null,
-};
+```bash
+pnpm exec fluid portal version create --activate
 ```
 
-## Available Widgets
+Only run this when activation is intended. If publishing needs content, design, or release approval, stop and ask first.
 
-Import from `@fluid-app/portal-sdk`:
+## Command boundaries
 
-| Widget | Description |
-|--------|-------------|
-| `TextWidget` | Text content with optional title |
-| `ChartWidget` | Bar, line, area, pie charts |
-| `TableWidget` | Data tables with columns |
-| `ListWidget` | Lists with icons and actions |
-| `ToDoWidget` | Task list (uses `useTodos`) |
-| `RecentActivityWidget` | Activity feed (uses `useActivities`) |
-| `CalendarWidget` | Calendar view (uses `useCalendarEvents`) |
-| `CatchUpWidget` | Catch-up items |
-| `AlertWidget` | Info, warning, error alerts |
-| `ImageWidget` | Images with sizing options |
-| `VideoWidget` | Embedded video players |
-| `CarouselWidget` | Image/content carousel |
-| `ContainerWidget` | Layout containers |
-| `SpacerWidget` | Vertical spacing |
+Do not mix these up:
 
-## Building Forms
+- `fluid portal pull` downloads the remote portal definition into `portal/`.
+- `fluid portal push` syncs local `portal/` JSON to the remote working/draft definition.
+- `fluid portal version create --activate` makes the remote working/draft definition live.
+- `pnpm build` creates hosted shell assets in `dist/`.
+- GitHub Actions deploys hosted shell assets from `dist/`.
+- `fluid portal deploy` publishes company-owned widget runtime artifacts. It does not push portal JSON and does not upload hosted shell assets.
 
-For data-entry screens (order forms, customer intake, settings), we recommend [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) for validation.
+## Widget work
 
-### Install form dependencies
+Company-owned portal widgets are supported through the portal widget scaffold:
 
 ```bash
-pnpm add react-hook-form zod @hookform/resolvers
+pnpm widget:create stock-ticker
+# or
+pnpm exec fluid portal widget create stock-ticker
 ```
 
-### Example
-
-```tsx
-import { z } from "zod";
-import { useZodForm } from "@fluid-app/ui-primitives";
-
-const schema = z.object({
-  name: z.string().min(1, "Name is required"),
-  email: z.string().email("Invalid email"),
-});
-
-type FormData = z.infer<typeof schema>;
-
-export function MyFormScreen() {
-  const {
-    register,
-    handleSubmit,
-    formState: { errors, isSubmitting },
-  } = useZodForm<FormData>(schema);
-
-  const onSubmit = async (data: FormData) => {
-    // Call your API here
-    console.log(data);
-  };
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <input {...register("name")} placeholder="Name" />
-      {errors.name && <p>{errors.name.message}</p>}
-
-      <input {...register("email")} placeholder="Email" />
-      {errors.email && <p>{errors.email.message}</p>}
-
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? "Submitting..." : "Submit"}
-      </button>
-    </form>
-  );
-}
-```
+The scaffold writes widget source under `src/widgets/<name>/` and wires the widget manifest for portal tooling. Then use the generated widget authoring skill:
+
+- `.agents/skills/fluid-widget-authoring/SKILL.md`
+- `.claude/skills/fluid-widget-authoring/SKILL.md`
+
+That skill covers widget manifests, property schemas, theme variables, runtime CSS, validation, build, and publish workflows.
+
+## Hosted shell deployment
+
+The included GitHub Actions workflow builds the portal and uploads `dist/` to Google Cloud Storage plus Cloud CDN.
 
-### Starter example
+1. Push to `main` or run the workflow manually.
+2. The workflow runs `pnpm build`.
+3. It syncs `dist/` to `gs://portals-cdn/{{projectName}}/assets/`.
+4. It invalidates the CDN cache for this portal's asset prefix.
 
-A complete form example is included at `src/screens/ExampleForm.tsx`. To enable it:
+Setup:
 
-1. Install the form dependencies above
-2. Uncomment the import and nav entry in `src/portal.config.ts`
+1. Create a GCP service account with Storage Object Admin and Compute Load Balancer Admin roles.
+2. Add the service account JSON key as a GitHub Actions secret named `GCP_SA_JSON`.
+3. Set `CDN_HOSTNAME` in `.github/workflows/deploy.yml` to your Cloud CDN load balancer domain.
+4. Update `GCP_PROJECT` and `CDN_URL_MAP` if your project differs from the defaults.
 
-## Styling
+## AI authoring kit
 
-This project uses [Tailwind CSS v4](https://tailwindcss.com/).
+Generated projects include portable guidance for AI coding tools:
 
-Edit `src/index.css` to customize the theme or add global styles.
+- `AGENTS.md` — canonical project instructions.
+- `CLAUDE.md` — plain-file bridge to `AGENTS.md`.
+- `.agents/skills/fluid-portal-authoring/SKILL.md` — portal pull/edit/push/version workflow.
+- `.agents/skills/fluid-widget-authoring/SKILL.md` — widget authoring and validation workflow.
+- `.claude/skills/...` — Claude-compatible copies generated from the same template skill files.
 
-## Learn More
+## Learn more
 
-- [Fluid Commerce Documentation](https://docs.fluidcommerce.com)
-- [portal-sdk GitHub](https://github.com/fluidcommerce/portal-sdk)
-- [Vite Documentation](https://vite.dev)
-- [React Documentation](https://react.dev)
+- Fluid Commerce Documentation: https://docs.fluidcommerce.com
+- Vite Documentation: https://vite.dev
+- React Documentation: https://react.dev