@fluid-app/fluid-cli-portal 0.1.39 → 0.1.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-portal",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "Fluid CLI plugin for building portal applications",
   "files": [
     "dist",

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

@@ -59,6 +59,32 @@ Guidelines:
 - 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`.
 
+## Add a new page and put it in the menu
+
+A page = a **screen** (a `component_tree` of widgets) + a **navigation item** that points at it. A screen with no nav item is unreachable; a nav item whose screen reference doesn't resolve is silently dropped in local preview and refused at push. Both live in `portal/`.
+
+1. Create `portal/screens/<slug>.json`: `{ "name": "Rewards", "component_tree": [ ... ] }`. Give every node an `id` and a widget `type` from the catalog below. Match the shape `pnpm pull` produced.
+2. Add a navigation item to each profile that should see it: `{ "label": "Rewards", "slug": "rewards", "screen_id": <id> }` (mirror how sibling items in that navigation reference their screens — by `screen_id` or `slug`). Use `children[]` for a nested group. Add to `mobile_navigation` too for mobile.
+3. Link to it with a `ButtonWidget`/`LinkWidget` (or a carousel slide `buttonLink`) using the path `/rewards`.
+4. Preview on the profile local dev serves (default/first), then push and activate a version to go live.
+
+## Choosing a widget (recommend built-ins before custom code)
+
+Use the `type` value in a `component_tree` node. Reach for what already exists:
+
+- Layout: `ContainerWidget`, `LayoutWidget` (columns/grid), `NestedWidget`, `SpacerWidget`, `SeparatorWidget`
+- Hero/media: `CarouselWidget` (rotating hero slides w/ CTA), `ImageWidget`, `VideoWidget`
+- Content: `TextWidget`, `BulletListWidget`, `CardWidget`, `AlertWidget`, `TableWidget`, `ChartWidget`, `CalendarWidget`
+- Commerce/member: `ShopWidget`, `PointsWidget` (rewards balance), `RecentActivityWidget`, `ToDoWidget`
+- Links/sharing: `LinkWidget`, `ButtonWidget`, `QuickLinksWidget`, `QuickShareWidget`, `ListWidget`
+- Platform: `EmbedWidget` (drops a Mist app into a screen), `MySiteWidget`, `CatchUpWidget`
+
+An unregistered `type` renders nothing. Data-driven UI a built-in can't express (a member-specific dashboard) needs a custom widget package — a separate concern from this definition-editing workflow; note it to the user rather than hand-rolling code here.
+
+## System screens and how to reach them
+
+The portal ships built-in screens addressed by nav slug: `profile` (alias `account`), `orders`, `subscriptions`, `messaging`, `contacts`, `shop`, `customers`, `my-site`, `share/*`, `app-download`. To expose one, add a navigation item with that slug to the profile — `messaging` and `contacts` only appear when a nav item includes them, and `messages`/`my-site` are rep-only (a non-rep member sees the fallback). These are core surfaces the admin builder keeps; author your own pages alongside them in `portal/` and let the definition stay the source of truth so drag-and-drop editing keeps working.
+
 ## Validate locally
 
 Run the checks that match the change:
@@ -69,7 +95,10 @@ 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.
+For portal JSON changes, know that validation is asymmetric:
+
+- **Local preview is lenient.** The dev server builds its manifest from `portal/` and silently skips malformed JSON files and silently drops navigation items whose `screen` reference does not resolve. A screen that "just vanished" from the preview with no error usually means broken JSON or a broken reference in the file you last edited.
+- **Push is strict.** `pnpm push` validates cross-references (navigation → screen, profile → navigation/theme) before writing anything and refuses the entire push if any reference is broken.
 
 Use local preview for visual/content changes:
 
@@ -77,7 +106,12 @@ Use local preview for visual/content changes:
 pnpm dev
 ```
 
-Expected result: the portal shell starts and can load the local pulled portal definition for preview where supported by the SDK/tooling.
+Expected result: the portal shell starts and loads the local pulled portal definition for preview.
+
+Two local-preview rules that read as bugs if you do not know them:
+
+- The local manifest always serves the profile with `default: true` (or the first profile file if none is default). Profile `permissions` are **not** evaluated locally — edits to any other profile will never appear in the local preview. Permission matching only happens on the deployed portal against the real logged-in member.
+- The logged-in session is still real: rep-only screens (`messages`, `my-site`) render the customer fallback when the member is not rep-eligible.
 
 ## Push definition changes
 
@@ -87,12 +121,12 @@ Run:
 pnpm push
 ```
 
-What push does:
+What push does, in order (it stops at the first failing gate):
 
-- 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.
+1. **Invisible git sync.** Push auto-commits the whole working tree (`git add -A`; `.gitignore` is the only exclusion boundary — keep secrets in `.env`, never in tracked files) and pushes to the portal's Fluid-provisioned git repository. A "Skipped git sync — <reason>" note is non-fatal and the content push continues. A _failed_ git push aborts the whole command with your changes committed locally — reconcile (usually `git pull --rebase`) and rerun.
+2. **Snapshot diff.** Compares `portal/` against `.portal-sync/` state. "Nothing to push" means no local edits since the last pull/push.
+3. **Cross-reference validation.** Refuses the entire push, before any write, if a navigation item references a missing screen or a profile references a missing navigation/theme.
+4. **Phased write.** Screens and themes first, then navigations, then profiles. A failed phase skips later phases, and only successfully pushed files advance the snapshot — fix the error and rerun to push the remainder. "No mapping found for <type> slug" means the resource was never pulled/created remotely; re-pull.
 
 What push does not do:
 
@@ -121,6 +155,30 @@ Do not mix these up:
 - 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.
 
+## Work on this portal from another machine
+
+The project's source lives in a Fluid-provisioned git repository (kept in sync by push). To continue work elsewhere:
+
+```bash
+fluid login
+fluid portal clone <app-name>
+cd <app-name>
+fluid portal pull
+```
+
+Clone mints its own short-lived git credentials — do not hand out raw repository URLs or tokens.
+
+## Debug order when something looks wrong
+
+Work these in order and report which one failed:
+
+1. Logged in? Auth errors say `Run fluid login first`.
+2. Right directory? Push errors about missing `portal/` or `.portal-sync/` mean you are not in the pulled project (or never pulled).
+3. Local preview showing stale/missing content? Check for malformed JSON or broken references in the file you last edited (local preview drops them silently), and confirm you edited the profile the local preview serves (`default: true`).
+4. Push refused? Read the cross-reference validation errors — they name the file and the missing slug.
+5. Push partially failed? Fix the reported phase error and rerun; the snapshot only advanced for files that succeeded.
+6. Users do not see the change? Push updates the draft only — create/activate a version.
+
 ## 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.