AGENTS.md

1# apps/landing-page/AGENTS.md
2 
3Follow the root `AGENTS.md` and `apps/AGENTS.md` first. This file only
4records module-level boundaries for `apps/landing-page/`.
5 
6## Purpose
7 
8`apps/landing-page` is a stand-alone static Astro site that renders
9the Open Design marketing surface in the **Atelier Zero** style and
10ships a public plugin library plus compatibility/detail catalog pages for
11repository skills, design templates, design systems, craft principles, and
12legacy live-artifact templates.
13 
14Tightly coupled with:
15 
16- Design template: `design-templates/open-design-landing/` — agent workflow + the source-of-truth
17  `example.html` known-good rendering for the homepage hero.
18- Design system: `design-systems/atelier-zero/DESIGN.md` — token spec.
19- Image assets: `design-templates/open-design-landing/assets/*.png` are uploaded to
20  Cloudflare R2 (`open-design-static`) and served through
21  `static.open-design.ai` with Image Resizing (`format=auto`). Do not
22  commit local mirrored PNGs into `apps/landing-page/public/assets/`.
23 
24## What it is
25 
26- Astro static output. Its catalog route groups are:
27  - `/` — Atelier Zero homepage (`app/pages/index.astro`).
28  - `/plugins/` — primary public discovery hub, with `/plugins/templates/`,
29    `/plugins/skills/`, `/plugins/systems/`, `/plugins/craft/`, and plugin
30    detail/search/preview routes. The hub reads bundled manifests from
31    `plugins/_official/` and mirrors the in-app plugin taxonomy.
32  - Direct `/skills/`, `/systems/`, `/craft/`, and `/templates/` catalog,
33    facet, and detail routes remain for compatibility and deep links. The
34    template catalog is primarily `design-templates/*/SKILL.md`; legacy
35    `templates/live-artifacts/*/README.md` entries remain compatibility records.
36- Content sources are **never** mirrored into this app. Astro content
37  collections (`app/content.config.ts`) glob the canonical Markdown
38  bundles in the repo root at build time. When a contributor adds or
39  edits a `SKILL.md`/`DESIGN.md` or plugin manifest, the next build picks it up — no
40  intermediate "register your skill here" step.
41- The shaped data layer lives in `app/_lib/catalog.ts`. Page templates
42  import shaped records from there and never re-parse Markdown in JSX.
43- React is used only at build time (`renderToStaticMarkup`) for
44  `app/page.tsx` and the shared `Header`. The output ships
45  CDN-ready HTML/CSS plus a small inline enhancement script;
46  no React runtime ships to browsers.
47- All styles split between `app/globals.css` (homepage, kept in
48  lockstep with `design-templates/open-design-landing/example.html`) and
49  `app/sub-pages.css` (catalog/facet/detail pages).
50- All page imagery is referenced through `app/image-assets.ts`, which
51  builds Cloudflare Image Resizing URLs for the R2 originals.
52- Per-skill / per-template thumbnails are rendered offline by
53  `scripts/generate-previews.ts` (Playwright). Output lives in
54  `public/previews/<bucket>/<slug>.<ext>` and is **gitignored** — CI
55  regenerates on every deploy. The script preserves the actual file
56  extension so a future sharp/webp post-processor will work without
57  touching the data layer.
58 
59## What it is NOT
60 
61- Not part of `apps/web`. The web app is the product surface; the
62  landing page is a marketing surface. They share design tokens but
63  not state, routes, or runtime.
64- Not connected to `apps/daemon`. There is no `/api`, no `/artifacts`,
65  no `/frames` — no proxy to set up.
66- Not a CMS. Content authors edit canonical sources in `skills/`,
67  `design-templates/`, `design-systems/`, `craft/`,
68  `templates/live-artifacts/`, or `plugins/` at the repo root; the landing
69  page rebuilds against those sources and ships to Cloudflare Pages.
70 
71## Boundary constraints
72 
73- Must remain a static Astro output.
74- Must not import from `@open-design/web`, `@open-design/daemon`,
75  `@open-design/desktop`, `@open-design/sidecar*`, or
76  `@open-design/contracts`. Those are product runtime concerns.
77- Must not introduce a `src/` shell — keep all source under `app/`.
78  Component bundles live in `app/_components/<name>.{tsx,astro}`.
79- Must not depend on any non-Google web font.
80- Visible "X skills" / "Y systems" claims must read from
81  `getCatalogCounts()` — never hardcode. The hero, capabilities cards,
82  labs pills, selected-work fractions, and footer Library all derive
83  from the same call so a fresh content edit can never publish
84  contradictory totals. The homepage `<meta name="description">` is
85  intentionally scenario-focused and no longer states catalog totals, so
86  it is not a count-backed surface; `getHomeSeo()` still accepts the
87  counts and its `{skills}`/`{systems}` substitution stays as a no-op
88  hook, so if the description ever surfaces a count again it must route
89  through `getCatalogCounts()`.
90- When the canonical `design-templates/open-design-landing/example.html`
91  changes, the corresponding section JSX in `app/page.tsx` and rules
92  in `app/globals.css` must be updated to match. Those two files are
93  kept in lockstep; the rest of the landing-page sources are not.
94- Content-collection schemas in `app/content.config.ts` stay loose
95  (`passthrough()`). Validation lives at render time so vendored
96  upstream Markdown (e.g., `guizang-ppt`) doesn't break the build
97  when an author uses a slightly different `od:` key.
98 
99## Deploy contract (staging → manual production)
100 
101Deploys are split across **two Cloudflare Pages projects** so a merge to
102`main` can never publish to the live site on its own:
103 
104- Production project `open-design-landing` → `open-design.ai`.
105- Staging project `open-design-landing-staging` → `staging.open-design.ai`.
106 
107The safety gate is project separation: only the manual production workflow
108ever names the production project.
109 
110- `.github/workflows/landing-page-staging.yml` runs on push to `main` and
111  deploys to the **staging project** (`open-design-landing-staging`,
112  `staging.open-design.ai`).
113- `.github/workflows/landing-page-production.yml` is **manual**
114  (`workflow_dispatch`) and is the only workflow that names the production
115  project (`open-design-landing`, `open-design.ai`). Gate it with required
116  reviewers on the GitHub `production` environment.
117- `.github/workflows/landing-page-ci.yml` runs on PRs: it validates the build
118  and, for same-repo branches, deploys a per-PR preview into the staging
119  project (`--branch=pr-<number>` →
120  `pr-<number>.open-design-landing-staging.pages.dev`) and comments the URL.
121 
122The staging workflow triggers when **any** of these change:
123 
124- `apps/landing-page/**`
125- `design-templates/open-design-landing/**`
126- `design-templates/**`
127- `skills/**`
128- `design-systems/**`
129- `craft/**`
130- `templates/**`
131- `plugins/**`
132- `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`
133- the workflow files themselves
134 
135A push that only edits a catalog source or bundled plugin manifest MUST trigger
136the staging workflow. If it does not, the `paths:` filter has drifted from the
137build-time readers and the staged site will fall behind silently.
138 
139## Common commands
140 
141```bash
142pnpm --filter @open-design/landing-page dev          # http://127.0.0.1:17574
143pnpm --filter @open-design/landing-page typecheck
144pnpm --filter @open-design/landing-page previews     # render thumbnails
145pnpm --filter @open-design/landing-page build        # static export → out/
146```
147 
148## When to update this app
149 
150- Added/edited a skill, design template, `DESIGN.md`, craft principle,
151  live-artifact compatibility template, or bundled plugin manifest at the
152  repo root → no landing-page edit required; CI
153  rebuilds and re-renders thumbnails on the next push to `main`.
154- Adding a new top-level route group (e.g. `/playbooks/`) → add an
155  Astro page directory under `app/pages/`, a content collection in
156  `app/content.config.ts`, a shaping function in `app/_lib/catalog.ts`,
157  and route entries that match the existing index/detail/facet pattern.
158- New section added to the canonical landing page → port it into
159  `app/page.tsx` and `app/globals.css` keeping lockstep with
160  `design-templates/open-design-landing/example.html`.
161- Brand re-keying for a non-Open-Design tenant → fork the app, update
162  copy, swap PNGs. Do not parameterize this app for multi-tenancy.
163