@velocity-astro/cms-astro 0.1.0-beta.1 → 0.1.0-beta.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/agents/cms.md +145 -0
  2. package/agents/skills/cms-add-content-type/SKILL.md +81 -0
  3. package/agents/skills/cms-add-form/SKILL.md +85 -0
  4. package/agents/skills/cms-add-section/SKILL.md +97 -0
  5. package/agents/skills/cms-add-to-site/SKILL.md +57 -0
  6. package/agents/skills/cms-connect-page/SKILL.md +64 -0
  7. package/agents/skills/cms-deploy/SKILL.md +64 -0
  8. package/agents/skills/cms-import-content/SKILL.md +63 -0
  9. package/agents/skills/cms-set-up-crm/SKILL.md +53 -0
  10. package/agents/skills/cms-write-plugin/SKILL.md +81 -0
  11. package/dist/admin-files.d.ts +2 -2
  12. package/dist/admin-files.d.ts.map +1 -1
  13. package/dist/admin-files.js +13 -7
  14. package/dist/admin-files.js.map +1 -1
  15. package/dist/agent-files.d.ts +23 -0
  16. package/dist/agent-files.d.ts.map +1 -0
  17. package/dist/agent-files.js +84 -0
  18. package/dist/agent-files.js.map +1 -0
  19. package/dist/challenge.d.ts +35 -0
  20. package/dist/challenge.d.ts.map +1 -0
  21. package/dist/challenge.js +84 -0
  22. package/dist/challenge.js.map +1 -0
  23. package/dist/check.d.ts +38 -0
  24. package/dist/check.d.ts.map +1 -0
  25. package/dist/check.js +194 -0
  26. package/dist/check.js.map +1 -0
  27. package/dist/cli-content.d.ts +22 -0
  28. package/dist/cli-content.d.ts.map +1 -0
  29. package/dist/cli-content.js +309 -0
  30. package/dist/cli-content.js.map +1 -0
  31. package/dist/cli.d.ts +3 -0
  32. package/dist/cli.d.ts.map +1 -1
  33. package/dist/cli.js +130 -6
  34. package/dist/cli.js.map +1 -1
  35. package/dist/connection.d.ts +1 -0
  36. package/dist/connection.d.ts.map +1 -1
  37. package/dist/connection.js +31 -6
  38. package/dist/connection.js.map +1 -1
  39. package/dist/editor.d.ts +2 -0
  40. package/dist/editor.d.ts.map +1 -1
  41. package/dist/editor.js +10 -1
  42. package/dist/editor.js.map +1 -1
  43. package/dist/form-post.d.ts +9 -1
  44. package/dist/form-post.d.ts.map +1 -1
  45. package/dist/form-post.js +10 -3
  46. package/dist/form-post.js.map +1 -1
  47. package/dist/hosted.d.ts +76 -0
  48. package/dist/hosted.d.ts.map +1 -0
  49. package/dist/hosted.js +104 -0
  50. package/dist/hosted.js.map +1 -0
  51. package/dist/image-optimizer.d.ts +35 -0
  52. package/dist/image-optimizer.d.ts.map +1 -0
  53. package/dist/image-optimizer.js +76 -0
  54. package/dist/image-optimizer.js.map +1 -0
  55. package/dist/import-files.d.ts +30 -0
  56. package/dist/import-files.d.ts.map +1 -0
  57. package/dist/import-files.js +100 -0
  58. package/dist/import-files.js.map +1 -0
  59. package/dist/index.d.ts +12 -3
  60. package/dist/index.d.ts.map +1 -1
  61. package/dist/index.js +12 -3
  62. package/dist/index.js.map +1 -1
  63. package/dist/init.d.ts +2 -0
  64. package/dist/init.d.ts.map +1 -1
  65. package/dist/init.js +16 -1
  66. package/dist/init.js.map +1 -1
  67. package/dist/integration.d.ts +9 -0
  68. package/dist/integration.d.ts.map +1 -1
  69. package/dist/integration.js +15 -1
  70. package/dist/integration.js.map +1 -1
  71. package/dist/link.d.ts.map +1 -1
  72. package/dist/link.js +6 -2
  73. package/dist/link.js.map +1 -1
  74. package/dist/live-loader.d.ts +7 -3
  75. package/dist/live-loader.d.ts.map +1 -1
  76. package/dist/live-loader.js +12 -6
  77. package/dist/live-loader.js.map +1 -1
  78. package/dist/media-store.d.ts +15 -0
  79. package/dist/media-store.d.ts.map +1 -1
  80. package/dist/media-store.js +26 -2
  81. package/dist/media-store.js.map +1 -1
  82. package/dist/page-marks.d.ts +50 -0
  83. package/dist/page-marks.d.ts.map +1 -0
  84. package/dist/page-marks.js +90 -0
  85. package/dist/page-marks.js.map +1 -0
  86. package/dist/preview.d.ts +34 -2
  87. package/dist/preview.d.ts.map +1 -1
  88. package/dist/preview.js +81 -15
  89. package/dist/preview.js.map +1 -1
  90. package/dist/resend-mailer.d.ts +18 -1
  91. package/dist/resend-mailer.d.ts.map +1 -1
  92. package/dist/resend-mailer.js +24 -3
  93. package/dist/resend-mailer.js.map +1 -1
  94. package/dist/secret.d.ts +1 -1
  95. package/dist/secret.d.ts.map +1 -1
  96. package/dist/secret.js +3 -2
  97. package/dist/secret.js.map +1 -1
  98. package/dist/single.d.ts +18 -0
  99. package/dist/single.d.ts.map +1 -0
  100. package/dist/single.js +37 -0
  101. package/dist/single.js.map +1 -0
  102. package/dist/site-client.d.ts +37 -0
  103. package/dist/site-client.d.ts.map +1 -0
  104. package/dist/site-client.js +73 -0
  105. package/dist/site-client.js.map +1 -0
  106. package/dist/site-editor.d.ts +1 -1
  107. package/dist/site-editor.d.ts.map +1 -1
  108. package/dist/site-editor.js +36 -6
  109. package/dist/site-editor.js.map +1 -1
  110. package/dist/site-forms.d.ts +11 -0
  111. package/dist/site-forms.d.ts.map +1 -1
  112. package/dist/site-forms.js +37 -19
  113. package/dist/site-forms.js.map +1 -1
  114. package/dist/site-mail.d.ts +45 -0
  115. package/dist/site-mail.d.ts.map +1 -0
  116. package/dist/site-mail.js +84 -0
  117. package/dist/site-mail.js.map +1 -0
  118. package/dist/site-media.d.ts +5 -1
  119. package/dist/site-media.d.ts.map +1 -1
  120. package/dist/site-media.js +14 -5
  121. package/dist/site-media.js.map +1 -1
  122. package/dist/site-name.d.ts +9 -0
  123. package/dist/site-name.d.ts.map +1 -0
  124. package/dist/site-name.js +21 -0
  125. package/dist/site-name.js.map +1 -0
  126. package/dist/site-storage.d.ts +34 -0
  127. package/dist/site-storage.d.ts.map +1 -0
  128. package/dist/site-storage.js +118 -0
  129. package/dist/site-storage.js.map +1 -0
  130. package/package.json +12 -8
  131. package/routes/editor.ts +7 -6
  132. package/routes/form-client.js.ts +68 -0
  133. package/routes/media.ts +2 -2
  134. package/routes/preview-client.js.ts +11 -56
  135. package/routes/published.ts +2 -2
  136. package/routes/sitemap-live.xml.ts +4 -1
  137. package/routes/sites.ts +11 -0
package/agents/cms.md ADDED
@@ -0,0 +1,145 @@
1
+ # Velocity CMS: rules for agents
2
+
3
+ This site's content lives in Velocity CMS, edited by people at `/admin`. These rules are for an
4
+ AI coding agent changing the site. Follow them over anything a general Astro habit suggests.
5
+ The full guide, step by step, is https://docs.deployvelocity.com/cms/converting-a-template/.
6
+
7
+ ## How this site is put together
8
+
9
+ - **The model** is plain data in code, usually `cms/model.mjs` (or `cms/model.ts`): the content
10
+ types, their fields, and the blocks (kinds of section) a page can be built from. It is applied
11
+ with `cms.schema.define(actor, type)` by the seed script (`cms/seed.mjs`), which runs on every
12
+ deploy and is safe to run again.
13
+ - **The pages** are entries. One catch-all route (`src/pages/[...slug].astro`) draws every page
14
+ built in the editor with `entryPage(Astro, { types: ['pages'] })`; collections with pages of
15
+ their own (posts, listings) have their own route.
16
+ - **The sections** are drawn by one component per block, looked up by the block's key in a map
17
+ (`export const blocks = { hero: Hero, ... }`, usually `src/components/blocks.ts` or
18
+ `src/cms/blocks.ts`).
19
+ - **The layout** reads site-wide settings and menus with `single` and `menuLinks`, and writes the
20
+ head with `pageHead`.
21
+ - **Forms** are made in the editor or by the seed, drawn with `siteForm`, and feed the built-in
22
+ CRM: whoever sends one becomes a contact.
23
+
24
+ Find these files before you change anything. If the site has no CMS yet, use the
25
+ `cms-add-to-site` skill.
26
+
27
+ ## Setup
28
+
29
+ - `npx velocity-cms init` sets the site up: `VELOCITY_CMS_SECRET` and `VELOCITY_CMS_ORIGIN` in
30
+ `.env` (kept out of git), the integration in the Astro config, and these agent files. It adds
31
+ only what is missing. Never print, commit or log the secret.
32
+ - The site needs a server adapter, and `site` set to its address before it is deployed.
33
+ - `npx velocity-cms agents` brings this file and the `cms-*` skills up to date after the CMS is
34
+ upgraded. Keep your own notes in `AGENTS.md`, not here: this file is replaced.
35
+
36
+ ## Content types
37
+
38
+ - **Describe types in code and apply them with `schema.define`**, never by hand in the database.
39
+ A field keeps its id by key, so content stays when the model changes.
40
+ - **Field ids are permanent.** Content is stored by field id. Renaming a key makes a new field,
41
+ and the old one's data is kept but hidden. Change labels freely; change keys only on purpose.
42
+ - A field is `{ key, type, label, help?, required?, translated?, options? }`. Keys start with a
43
+ lowercase letter. A list's `min` and `max` go in `options`, beside `of`.
44
+ - Field types: `text`, `number`, `boolean`, `date`, `url`, `email`, `phone`, `select`, `color`,
45
+ `font`, `reference`, `image`, `richtext`, `group`, `list`, `blocks`, `link`, `form`, and any a
46
+ plugin adds. `velocity-cms type <key>` prints a type in full.
47
+ - A type names the field its entries are called by (`titleField`) and how the editor lays the
48
+ fields out (`sections`). `urlPattern` says where its entries live (`/blog/[slug]`;
49
+ `/[...slug]` for pages, where the slug `index` is the home page).
50
+ - Set `forDeals: true` on a type people enquire about (listings, services), so a form on its
51
+ page can start a deal about the entry.
52
+
53
+ ## Sections
54
+
55
+ - **A page is sections of data, never markup.** A block is `{ key, label, description, icon,
56
+ group, thumbnail?, fields }` in the model, and a component of the same key in the block map.
57
+ Both must exist: a block with no component is left off every page.
58
+ - **A look is a named choice.** Never a free colour, size or class. Use a `select` field with
59
+ `choices`, `labels` and, for colours, `swatches` (hex or a CSS colour function). The
60
+ component decides what each name looks like. Site-wide colours and fonts are `color` and
61
+ `font` fields of a settings page (the Theme), never per section.
62
+ - A block that stops being described is retired, not deleted: its sections are kept and left
63
+ off the site.
64
+ - A block may hold sections (a `blocks` field inside it, such as columns). Mark each place with
65
+ `slotMark` in the component.
66
+ - Draw a section's values from its props, every prop optional. Wrap each section with
67
+ `sectionMark(section.id, section.data)` and mark the element showing a field with
68
+ `fieldMark('key')`, so the visual editor can find it. Both add nothing to a visitor's page.
69
+
70
+ ## Live pages
71
+
72
+ - **Every page that reads the CMS says `export const prerender = false`**, including pages that
73
+ read it only through the layout (menus, settings). A prerendered page never sees a publish,
74
+ cannot show a preview and cannot be edited on the page. Don't set `output: 'server'`.
75
+ - Those pages are cached under the `cms` tag (`routeRules: { '/[...path]': { maxAge: 86400,
76
+ tags: ['cms'] } }` with a `cache` provider), and a publish clears it. A list read with
77
+ `getLiveCollection` calls `Astro.cache.set(cacheHint)`.
78
+ - **Never add a rebuild or a deploy to publishing.** A publish is visible about a second later.
79
+
80
+ ## Template helpers
81
+
82
+ All from `@velocity-astro/cms-astro`. Each never throws for missing content and answers with
83
+ nothing, so the template keeps its own values as the fallback.
84
+
85
+ | Helper | What it gives the page |
86
+ |---|---|
87
+ | `entryPage(Astro, { types })` | The entry whose page is at this address: `{ entry: { data } }`, values by key, sections as `{ id, block, data }`. |
88
+ | `single(Astro, 'settings')` | A single page's values by key (name, logo, phone, theme). |
89
+ | `menuLinks(Astro, { type, field })` | A menu people edit, as `{ label, href, columns? }` links. |
90
+ | `linkTo(Astro, value)` | Where a `link` field leads today, or nothing. |
91
+ | `siteForm(Astro, { id })` or `siteForm(Astro, 'key')` | A form to draw: fields, `action`, `hidden`, `trap`. |
92
+ | `pageHead(Astro, { title, description })` | The title, description and robots the page writes, after plugins. Call it in the layout. |
93
+ | `cmsLiveLoader({ type })` | A live collection for lists (`getLiveCollection`, `getLiveEntry`). |
94
+
95
+ ## Drafts never leak
96
+
97
+ - Read content only through the helpers above or the live loader. They show the published
98
+ version to visitors and the draft only in a preview. Don't open the database, call
99
+ `sharedConnection` or `cms.content` from a page.
100
+ - Nothing that shows a draft may be cached or feed search, the sitemap or share images.
101
+
102
+ ## Forms
103
+
104
+ - A form is `{ key, label, fields, submitLabel?, success?, notify?, contact?, startsDeal? }`.
105
+ `contact` names the fields that hold the sender's name, email and phone: that is what makes
106
+ the sender a contact in the CRM. Add a form the site lacks in the seed (once it exists, it is
107
+ the editor's), or with the `create_form` tool.
108
+ - Keep the template's own design for a form: toggles, steps, pickers. Draw its fields from
109
+ `siteForm` and post to `form.action` with `form.hidden` and the `form.trap` field. Load
110
+ `FORM_SCRIPT` to send it in place. A section that offers a form stores the form's id in a
111
+ field of type `form`; its component must call `siteForm`.
112
+ - **What a visitor sends is personal data.** It never reaches a page, a cache, the search index,
113
+ a log or a commit. Neither does a contact, a deal or a note.
114
+
115
+ ## Plugins
116
+
117
+ - Before writing one, check the plugins that ship (webhooks, Mailchimp, Slack, HubSpot, SEO):
118
+ an owner switches them on under Plugins.
119
+ - A plugin is `definePlugin({ name, apiVersion, label, version, permissions, setup })`, named in
120
+ `velocityCms({ plugins })`. Declare the fewest permissions. A key or password is a secret
121
+ (`secrets`), never a setting. Work that reaches another service goes through `cms.tasks`, and
122
+ only to a public `https` address.
123
+
124
+ ## Working with content
125
+
126
+ - An agent reaches content with an access token: an owner makes one in the editor (Settings,
127
+ Access tokens) or with `npx velocity-cms token "<what it is for>" --save`, which writes
128
+ `VELOCITY_CMS_TOKEN` to `.env`. Never commit or print a token.
129
+ - `npx velocity-cms types | entries | entry | create | update | publish | import | export |
130
+ upload | forms | pipeline` work over the site's API. `npx velocity-cms mcp` is an MCP server
131
+ for an agent on this computer, and every site serves the same tools at `/api/cms/mcp`.
132
+ - Values are written by field key. Formatted text takes a string or `{ "markdown": "..." }`. A
133
+ page is laid out from the blocks its type allows (`list_blocks`, `add_section`,
134
+ `set_sections`), with their own fields and named looks. For an idea no block can show, make a
135
+ new one in code (`cms-add-section`); `design_new_section` gives the theme and blocks to start from.
136
+ - What a token writes is a draft unless the token may publish. Contacts, deals and submissions
137
+ are there only when the token was allowed personal data.
138
+
139
+ ## Before you say you're done
140
+
141
+ 1. Run the seed if the model changed, then `npx velocity-cms check`. Fix every error it names.
142
+ 2. Build the site (`astro build`, or the site's own validate script).
143
+ 3. Open each page you changed with the dev server running, and the editor at `/admin` beside it.
144
+ 4. Tell the person what is still a placeholder or needs their hand: a mail service's key, a
145
+ domain, an owner to invite, a draft to publish.
@@ -0,0 +1,81 @@
1
+ ---
2
+ name: cms-add-content-type
3
+ description: Add a kind of content to a site on Velocity CMS (case studies, team members, listings, services, events) or a field to one, described in code and applied with schema.define, with its list and detail pages rendered live. Use when asked to add a content type, a collection, a post type, or a field such as square footage.
4
+ ---
5
+
6
+ # Add a content type or a field
7
+
8
+ Read `.agents/cms.md` first. This replaces the plain Astro way (a folder of Markdown files and
9
+ a `content.config.ts` collection) on a site whose content lives in the CMS.
10
+
11
+ ## 1. Describe it in the model
12
+
13
+ Open the site's model (usually `cms/model.mjs`) and add the type beside the others, with the
14
+ site's own helpers if it has them:
15
+
16
+ ```js
17
+ const caseStudies = {
18
+ key: 'case-studies',
19
+ kind: 'collection', // or 'single' for one page of settings or a menu
20
+ label: { en: 'Case studies' },
21
+ urlPattern: '/work/[slug]', // leave out for content with no page of its own
22
+ titleField: 'title',
23
+ fields: [
24
+ { key: 'title', type: 'text', label: { en: 'Title' }, required: true },
25
+ { key: 'client', type: 'text', label: { en: 'Client' } },
26
+ { key: 'cover', type: 'image', label: { en: 'Cover' } },
27
+ { key: 'summary', type: 'text', label: { en: 'Summary' }, options: { multiline: true } },
28
+ { key: 'body', type: 'richtext', label: { en: 'Story' }, required: true },
29
+ ],
30
+ sections: [
31
+ { key: 'story', label: { en: 'Story' }, fields: ['title', 'body'] },
32
+ { key: 'about', label: { en: 'About' }, fields: ['client', 'cover', 'summary'], aside: true },
33
+ ],
34
+ };
35
+ export const model = [/* ...the others, */ caseStudies];
36
+ ```
37
+
38
+ - Every language the site has gets a label (`{ en, es }`). Add `localizedUrlPatterns` for pages
39
+ in other languages.
40
+ - A choice among fixed values is a `select` with `choices` and `labels`. A link to another entry
41
+ is a `link` field. Repeated items are a `list` of a `group`.
42
+ - **To add a field to a type that has content**, add it to the list. Never rename a key to
43
+ "fix" it: that is a new field, and the old content is hidden. Never remove a field to change
44
+ its type; add a new key.
45
+ - A type people enquire about takes `forDeals: true`. A single page of site settings takes
46
+ `inSettings: true` (and `siteNameField` for the field that holds the site's name).
47
+
48
+ ## 2. Apply it
49
+
50
+ Run the seed (`npm run seed`, or `node --env-file-if-exists=.env cms/seed.mjs`). It calls
51
+ `schema.define` for every type. Check with `npx velocity-cms type case-studies`.
52
+
53
+ ## 3. Pages
54
+
55
+ For a type with `urlPattern`:
56
+
57
+ 1. A live collection in `src/live.config.ts`:
58
+ `'case-studies': defineLiveCollection({ loader: cmsLiveLoader({ type: 'case-studies' }) })`.
59
+ 2. The list page, such as `src/pages/work/index.astro`, with `export const prerender = false`,
60
+ reading `getLiveCollection('case-studies')` and calling `Astro.cache.set(cacheHint)`.
61
+ 3. The detail page, such as `src/pages/work/[slug].astro`, with `export const prerender = false`
62
+ and `const found = await entryPage(Astro, { types: ['case-studies'] })`, answering 404 when
63
+ nothing is found. Values are `found.entry.data`, by key. Formatted text is `{ html }`: render
64
+ it with `set:html={body.html}` (it is escaped already). An image field holds the image's
65
+ name: `uploadedImage(name)` gives an upload's `url`, `width` and `height`; an image the
66
+ template ships is looked up by file name, as the site's other pages do.
67
+ 4. Add the type's key to `velocityCms({ entryPages: [...] })` only if the catch-all route draws
68
+ it; give it its own route otherwise. Add the list to the nav through the menu in the CMS,
69
+ not by hard-coding a link, if the site's menu is in the CMS.
70
+ 5. Write strings a visitor reads that are not content (headings like "More work") the way the
71
+ site already does (its translations), not hard-coded.
72
+
73
+ ## 4. Sample content
74
+
75
+ If the site is new or the type is empty, add one or two entries so the pages show something:
76
+ in the seed (only when the database is empty), or with `npx velocity-cms create`. Never
77
+ publish sample content on a live site without asking.
78
+
79
+ ## 5. Check
80
+
81
+ `npx velocity-cms check`, then build and open both pages with the dev server running.
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: cms-add-form
3
+ description: Build a form on a Velocity CMS site that feeds the built-in CRM (contact, quote, tour request, booking), keeping the template's own design (steps, toggles, pickers), posting through siteForm, naming the sender's name, email and phone, filling custom fields and starting deals. Use when asked to build or connect a form, make the contact form work, or send leads to the CRM.
4
+ ---
5
+
6
+ # Build a form that feeds the CRM
7
+
8
+ Read `.agents/cms.md` first ("Forms"). On a site with the CMS, forms are CMS forms: what is
9
+ sent is kept under Forms in the editor, the people named are emailed, and the sender becomes a
10
+ contact. Don't wire an Astro Action or a third-party form service for it.
11
+
12
+ ## 1. Describe the form
13
+
14
+ Look at the design first: every field, step, toggle and picker. Each answer a visitor gives is a
15
+ field of a kind they can fill in: `text` (`multiline`, `maxLength`), `email`, `phone`, `number`,
16
+ `date`, `select` (`choices`, `labels`), `boolean`, `url`.
17
+
18
+ ```js
19
+ // in the seed's forms, added only when the site has no form with this key
20
+ {
21
+ key: 'tour',
22
+ label: { en: 'Schedule a tour' },
23
+ fields: [
24
+ { key: 'name', type: 'text', label: { en: 'Your name' }, required: true, options: { maxLength: 80 } },
25
+ { key: 'email', type: 'email', label: { en: 'Email' }, required: true },
26
+ { key: 'phone', type: 'phone', label: { en: 'Phone' } },
27
+ { key: 'day', type: 'date', label: { en: 'Preferred day' } },
28
+ { key: 'time', type: 'select', label: { en: 'Time' }, options: { choices: ['morning', 'afternoon'], labels: { morning: { en: 'Morning' }, afternoon: { en: 'Afternoon' } } } },
29
+ { key: 'virtual', type: 'boolean', label: { en: 'A video tour is fine' } },
30
+ ],
31
+ submitLabel: { en: 'Request a tour' },
32
+ success: { en: 'Thanks. We will confirm your tour by email.' },
33
+ contact: { name: 'name', email: 'email', phone: 'phone' }, // what makes the sender a contact
34
+ startsDeal: true, // on a listing's page: a deal about the listing
35
+ retentionDays: 365,
36
+ }
37
+ ```
38
+
39
+ - `contact` is what ties a submission to a person. Without an email field named there, nobody
40
+ becomes a contact.
41
+ - `startsDeal` needs the page's type to have `forDeals: true`.
42
+ - `fills` maps a form field's key to a contact custom field's id (see `cms-set-up-crm`).
43
+ - `notify` lists who is emailed. Ask the person for the addresses; never invent them.
44
+ - On a live site, `create_form` (MCP) makes the form without a deploy. Once a form exists it is
45
+ the editor's: change it there, not in the seed.
46
+
47
+ ## 2. Draw it with the template's design
48
+
49
+ In the component (a block with a `form` field, or a fixed place on a page):
50
+
51
+ ```astro
52
+ ---
53
+ import { FORM_SCRIPT, siteForm } from '@velocity-astro/cms-astro';
54
+ const form = await siteForm(Astro, 'tour'); // or siteForm(Astro, { id }) from a form field
55
+ ---
56
+ {form && (
57
+ <form action={form.action} method="post" data-cms-form data-cms-form-failed="That could not be sent. Please try again.">
58
+ {Object.entries(form.hidden).map(([name, value]) => <input type="hidden" name={name} value={value} />)}
59
+ ...the template's own markup, each input named by its field's key...
60
+ <p data-cms-form-error="email" role="alert" hidden></p>
61
+ <div class="trap" aria-hidden="true"><input type="text" name={form.trap} tabindex="-1" autocomplete="off" /></div>
62
+ <button type="submit" data-cms-form-sending="Sending…">Request a tour</button>
63
+ <p role="status" data-cms-form-status hidden></p>
64
+ </form>
65
+ )}
66
+ <script is:inline type="module" src={FORM_SCRIPT}></script>
67
+ ```
68
+
69
+ - Keep steps, toggles and pickers: they are presentation. What is posted is one value per field
70
+ key (a toggle posts `on`, a day picker posts `YYYY-MM-DD`).
71
+ - On an entry's page, `siteForm(Astro, 'tour', { about })` says which entry it is about, signed,
72
+ so a deal can be started about it. Never trust a hidden field the visitor could change for that.
73
+ - A form that is closed or gone answers `null`: leave the section out, never break the page.
74
+ - A page that draws a form says `export const prerender = false`.
75
+
76
+ ## 3. Never
77
+
78
+ - Never put what a visitor sent on a page, in a log, in a cache or in a commit.
79
+ - Never email the visitor; only the addresses the form names.
80
+
81
+ ## 4. Check
82
+
83
+ `npx velocity-cms check` (it fails when a section offers a form its component never draws).
84
+ Then send the form on the dev server and look under Forms and Contacts in `/admin`. Tell the
85
+ person email notices need a mail service (Settings, Email).
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: cms-add-section
3
+ description: Add a kind of section (a block) that editors can add to pages in Velocity CMS, such as a pricing table, a gallery or testimonials: its fields in the model, its component built from the site's own components, the block map entry, and named looks instead of free colours. Use when asked to add a section, a block, or something editors can put on pages.
4
+ ---
5
+
6
+ # Add a section editors can use
7
+
8
+ Read `.agents/cms.md` first ("Sections"). A section is data: the model describes the block and
9
+ its fields, a component draws it, and the editor only ever chooses among what you describe.
10
+
11
+ ## 1. Look before you add
12
+
13
+ - Read the model's existing blocks (usually `cms/model.mjs`, a `blocks` list) and the block map
14
+ (`export const blocks = { ... }`, usually `src/components/blocks.ts` or `src/cms/blocks.ts`).
15
+ - If an existing block differs from what is asked only in colour, alignment or image side, add a
16
+ `select` look to it instead of a new block.
17
+ - Find the site's own components for the job (cards, grids, buttons). The section must look
18
+ like the rest of the site.
19
+
20
+ ## 2. Describe the block
21
+
22
+ ```js
23
+ const pricing = {
24
+ key: 'pricing', // what the component is looked up by; never change it later
25
+ label: { en: 'Pricing' },
26
+ description: { en: 'Two to four plans side by side, one marked as the best value.' },
27
+ icon: 'badge-dollar-sign', // a Lucide icon name
28
+ group: 'Sections',
29
+ // thumbnail: '/cms/blocks/pricing.webp', // a picture for the picker, if the site has them
30
+ fields: [
31
+ { key: 'title', type: 'text', label: { en: 'Title' } },
32
+ { key: 'plans', type: 'list', label: { en: 'Plans' }, required: true, options: {
33
+ of: { type: 'group', options: { fields: [
34
+ { key: 'name', type: 'text', label: { en: 'Name' }, required: true },
35
+ { key: 'price', type: 'text', label: { en: 'Price' }, required: true },
36
+ { key: 'points', type: 'list', label: { en: 'What is included' }, options: { of: { type: 'text', options: {} } } },
37
+ { key: 'featured', type: 'boolean', label: { en: 'Best value' } },
38
+ { key: 'button', type: 'link', label: { en: 'Button goes to' } },
39
+ ] } },
40
+ min: 2, max: 4,
41
+ } },
42
+ { key: 'background', type: 'select', label: { en: 'Background' }, options: {
43
+ choices: ['plain', 'tinted'],
44
+ labels: { plain: { en: 'Plain' }, tinted: { en: 'Tinted' } },
45
+ swatches: { plain: '#ffffff', tinted: '#f4f1ec' },
46
+ } },
47
+ ],
48
+ };
49
+ ```
50
+
51
+ Add it to the `blocks` of every `blocks` field it belongs in (the pages type's sections field,
52
+ and a column's if it fits inside columns). Rules:
53
+
54
+ - **No free colours, sizes or classes.** A look is a `select` with named choices; `swatches`
55
+ give the editor a sample (hex, or a CSS colour function of numbers). Use the template's own
56
+ palette for the samples.
57
+ - Words a visitor reads are fields. Nothing is hard-coded in the component but structure.
58
+ - Keys start with a lowercase letter. Labels in every language the site has.
59
+
60
+ ## 3. Write the component
61
+
62
+ Beside the others (such as `src/components/blocks/Pricing.astro`), taking the block's values as
63
+ props by key, every prop optional:
64
+
65
+ ```astro
66
+ ---
67
+ import { fieldMark, linkTo } from '@velocity-astro/cms-astro';
68
+ interface Plan { name?: string; price?: string; points?: string[]; featured?: boolean; button?: unknown }
69
+ interface Props { title?: string; plans?: Plan[]; background?: 'plain' | 'tinted' }
70
+ const { title, plans = [], background = 'plain' } = Astro.props;
71
+ const links = await Promise.all(plans.map((plan) => linkTo(Astro, plan.button)));
72
+ ---
73
+ <section class:list={['band', background === 'tinted' && 'band--tinted']}>
74
+ {title && <h2 {...fieldMark('title')}>{title}</h2>}
75
+ ...draw each plan with the site's own card component, links[i]?.href for its button...
76
+ </section>
77
+ ```
78
+
79
+ - Use `fieldMark('key')` on the element that shows a field, so the visual editor finds it.
80
+ - Map each look name to the site's own classes or tokens. Never put a colour from content in a
81
+ style attribute.
82
+ - Formatted text is `{ html }`; images are names (`uploadedImage(name)`); links go through
83
+ `linkTo`, which answers with nothing for an unpublished page.
84
+ - Valid HTML only, one `<h1>` per page (a section usually starts at `<h2>`), alt text on images.
85
+
86
+ ## 4. Map it
87
+
88
+ Import the component in the block map and add `pricing: Pricing`. Then run the seed so the
89
+ block reaches the database. `npx velocity-cms type pages` shows it under the sections field.
90
+
91
+ ## 5. Check
92
+
93
+ 1. `npx velocity-cms check`: it fails when a block has no component or a component no block.
94
+ 2. Add the section to a draft page (in the editor, or `velocity-cms` / the MCP `add_section`
95
+ tool), open it beside the editor, and check every field shows and every look works, light
96
+ and dark if the site has both.
97
+ 3. If the site keeps pictures of blocks for the picker, take one for the new block.
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: cms-add-to-site
3
+ description: Add Velocity CMS to an Astro site, so people edit its content at /admin and publish live. Sets the CMS up, makes the first owner, models the site's existing content and converts the pages that show it. Use when asked to add a CMS, make the site editable, or move content into Velocity CMS.
4
+ ---
5
+
6
+ # Add the CMS to this site
7
+
8
+ Read `.agents/cms.md` once it exists (step 1 writes it). The full guide is
9
+ https://docs.deployvelocity.com/cms/converting-a-template/, and `examples/starter` in the CMS's
10
+ repository is a small site that does all of this.
11
+
12
+ ## 1. Install
13
+
14
+ 1. The site needs a server adapter. If `astro.config.*` has no `adapter`, add one for where the
15
+ site will live (`npx astro add node`, `vercel`, `netlify`, `cloudflare`).
16
+ 2. Run `npx velocity-cms init <owner email> "<owner name>"` in the site's folder. It installs
17
+ `@velocity-astro/cms-astro`, writes the secret and local address to `.env`, adds the
18
+ integration, installs `.agents/cms.md` and the `cms-*` skills, and prints a sign-in link for
19
+ the owner. Ask the person for the email and name; never invent them.
20
+ 3. If `init` printed two lines to add to the config by hand, add them.
21
+ 4. Set `site` in the config to the real address, or leave a note that it must be set before deploying.
22
+
23
+ ## 2. Audit what the site holds
24
+
25
+ Write a list before any code:
26
+
27
+ - built pages (home, about, contact) and the sections each is made of, top to bottom;
28
+ - collections (posts, projects, team, listings): anything repeated with one shape;
29
+ - site-wide settings (name, logo, phone, social links) and menus (header, footer);
30
+ - forms;
31
+ - looks a section offers (background, alignment) and the theme (brand colour, fonts).
32
+
33
+ Two sections that differ only in colour or alignment are one block with a `select` look.
34
+
35
+ ## 3. Model it
36
+
37
+ Write `cms/model.mjs` with the content types and blocks, and `cms/seed.mjs` that applies them
38
+ with `schema.define` and, in an empty database, adds the site's current words as the first
39
+ content. Follow `cms-add-content-type` for each type and `cms-add-section` for each block. Add
40
+ `"seed": "node --env-file-if-exists=.env cms/seed.mjs"` to `package.json` and run it.
41
+
42
+ ## 4. Convert the pages
43
+
44
+ Follow `cms-connect-page`: one catch-all route draws the built pages from sections, collections
45
+ get live routes, the layout reads menus and settings with `single` and `menuLinks` and writes
46
+ the head with `pageHead`. Keep every component; only the words move.
47
+
48
+ Forms: follow `cms-add-form`.
49
+
50
+ ## 5. Finish
51
+
52
+ 1. `npx velocity-cms check`, and fix every error.
53
+ 2. Build, start the dev server, open each page and `/admin` beside it. Every word a visitor sees
54
+ on a converted page should be editable there.
55
+ 3. Tell the person: the sign-in link (it works once, for ten minutes; `npx velocity-cms link
56
+ <email>` makes another), what is still a placeholder, and what they need for going live (see
57
+ `cms-deploy`).
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: cms-connect-page
3
+ description: Move a hard-coded page, header, footer or site setting of a Velocity CMS site onto content people edit, with entryPage, single, menuLinks and linkTo, keeping the template's own values as the fallback. Use when asked to make the home page, a page, the header, the footer, the menu, the logo or contact details editable.
4
+ ---
5
+
6
+ # Connect a page to CMS content
7
+
8
+ Read `.agents/cms.md` first ("Template helpers", "Live pages"). The goal: everything a visitor
9
+ sees on the page is edited in the CMS, and the page still looks exactly as it did.
10
+
11
+ ## A built page (home, about, services)
12
+
13
+ 1. List the page's sections top to bottom. For each, find a block in the model that draws it,
14
+ or add one with `cms-add-section`.
15
+ 2. Make the page an entry of the pages type: in the seed (written by key, with the page's
16
+ current words as the sample content) or with `npx velocity-cms create pages <slug> --data
17
+ '{...}'`. The home page's slug is `index`. A page under another has a slug of several parts
18
+ (`services/roofing`) when the pattern is `/[...slug]`.
19
+ 3. Delete the hard-coded `.astro` file: the catch-all route (`src/pages/[...slug].astro`, with
20
+ `entryPage(Astro, { types: ['pages'] })`) now draws it. Make sure the pages type is in
21
+ `velocityCms({ entryPages })`.
22
+ 4. Compare the page before and after, at desktop and phone widths: same sections, same order,
23
+ same words.
24
+
25
+ ## A collection's page (a post, a listing)
26
+
27
+ Its own route: `export const prerender = false`, then `entryPage(Astro, { types: ['<type>'] })`
28
+ and a 404 when nothing is found. Lists read `getLiveCollection('<type>')` and call
29
+ `Astro.cache.set(cacheHint)`.
30
+
31
+ ## The header, the footer and menus
32
+
33
+ 1. A menu is a single page with a `list` of `{ label, link }` groups (often `navigation`, field
34
+ `header`; another field for the footer). Add it to the model if it is missing.
35
+ 2. In the layout: `const edited = await menuLinks(Astro, { type: 'navigation', field: 'header' })`
36
+ and draw `edited.length > 0 ? edited : <the template's own links>`. Each link is
37
+ `{ label, href, external }`, and `columns` for a large menu.
38
+ 3. Seed the menu with the template's current links, linking to entries (`{ kind: 'entry', type,
39
+ entry: <translation group> }`) where they are pages of the site, so a renamed page keeps its link.
40
+
41
+ ## Site-wide settings (name, logo, phone, social, theme)
42
+
43
+ 1. A single page with `inSettings: true` (and `siteNameField` for the name), so it is a tab of
44
+ the editor's Settings.
45
+ 2. `const settings = await single(Astro, 'settings')`, and use each value with the template's
46
+ own as the fallback: `typeof settings?.phone === 'string' ? settings.phone : '555 0100'`.
47
+ 3. The theme (brand colour, fonts) is `color` and `font` fields of such a page, written by the
48
+ layout as CSS variables. Never per section.
49
+
50
+ ## Links and buttons
51
+
52
+ A `link` value is an entry or a typed address, never a string. `await linkTo(Astro, value)`
53
+ gives `{ href, external }` or nothing (an unpublished page): draw the button only when it answered.
54
+
55
+ ## Every page that reads the CMS
56
+
57
+ - `export const prerender = false`, including pages that read it only through the layout.
58
+ - `pageHead(Astro, { title, description })` in the layout, writing what it answers.
59
+ - Never read the database or `cms.content` directly: drafts would leak.
60
+
61
+ ## Check
62
+
63
+ `npx velocity-cms check`, build, and open the page beside `/admin` with the dev server running.
64
+ Change a word in the editor, publish, and reload: it should show at once.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: cms-deploy
3
+ description: Put a site on Velocity CMS live or self-host it: the host's settings (secret, address, database on a file or Turso, a bucket for uploads, the mailer, the scheduled publish call, a cache the servers share), the first owner, and a check that the live site answers. Use when asked to deploy, put the site live, self-host, or move it to another host.
4
+ ---
5
+
6
+ # Deploy a site on the CMS
7
+
8
+ Read `.agents/cms.md` first. A site on the CMS runs on a server: the editor, the API and live
9
+ pages need one. Velocity Cloud does all of this for the person; offer it if they would rather
10
+ not run a server.
11
+
12
+ ## 1. What the host needs
13
+
14
+ | Setting | What to put |
15
+ |---|---|
16
+ | `VELOCITY_CMS_SECRET` | 32 or more random characters (`openssl rand -base64 32`). The same value for the life of the site: sessions, preview links and saved keys depend on it. Never the one from a developer's `.env` if that was ever shared. |
17
+ | `VELOCITY_CMS_ORIGIN` | The site's address, `https://example.com`. Sign-in links lead here. Also set `site` in the Astro config. |
18
+ | `VELOCITY_CMS_DATABASE_URL` | Where the content lives. A file (`file:/data/cms.db`) works only on a server with a disk that is kept (a VPS, Fly with a volume, Railway). On Vercel, Netlify or Cloudflare use Turso: `libsql://<db>.turso.io`. |
19
+ | `VELOCITY_CMS_DATABASE_TOKEN` | The Turso database's token, for a `libsql://` address. |
20
+
21
+ Uploads, email and the spam check are set up by the owner in the editor (Settings), with keys
22
+ kept encrypted. Set them on the host instead only if the person wants them out of the editor:
23
+
24
+ - uploads: a bucket (S3, R2, B2) in Settings, Storage; on a server with a kept disk, uploads
25
+ can stay in a folder (`VELOCITY_CMS_MEDIA_DIR`);
26
+ - email: Resend in Settings, Email, or `VELOCITY_CMS_RESEND_API_KEY` and
27
+ `VELOCITY_CMS_EMAIL_FROM` on the host. Without one, sign-in links go to the server's log.
28
+
29
+ Ask the person for every key; never invent one, never commit one, never print one back.
30
+
31
+ ## 2. The adapter and the cache
32
+
33
+ - The Astro config's adapter must match the host (`@astrojs/node` standalone, `@astrojs/vercel`,
34
+ `@astrojs/netlify`, `@astrojs/cloudflare`).
35
+ - Pages are kept under the `cms` tag until a publish clears it. With one server, Astro's
36
+ `memoryCache()` is enough. With several (serverless, more than one instance), use a cache all
37
+ of them share, or a publish clears only one server's copy. Say so to the person if the host
38
+ scales out.
39
+
40
+ ## 3. Scheduled publishing
41
+
42
+ The site looks for entries due to go out on every page request. For a quiet site, have the host
43
+ call `POST /api/cms/schedule` with `Authorization: Bearer <VELOCITY_CMS_SECRET>` every few
44
+ minutes (a Vercel cron in `vercel.json`, a Netlify scheduled function, a cron on the server).
45
+
46
+ ## 4. The content on the server
47
+
48
+ 1. Run the seed against the live database once, and on every deploy (the build command or a
49
+ release step): `node cms/seed.mjs` with the host's settings. It is safe to run again and
50
+ never touches what people edited.
51
+ 2. Make the first owner against the live database: `npx velocity-cms owner <email> "<name>"`
52
+ with `VELOCITY_CMS_DATABASE_URL`, `VELOCITY_CMS_SECRET` and `VELOCITY_CMS_ORIGIN` set as on
53
+ the host. It prints a sign-in link that works once, for ten minutes.
54
+
55
+ ## 5. Check it answers
56
+
57
+ - `/` and a few pages answer 200; `/admin` shows the sign-in screen.
58
+ - `npx velocity-cms check` passes locally before the deploy.
59
+ - With a token (`VELOCITY_CMS_ORIGIN=https://example.com npx velocity-cms types`), the API
60
+ answers from the live site.
61
+ - Publish a small change in the editor and see it on the site within a few seconds.
62
+
63
+ Tell the person what they still have to do themselves: DNS, the mail service's domain, the
64
+ bucket, the owner's first sign-in.