fimo 0.11.0-staging.6 → 0.11.0-staging.8

package/assets/skills/fimo-cli/SKILL.md

@@ -58,6 +58,7 @@ A project can have multiple **envs** — each is a git branch _plus_ its own DB,
 npx fimo@latest login                          # authenticate via browser
 npx fimo@latest skills install                 # install the global Fimo skill for your AI tools
 npx fimo@latest init my-site --org <id>        # one-stop setup: sign in, create/link a project, install deps + skills. Use the org **id** from `fimo orgs list`, NOT the slug.
+npx fimo@latest init my-site --starter fimo-site@1 --org <id> --yes --no-skills  # opt-in content-led starter for a new project
 npx fimo@latest init --project-id <id> my-site # link an EXISTING project instead of creating one
 npx fimo@latest clone                          # interactively choose an existing project to clone locally
 cd my-site                                     # then load skills on demand: npx fimo@latest skills get fimo-code
@@ -77,7 +78,7 @@ The working loop is local: run the app with the project's package-manager `dev`
 
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
-- "Create a new Fimo project / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
+- "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
 - "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ load `fimo-code/references/content.md` for the JSON shape and React hooks**
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo-code/references/forms.md` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
@@ -136,6 +137,8 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Running `fimo deploy` just to get a fresh preview URL** — that's a commit + push + sandbox sync for what should be a sub-second read. Use `fimo preview url` instead. See `references/preview.md`.
 - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
 - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
+- **Using a starter on an existing project** — `--starter` is create-new only. Keep `--project-id` flows blank and use explicit content/form/label commands when changing an existing project.
+- **Treating a starter as a permanent demo tenant** — starters are opt-in seed data in the new project, not a global default. Keep starter agents manual-only; do not add schedules or webhooks unless the project owner explicitly asks for automation.
 - **Hardcoding content / strings / images in code** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's anti-patterns.
 - **Adding another deploy tool (Vercel, Netlify, Cloudflare Pages)** — Fimo handles deploys; don't bolt another platform on.
 - **Committing secrets** — hidden values use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.

package/assets/skills/fimo-cli/references/init.md

@@ -13,26 +13,51 @@ fimo init [dir] [options]
 `fimo init` runs the full onboarding in one shot:
 
 1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
-2. **Resolves the project** — with `--project-id <id>` it links an EXISTING project (clones it); without it, it creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new.
+2. **Resolves the project** — with `--project-id <id>` it links an EXISTING project (clones it); without it, it creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project.
 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
 
-| Flag                         | Required                      | Purpose                                                                                                                                            |
-| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                  |
-| `--project-id <id>`          | no                            | Link an EXISTING project instead of creating one (clones it).                                                                                      |
-| `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY. |
-| `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                            |
-| `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                |
-| `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                          |
-| `--skills` / `--no-skills`   | yes in non-TTY                | Install the global Fimo skill (or skip it).                                                                                                        |
-| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill.                                            |
-| `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                       |
-| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                  |
-| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                 |
+| Flag                         | Required                      | Purpose                                                                                                                                                        |
+| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                              |
+| `--project-id <id>`          | no                            | Link an EXISTING project instead of creating one (clones it).                                                                                                  |
+| `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.             |
+| `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                                        |
+| `--starter <id>`             | no                            | Opt-in project starter for create-new (currently `fimo-site@1`). It seeds CMS content, labels, a contact form, and manual-only agents. Rejects `--project-id`. |
+| `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                            |
+| `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                                      |
+| `--skills` / `--no-skills`   | yes in non-TTY                | Install the global Fimo skill (or skip it).                                                                                                                    |
+| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill.                                                        |
+| `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                                   |
+| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                              |
+| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                             |
 
 In a non-TTY shell the create-new path requires `[dir]`, `--install` / `--no-install`, and `--skills` / `--no-skills` (and `--org` if you have no active org and belong to multiple orgs). Without them the command exits with `Cannot prompt in a non-interactive shell.`
 
+### Non-interactive starter setup
+
+Use explicit flags when a script or agent owns the flow. `--json` gives the
+caller one stable result envelope; `--yes` is useful when running in a TTY but
+is not required in a pipe or CI shell. The starter is never selected by default.
+
+```bash
+npx fimo@latest --json init my-site \
+  --starter fimo-site@1 \
+  --org <organizationId> \
+  --no-install \
+  --no-skills \
+  --agents=none \
+  --yes
+```
+
+The command creates the project, copies the starter overlay, seeds its `HomePage`
+singleton, `contact` form, and labels in `main`, writes the form id into
+`src/forms/contact.json`, and commits the starter agents as manual-only bundles.
+`--starter` is create-new only; an existing-project command such as
+`fimo init --project-id <id> --starter fimo-site@1` fails before cloning or
+writing anything. If dependencies were skipped, install them and run
+`fimo validate` before starting the app so generated clients are present.
+
 > **Zero-install:** run `npx fimo@latest init` — no global install needed. `fimo projects create` is also an alias of `fimo init` (create-new path).
 
 For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
@@ -53,6 +78,14 @@ Pass `--project-id <id>` to link an EXISTING project instead of creating one. Th
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
 - A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
 
+When `--starter fimo-site@1` is supplied, the overlay also includes a
+content-backed homepage, `src/schemas/HomePage.json`, a `contact` form spec,
+nine English labels, and two read-only agent bundles (`site-review` and
+`content-guide`). The seed is opt-in and scoped to the new project; the default
+blank template and all existing-project flows remain unchanged. Starter agents
+declare only a manual trigger so copying them does not create schedules or
+webhooks.
+
 Nothing is written into per-agent skill dirs: the rich skills are fetched on demand via `fimo skills get <name>`, never copied into the project. `fimo init` separately installs the small global `fimo` bootstrap skill for the agents you select (machine-wide, not in the project) unless you pass `--no-skills`. For other agents' rule-file variants (`.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`), run `fimo rules sync`. See `references/agent-setup.md`.
 
 Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.

package/assets/starters/fimo-site/manifest.json

@@ -0,0 +1,64 @@
+{
+  "name": "fimo-site",
+  "version": 1,
+  "description": "A content-led site with a homepage, contact form, labels, and manual review agents.",
+  "singletons": [
+    {
+      "type": "HomePage",
+      "data": {
+        "eyebrow": "Field notes",
+        "title": "Your website, ready to edit.",
+        "intro": {
+          "type": "doc",
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [
+                {
+                  "type": "text",
+                  "text": "This starter is real website content. Edit the copy in Studio, change the code with your favorite agent, and keep both surfaces in sync."
+                }
+              ]
+            }
+          ]
+        },
+        "primaryCtaLabel": "Read the field notes",
+        "primaryCtaHref": "#stories",
+        "featured": [
+          {
+            "label": "Start here",
+            "title": "A calmer content workflow",
+            "summary": "Keep content, code, previews, and the team in one editable project.",
+            "href": "#stories"
+          },
+          {
+            "label": "For agents",
+            "title": "Build once, keep iterating",
+            "summary": "Give your coding agent a real CMS surface to work with after the first deploy.",
+            "href": "#stories"
+          },
+          {
+            "label": "For teams",
+            "title": "Make every edit reviewable",
+            "summary": "Let teammates shape the site without asking them to open a code editor.",
+            "href": "#stories"
+          }
+        ],
+        "contactHeading": "Make something useful",
+        "contactIntro": "Tell us what you are building and we will help you find the shortest path from first draft to a site your team can own."
+      }
+    }
+  ],
+  "labels": [
+    { "key": "nav.stories", "value": "Field notes", "locale": "en" },
+    { "key": "nav.contact", "value": "Start a conversation", "locale": "en" },
+    { "key": "hero.scroll", "value": "Explore the starter", "locale": "en" },
+    { "key": "contact.name", "value": "Your name", "locale": "en" },
+    { "key": "contact.email", "value": "Email address", "locale": "en" },
+    { "key": "contact.message", "value": "What are you building?", "locale": "en" },
+    { "key": "contact.submit", "value": "Send a note", "locale": "en" },
+    { "key": "contact.sent", "value": "Thanks. Your note is on its way.", "locale": "en" },
+    { "key": "contact.failed", "value": "That did not send. Please try again.", "locale": "en" }
+  ],
+  "forms": ["contact"]
+}

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/GOAL.md

@@ -0,0 +1,8 @@
+# Content guide
+
+Inspect the site's content model and homepage copy. Suggest a small editorial
+backlog that makes the site more useful to its intended audience.
+
+Return three suggestions, each with the content type or field it touches and
+why it matters. Use the existing content as evidence. Do not write files,
+change entries, or create labels.

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/capabilities.yaml

@@ -0,0 +1,2 @@
+- files:read
+- cms:read

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/config.yaml

@@ -0,0 +1,9 @@
+# Keep starter agents manual-only. Adding a schedule or webhook and pushing to
+# main registers an automation for the project.
+version: 1
+description: 'Suggest useful editorial improvements from the existing CMS content.'
+data_sources:
+  - main
+
+triggers:
+  - type: manual

package/assets/starters/fimo-site/template/.fimo/agents/site-review/GOAL.md

@@ -0,0 +1,14 @@
+# Site review
+
+Review the starter project as a teammate would before the first publish.
+
+Read the declared routes, the CMS content, the labels, and the public site.
+Return a short report with:
+
+- one thing that already feels clear;
+- the three highest-value improvements;
+- any missing content or broken route you can prove;
+- one next action that a human or coding agent can review.
+
+This is a read-only review. Do not edit files, change CMS content, create
+branches, or publish anything.

package/assets/starters/fimo-site/template/.fimo/agents/site-review/capabilities.yaml

@@ -0,0 +1,4 @@
+- files:read
+- cms:read
+- i18n:read
+- net:fetch

package/assets/starters/fimo-site/template/.fimo/agents/site-review/config.yaml

@@ -0,0 +1,9 @@
+# Keep starter agents manual-only. Adding a schedule or webhook and pushing to
+# main registers an automation for the project.
+version: 1
+description: 'Review the starter site and return a concise, read-only launch report.'
+data_sources:
+  - main
+
+triggers:
+  - type: manual

package/assets/starters/fimo-site/template/src/forms/contact.json

@@ -0,0 +1,14 @@
+{
+  "name": "contact",
+  "label": "Start a conversation",
+  "fields": {
+    "name": { "type": "text", "label": "Your name", "required": true },
+    "email": { "type": "email", "label": "Email address", "required": true },
+    "message": {
+      "type": "textarea",
+      "label": "What are you building?",
+      "required": true,
+      "validation": { "minLength": 10, "maxLength": 2000 }
+    }
+  }
+}

package/assets/starters/fimo-site/template/src/forms/contact.ts

@@ -0,0 +1,46 @@
+// AUTO-GENERATED ⚠️ — do not edit by hand
+// Source: src/forms/contact.json
+// The CLI replaces the placeholder form id while seeding the starter. `fimo
+// validate` regenerates this file from the JSON spec on later edits.
+
+import { z } from 'zod';
+
+export const FORM_ID = '__FIMO_FORM_ID__';
+
+export const ContactSchema = z.object({
+  name: z.string().min(1, 'Your name is required'),
+  email: z.string().min(1, 'Email address is required').email('Invalid email address'),
+  message: z.string().min(1, 'What are you building? is required').min(10).max(2000),
+});
+
+export type ContactData = z.infer<typeof ContactSchema>;
+
+// @ts-ignore - meta.env is a vite feature
+const base = import.meta.env.VITE_API_URL;
+
+export async function submitContact(data: ContactData): Promise<{
+  success: boolean;
+  errors?: Record<string, string>;
+}> {
+  let response: Response;
+  try {
+    response = await fetch(`${base}/forms/${FORM_ID}/submit`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+  } catch {
+    return { success: false };
+  }
+
+  if (response.ok) {
+    return { success: true };
+  }
+
+  if (response.status === 422) {
+    const json = (await response.json()) as { errors?: Record<string, string> };
+    return { success: false, errors: json.errors };
+  }
+
+  return { success: false };
+}

package/assets/starters/fimo-site/template/src/pages/Contact.tsx

@@ -0,0 +1,193 @@
+import { type FimoString, Text, useLabels } from 'fimo/ui';
+import { ArrowUpRight, Check } from 'lucide-react';
+import { type FormEvent, type ReactNode, useState } from 'react';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Spinner } from '@/components/ui/spinner';
+import { Textarea } from '@/components/ui/textarea';
+import { ContactSchema, submitContact } from '@/forms/contact';
+import { cn } from '@/lib/utils';
+import type { HomePage } from '@/schemas/HomePage';
+
+import { Bar } from './SiteContent';
+
+export function Contact({ page, loading }: { page?: HomePage; loading: boolean }) {
+  return (
+    <section id="contact" className="dark bg-background text-foreground scroll-mt-16">
+      <div className="mx-auto grid w-full max-w-6xl gap-12 px-6 py-20 lg:grid-cols-12 lg:gap-16 lg:px-10 lg:py-28">
+        <div className="lg:col-span-5">
+          {page ? (
+            <>
+              <Text
+                value={page.contactHeading}
+                as="h2"
+                className="text-4xl font-semibold tracking-[-0.03em] text-balance lg:text-5xl"
+              />
+              <Text value={page.contactIntro} as="p" className="text-muted-foreground mt-6 max-w-md leading-relaxed" />
+            </>
+          ) : (
+            <div aria-hidden>
+              <div className="grid gap-3">
+                <Bar loading={loading} className="h-10 w-4/5" />
+                <Bar loading={loading} className="h-10 w-2/5" />
+              </div>
+              <div className="mt-8 grid gap-2">
+                <Bar loading={loading} className="h-4 w-full max-w-md" />
+                <Bar loading={loading} className="h-4 w-11/12 max-w-md" />
+                <Bar loading={loading} className="h-4 w-2/3 max-w-md" />
+              </div>
+            </div>
+          )}
+        </div>
+
+        <div className="lg:col-span-7">
+          <ContactForm />
+        </div>
+      </div>
+    </section>
+  );
+}
+
+type SubmitState = 'idle' | 'submitting' | 'sent' | 'invalid' | 'failed';
+
+function ContactForm() {
+  const { t } = useLabels();
+  const [state, setState] = useState<SubmitState>('idle');
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    // `currentTarget` is cleared once the handler yields, so keep the node.
+    const form = event.currentTarget;
+    setErrors({});
+
+    const parsed = ContactSchema.safeParse(Object.fromEntries(new FormData(form)));
+    if (!parsed.success) {
+      const fieldErrors: Record<string, string> = {};
+      for (const issue of parsed.error.issues) {
+        fieldErrors[issue.path[0] as string] = issue.message;
+      }
+      setErrors(fieldErrors);
+      setState('invalid');
+      return;
+    }
+
+    setState('submitting');
+    const result = await submitContact(parsed.data);
+    if (result.success) {
+      form.reset();
+      setState('sent');
+      return;
+    }
+
+    // A rejected submission comes back with per-field messages; a network or
+    // server failure has nothing to attach to a field, so it needs its own.
+    const fieldErrors = result.errors ?? {};
+    setErrors(fieldErrors);
+    setState(Object.keys(fieldErrors).length > 0 ? 'invalid' : 'failed');
+  };
+
+  const busy = state === 'submitting';
+  const sent = state === 'sent';
+
+  return (
+    <form
+      onSubmit={handleSubmit}
+      noValidate
+      aria-busy={busy}
+      className="border-border bg-card rounded-xl border p-6 sm:p-8"
+    >
+      <div className="grid gap-6 sm:grid-cols-2">
+        <FormField id="contact-name" label={t('contact.name')} error={errors.name}>
+          <Input
+            id="contact-name"
+            name="name"
+            type="text"
+            autoComplete="name"
+            disabled={busy || sent}
+            aria-invalid={Boolean(errors.name)}
+            aria-describedby={errors.name ? 'contact-name-error' : undefined}
+          />
+        </FormField>
+
+        <FormField id="contact-email" label={t('contact.email')} error={errors.email}>
+          <Input
+            id="contact-email"
+            name="email"
+            type="email"
+            autoComplete="email"
+            disabled={busy || sent}
+            aria-invalid={Boolean(errors.email)}
+            aria-describedby={errors.email ? 'contact-email-error' : undefined}
+          />
+        </FormField>
+
+        <div className="sm:col-span-2">
+          <FormField id="contact-message" label={t('contact.message')} error={errors.message}>
+            <Textarea
+              id="contact-message"
+              name="message"
+              rows={5}
+              disabled={busy || sent}
+              aria-invalid={Boolean(errors.message)}
+              aria-describedby={errors.message ? 'contact-message-error' : undefined}
+            />
+          </FormField>
+        </div>
+      </div>
+
+      <div className="mt-8 flex flex-wrap items-center gap-x-4 gap-y-3">
+        <Button
+          type="submit"
+          size="lg"
+          disabled={busy || sent}
+          className={cn('group', state === 'invalid' && 'ring-destructive/40 ring-[3px]')}
+        >
+          {busy ? <Spinner /> : null}
+          {sent ? <Check /> : null}
+          <Text value={t('contact.submit')} />
+          {!busy && !sent ? (
+            <ArrowUpRight className="transition-transform group-hover:translate-x-0.5 group-hover:-translate-y-0.5" />
+          ) : null}
+        </Button>
+
+        {/* Both regions stay mounted and empty: a live region inserted at the same
+            moment as its text is announced unreliably. */}
+        <p role="status" className="text-muted-foreground text-sm">
+          {sent ? <Text value={t('contact.sent')} /> : null}
+        </p>
+        <p role="alert" className="text-destructive text-sm">
+          {state === 'failed' ? <Text value={t('contact.failed')} /> : null}
+        </p>
+      </div>
+    </form>
+  );
+}
+
+function FormField({
+  id,
+  label,
+  error,
+  children,
+}: {
+  id: string;
+  label: FimoString;
+  error?: string;
+  children: ReactNode;
+}) {
+  return (
+    <div className="grid gap-2">
+      <Label htmlFor={id} className="text-muted-foreground text-[11px] font-medium tracking-[0.16em] uppercase">
+        <Text value={label} />
+      </Label>
+      {children}
+      {error ? (
+        <p id={`${id}-error`} role="alert" className="text-destructive text-xs">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/assets/starters/fimo-site/template/src/pages/Index.tsx

@@ -0,0 +1,27 @@
+import HomePageContent from '@/schemas/HomePage';
+
+import { Contact } from './Contact';
+import { ContentFallback, Hero, SiteHeader, Stories } from './SiteContent';
+
+const Index = () => {
+  const { data: page, isLoading } = HomePageContent.useGet();
+
+  return (
+    <div className="bg-background text-foreground min-h-screen">
+      <SiteHeader />
+      <main>
+        {page ? (
+          <>
+            <Hero page={page} />
+            <Stories items={page.featured ?? []} />
+          </>
+        ) : (
+          <ContentFallback loading={isLoading} />
+        )}
+        <Contact page={page} loading={isLoading} />
+      </main>
+    </div>
+  );
+};
+
+export default Index;