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

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

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

@@ -1,26 +0,0 @@
-/**
- * Code-defined navigation items.
- *
- * Synced to the Fluid OS API on `fluid deploy` with source: "code".
- * Position is derived from array order. Items without a slug are
- * treated as section headers.
- *
- * User-created navigation items (from the admin dashboard) are not
- * affected — only items with source: "code" are managed.
- *
- * IMPORTANT: Do not add import statements to this file. The Fluid CLI
- * reads this file without resolving dependencies, so it must be
- * self-contained static data only.
- */
-export const navigation = [
-  {
-    label: "Dashboard",
-    slug: "dashboard",
-    icon: "home",
-  },
-  {
-    label: "MySite",
-    slug: "my-site",
-    icon: "globe",
-  },
-];

package/templates/base/src/screens/Dashboard.tsx

@@ -1,133 +0,0 @@
-import {
-  TextWidget,
-  ChartWidget,
-  ToDoWidget,
-  RecentActivityWidget,
-  CalendarWidget,
-} from "@fluid-app/portal-sdk";
-
-/**
- * Sample chart data extracted as a module-level constant.
- *
- * The data is extracted as a constant to:
- * 1. Keep the component cleaner
- * 2. Allow reuse/testing if needed
- * 3. Make it clear the data is static
- */
-const MONTHLY_PERFORMANCE_DATA = [
-  { name: "Jan", value: 4000 },
-  { name: "Feb", value: 3000 },
-  { name: "Mar", value: 5000 },
-  { name: "Apr", value: 4500 },
-  { name: "May", value: 6000 },
-  { name: "Jun", value: 5500 },
-];
-
-/**
- * Dashboard Screen
- *
- * This is the default landing screen for the portal.
- * It demonstrates using various widgets from portal-sdk:
- *
- * - TextWidget: Display text content with optional title
- * - ToDoWidget: Task list (uses useTodos hook)
- * - RecentActivityWidget: Activity feed (uses useActivities hook)
- * - ChartWidget: Bar, line, area, pie charts
- * - CalendarWidget: Calendar view (uses useCalendarEvents hook)
- *
- * These widgets fetch data from hooks that connect to your Fluid API.
- * In development, they show demo data. Configure fluid.config.ts
- * to connect to your Fluid instance.
- */
-export function DashboardScreen() {
-  return (
-    <div className="space-y-6">
-      {/* Welcome section */}
-      <TextWidget
-        titleEnabled
-        title="Welcome to Your Portal"
-        description="This is your portal dashboard. Use widgets from @fluid-app/portal-sdk to build powerful interfaces for your team."
-        padding={4}
-        borderRadius="lg"
-      />
-
-      {/* Stats row - sample static data */}
-      <div className="grid gap-6 md:grid-cols-3">
-        <div className="bg-background rounded-lg p-4 shadow-sm">
-          <p className="text-foreground text-3xl font-bold">$12,450</p>
-          <p className="text-muted-foreground mt-1 text-sm">Total Sales</p>
-        </div>
-
-        <div className="bg-background rounded-lg p-4 shadow-sm">
-          <p className="text-foreground text-3xl font-bold">24</p>
-          <p className="text-muted-foreground mt-1 text-sm">Active Orders</p>
-        </div>
-
-        <div className="bg-background rounded-lg p-4 shadow-sm">
-          <p className="text-foreground text-3xl font-bold">156</p>
-          <p className="text-muted-foreground mt-1 text-sm">Customers</p>
-        </div>
-      </div>
-
-      {/* Main content grid - Tasks and Activity */}
-      <div className="grid gap-6 lg:grid-cols-2">
-        {/* To-Do Widget - fetches tasks via useTodos hook */}
-        <ToDoWidget
-          titleEnabled
-          titleText="Tasks"
-          maxItems={5}
-          padding={4}
-          borderRadius="lg"
-        />
-
-        {/* Recent Activity Widget - fetches via useActivities hook */}
-        <RecentActivityWidget
-          titleEnabled
-          titleText="Recent Activity"
-          maxItemsToShow={5}
-          padding={4}
-          borderRadius="lg"
-        />
-      </div>
-
-      {/* Performance chart - uses extracted constant data */}
-      <ChartWidget
-        titleEnabled
-        title="Monthly Performance"
-        chartType="bar"
-        data={MONTHLY_PERFORMANCE_DATA}
-        padding={4}
-        borderRadius="lg"
-      />
-
-      {/* Calendar preview - uses useCalendarEvents hook */}
-      <CalendarWidget
-        titleEnabled
-        titleText="Upcoming Events"
-        padding={4}
-        borderRadius="lg"
-      />
-
-      {/* Getting started tips */}
-      <div className="grid gap-6 md:grid-cols-2">
-        <TextWidget
-          titleEnabled
-          title="Customize Navigation"
-          description="Edit portal.config.ts to add, remove, or reorder navigation items. Core screens (Messaging, Contacts) are built-in."
-          padding={4}
-          borderRadius="lg"
-          background={{ type: "solid", color: "muted" }}
-        />
-
-        <TextWidget
-          titleEnabled
-          title="Connect Your Data"
-          description="Configure fluid.config.ts with your Fluid API credentials. Widgets will automatically fetch real data from your account."
-          padding={4}
-          borderRadius="lg"
-          background={{ type: "solid", color: "muted" }}
-        />
-      </div>
-    </div>
-  );
-}