@nebularstreams/statify 3.0.7 → 3.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebularstreams/statify",
-  "version": "3.0.7",
+  "version": "3.0.8",
   "description": "Generate Cool Landing and Documentation Pages",
   "scripts": {
     "build:app": "node tool/cli.js app",
@@ -21,6 +21,7 @@
     "src.website/*.mjs",
     "src.website/package.json",
     "src.website/package-lock.json",
+    "skill/",
     "templates/",
     "tool/cli.js",
     "readme.md"

package/skill/statify-site/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: statify-site
+description: Create or update static documentation sites and landing pages with Statify templates, Markdown, JSON page definitions, and supported website widgets. Use for websites built with @nebularstreams/statify; do not use for unrelated web frameworks.
+---
+
+# Statify Site
+
+Create a maintainable Statify source site and verify the generated output. Preserve the user's content, branding, chosen template, and existing custom widgets.
+
+## Start from the installed tool
+
+Confirm that `statify --help` works in the target project. Prefer the project's pinned dependency through an npm script or `npx --no-install statify`; do not fetch or globally install a different version without permission.
+
+For a new site, initialize one of the bundled templates:
+
+```sh
+statify init <site-directory> documentation
+statify init <site-directory> landing
+```
+
+For an existing site, inspect its `metadata.json`, `pages/`, `assets/`, and custom styles before editing. Do not reinitialize it.
+
+## Author the site
+
+Read [references/authoring.md](references/authoring.md) for the source layout, metadata conventions, links, and documentation pages.
+
+For landing pages or JSON widgets, also read [references/landing-pages.md](references/landing-pages.md). Inspect `templates/landing-rich` when advanced examples such as background video, YouTube embeds, FAQs, or nested cards are relevant.
+
+When choosing colors, typography scale, control sizes, or light/dark presentation, read [references/skins.md](references/skins.md) before editing the template's local stylesheet.
+
+Keep content factual and specific to the user's request. Treat template names, companies, URLs, analytics identifiers, contact details, and legal text as examples to replace—not facts to preserve. Preserve accurate image attribution when reusing an image.
+
+Prefer the simplest supported structure that expresses the page. Reuse the template's existing widgets and CSS conventions.
+
+Do not invent licenses, customer claims, testimonials, compliance claims, analytics IDs, legal identities, or production contact details. Mark placeholder legal content clearly and recommend appropriate review.
+
+## Build and verify
+
+Generate into a disposable output directory unless the user specifies the deployment directory:
+
+```sh
+statify folder <site-directory> <output-directory>
+```
+
+Before handing off:
+
+- Parse every edited JSON file.
+- Confirm local image, stylesheet, script, and page references resolve or are intentional deployment paths.
+- Build the complete folder, not just an individual page.
+- Inspect generated filenames and check representative HTML for the expected title, canonical URL, navigation, and content.
+- When visual inspection is available, preview at least the home page and one representative documentation or secondary page at desktop and narrow widths.
+
+Report the source directory, output directory, template/flavour used, validation performed, and any placeholders still requiring user content or assets.

package/skill/statify-site/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Statify Site"
+  short_description: "Build documentation sites and landing pages"
+  default_prompt: "Use $statify-site to create a responsive website from a Statify template."

package/skill/statify-site/references/authoring.md

@@ -0,0 +1,121 @@
+# Statify authoring
+
+## Source layout
+
+```text
+site/
+  metadata.json
+  images.json
+  pages/
+    index.md or index.json
+    nested-section/
+      index.md
+    res/
+  assets/
+    app/
+      website.css
+      website.min.js
+    res/
+      custom.css
+```
+
+`statify folder` walks `pages/` recursively. It converts `.md` and `.json` pages to matching `.html` paths, copies other files unchanged, and copies the contents of optional `assets/` into the output root.
+
+Both `pages/res/` and `assets/res/` produce `/res/...` in the output. Choose the partition that best expresses ownership:
+
+- Keep page-local resources beside the content under `pages/res/`.
+- Keep shared site resources under `assets/res/`.
+- Use other `assets/` subfolders for global output folders; for example, `assets/app/` becomes `/app/`.
+
+Do not create the same output path in both trees. When editing an existing site, preserve its chosen partition unless there is a concrete reason to reorganize it.
+
+## Metadata
+
+Start from the selected template's `metadata.json` because the renderer expects its established shape. Update at least:
+
+- `title` and `description`
+- `canonical`
+- social `image`
+- `site.name`, `site.url`, and `site.domain`
+- `author` and `publisher`
+- icons, stylesheets, scripts, and font paths in `head`
+- navigation and breadcrumb URLs
+
+Keep the canonical origin consistent. `site.domain` is required by the renderer. Use `example.com` only for an explicitly fictional or unfinished site.
+
+`head` entries use `t` for the HTML tag and ordinary element attributes for the remaining fields:
+
+```json
+{
+  "t": "link",
+  "rel": "stylesheet",
+  "href": "app/website.css"
+}
+```
+
+Navigation links live in `navibar.links`. A separator entry is represented by:
+
+```json
+{
+  "SPACER": {
+    "separator": true
+  }
+}
+```
+
+## Documentation pages
+
+Write documentation as Markdown beneath `pages/`. Headings create the page outline. Relative Markdown links are rewritten to generated page routes, so prefer:
+
+```markdown
+[Installation](guide/install.md)
+```
+
+Keep a single H1 followed by meaningful H2/H3 sections. Tables, task lists, fenced code, images, and ordinary inline Markdown are supported.
+
+Subfolders may provide arbitrary documentation trees. Keep link paths relative to the source page when possible.
+
+The legal pages bundled with the documentation template are examples. Replace their organization, jurisdiction, dates, practices, and contact details. Do not present template policies as legal advice.
+
+## Images
+
+`images.json` supplies decorative image data in an Unsplash-compatible shape. Preserve attribution fields for third-party images. Do not invent attribution or remove licensing information merely to simplify a template.
+
+## Local styling and skin colors
+
+Use the template's local stylesheet—normally `assets/res/custom.css`—for branding and page-specific presentation. `website.css` contains the shared application styles and should remain untouched during ordinary authoring.
+
+Read [skins.md](skins.md) when the task includes visual personalization. It lists the overridable variables supplied by the application skin.
+
+At minimum, personalize the accent variables:
+
+```css
+:root {
+    --accent: #ff8800;
+    --accent-tx: rgba(255, 136, 0, 0.5);
+}
+```
+
+Choose `--accent-tx` as a translucent version or companion of the main accent. Check that text and controls using the accent remain legible in both skins.
+
+The application supports light and dark skins. Use scoped overrides only when the shared values do not work in both:
+
+```css
+.skinroot.light {
+    --accent: #b74d00;
+}
+
+.skinroot.dark {
+    --accent: #ff9d3d;
+}
+```
+
+The standard navigation can expose a light/dark toggle. If it is present, verify both states and confirm the preference survives a reload. Prefer skin variables over one-off hard-coded colors so both modes remain coherent.
+
+## Individual pages
+
+Use the full-folder build for final validation. For a focused iteration, a page can be generated with:
+
+```sh
+statify file <site>/pages/path/page.md <output> <site>
+```

package/skill/statify-site/references/landing-pages.md

@@ -0,0 +1,107 @@
+# Landing pages and widgets
+
+Landing pages are JSON objects rendered by a named widget. Begin with `templates/landing/pages/index.json`; consult `templates/landing-rich/pages/index.json` only for relevant advanced patterns.
+
+## Page shell
+
+The common landing page uses `FeatureList`:
+
+```json
+{
+  "widget": "FeatureList",
+  "title": "Company name",
+  "canonical": "https://example.com",
+  "features": {
+    "title": {
+      "items": []
+    },
+    "cards": []
+  },
+  "footer": {
+    "links": []
+  }
+}
+```
+
+Use the exact property names and nesting demonstrated by the templates. CSS class strings are presentation hooks consumed by the website flavour; reuse known classes rather than guessing new behavior.
+
+## Content items
+
+A basic text or heading item:
+
+```json
+{
+  "el": "h2",
+  "text": "A useful heading",
+  "class": "accent"
+}
+```
+
+An image item:
+
+```json
+{
+  "image": "/res/product.webp",
+  "alt": "The product dashboard showing weekly activity",
+  "class": "shot col-12"
+}
+```
+
+Always provide meaningful `alt` text unless an image is purely decorative.
+
+A link item:
+
+```json
+{
+  "link": {
+    "text": "Get started",
+    "href": "/docs/start",
+    "class": "accentbutton"
+  }
+}
+```
+
+Cards can contain `items`, nested `cards`, and optional `links`. Keep nesting shallow unless the layout demonstrated by an existing template calls for it.
+
+## Video
+
+The rich template demonstrates two different video forms.
+
+Use `features.video` for a local background or showcase video:
+
+```json
+{
+  "url": "/res/videos/showcase",
+  "title": "Product showcase",
+  "autoplay": true,
+  "muted": "muted",
+  "loop": true
+}
+```
+
+The URL is a media basename in the existing convention. Confirm the required encoded video files exist. Autoplay video must remain muted and should not be the only way important information is communicated.
+
+Use a `youtube` item for a consent-aware YouTube embed:
+
+```json
+{
+  "youtube": {
+    "ref": "VIDEO_ID",
+    "image": "/res/video-poster.webp",
+    "title": "Descriptive video title",
+    "class": "smallervideo"
+  }
+}
+```
+
+Use only a real video ID supplied by the user or verified from their source. Provide a local poster image and descriptive title.
+
+## Other demonstrated patterns
+
+- `imageCarousel` accepts an array of objects with `url` values.
+- `Faq` pages use `faq.mainEntity`, with `name` and Markdown-capable `acceptedAnswer` values.
+
+## Choosing complexity
+
+Use ordinary text, images, links, and cards for most sites. Richer sites could include video, FAQs, carousels. 
+A rich reference is a syntax catalogue, not a target page length.

package/skill/statify-site/references/skins.md

@@ -0,0 +1,150 @@
+# Skin variables
+
+Statify's shared `website.css` defines a variable-driven light/dark skin. Override these variables in the template-local stylesheet, normally `assets/res/custom.css`; do not edit the compiled application stylesheet.
+
+Use `:root` for a value shared by both modes. Use `.skinroot.light` or `.skinroot.dark` when a token needs different contrast in each mode. Keep overrides limited to variables the design actually needs.
+
+## Core surface and text tokens
+
+| Variable | Role |
+| --- | --- |
+| `--window-background` | Main application background |
+| `--window-background-0` | Lowest dark-skin surface step |
+| `--window-background-1` | First raised dark-skin surface step |
+| `--window-background-2` | Second raised dark-skin surface step |
+| `--window-background-3` | Third raised dark-skin surface step |
+| `--window-background-hi` | Highlighted or raised surface |
+| `--window-background-lo` | Recessed light-skin surface |
+| `--primary-color` | Primary chrome or strong surface color |
+| `--black` | Stable black token |
+| `--text` | Main text color |
+| `--text-lo` | Secondary or subdued text |
+| `--border-color` | Borders and separators |
+| `--placeholder` | Placeholder or empty-state surface |
+| `--inputs` | Input background |
+| `--shadow-color` | Shadow color |
+
+The numbered `--window-background-*` variables are present in the dark source skin, while `--window-background-lo` is present in the light source skin. A custom stylesheet may define the complete set in both modes when its components need them.
+
+## Accent and foreground tokens
+
+The templates define the main branding accents locally:
+
+| Variable | Role |
+| --- | --- |
+| `--accent` | Primary brand/action color |
+| `--accent-tx` | Translucent or softer accent used by decorative treatments |
+
+The shared skin provides related foreground and state tokens:
+
+| Variable | Role |
+| --- | --- |
+| `--accent-light` | Pale accent surface, especially in light mode |
+| `--accent-alt` | Alternate accent |
+| `--text-over-accent` | Text placed over the main accent |
+| `--text-over-accent-hover` | Hover text over the main accent |
+| `--text-over-primary` | Text placed over the primary surface |
+| `--text-over-primary-hover` | Hover text over the primary surface |
+
+Check text-over-color pairs together. A visually attractive accent is not usable if `--text-over-accent` lacks contrast.
+
+## Status and overlay tokens
+
+| Variable | Role |
+| --- | --- |
+| `--back-success` | Success-message background |
+| `--back-warning` | Warning-message background |
+| `--back-error` | Error-message background |
+| `--bg-ok` | Strong success indicator |
+| `--bg-warning` | Strong warning indicator |
+| `--bg-error` | Strong error indicator |
+| `--alpha-band` | Translucent band or overlay |
+| `--alpha-gradient` | Overlay/gradient endpoint |
+| `--green` | Generic green utility color |
+| `--orange` | Generic orange utility color |
+| `--red` | Generic red utility color |
+
+`--bg-ok`, `--bg-warning`, and `--bg-error` are declared by the light skin; define dark equivalents only if components using them need different dark-mode values. Preserve recognizable success, warning, and error meaning.
+
+## Section backgrounds
+
+The `.back-zero`, `.back-one`, `.back-two`, and `.back-three` helpers consume matching variables:
+
+| Variable | Default intent |
+| --- | --- |
+| `--back-zero` | Base section background |
+| `--back-one` | First contrasting section background |
+| `--back-two` | Second contrasting section background |
+| `--back-three` | Third contrasting section background |
+
+The default dark skin derives these from the window surfaces with 45-degree gradients. They may also be solid colors. Some templates define additional local levels such as `--back-four` and `--back-five`; these are template extensions, not base skin variables.
+
+Example paired palette:
+
+```css
+.skinroot.light {
+    --back-zero: #ffffff;
+    --back-one: #f6f2ff;
+    --back-two: #e8dcff;
+    --back-three: #cab0ff;
+}
+
+.skinroot.dark {
+    --back-zero: #111111;
+    --back-one: #211934;
+    --back-two: #32234f;
+    --back-three: #49316f;
+}
+```
+
+Only define levels used by the page. Check the main and subdued text colors against every chosen level.
+
+## Responsive font variables
+
+The application provides root font sizes by breakpoint:
+
+| Variable | Source default |
+| --- | --- |
+| `--font-xs` | `16px` |
+| `--font-sm` | `16px` |
+| `--font-md` | `18px` |
+| `--font-lg` | `18px` |
+| `--font-xl` | `18px` |
+| `--font-fullhd` | `20px` |
+
+Override these only when the site needs a different global type scale. Preserve readable mobile sizes and test long headings, navigation labels, tables, and code blocks after changing them.
+
+## Control-size variables
+
+| Variable | Source default | Role |
+| --- | --- | --- |
+| `--unitsize` | `3rem` | Standard control and navigation unit |
+| `--unitsize-small` | `2.54rem` | Compact control unit |
+
+These are structural variables rather than branding colors. Change them cautiously because many controls, icons, and navigation elements share them.
+
+## Practical starter override
+
+For most sites, begin with the accents and leave the structural defaults alone:
+
+```css
+:root {
+    --accent: #ff8800;
+    --accent-tx: rgba(255, 136, 0, 0.5);
+}
+
+.skinroot.light {
+    --accent: #b74d00;
+    --accent-light: #fff1e6;
+    --text-over-accent: #ffffff;
+    --text-over-accent-hover: #ffffff;
+}
+
+.skinroot.dark {
+    --accent: #ff9d3d;
+    --text-over-accent: #111111;
+    --text-over-accent-hover: #000000;
+}
+```
+
+Preview the generated site in both skins at narrow and wide widths. Verify ordinary text, muted text, links, buttons, inputs, borders, cards, status colors, and every section-background level used by the page.

package/templates/landing/metadata.json

@@ -96,7 +96,7 @@
         "separator": true
       },
       "Documentation": {
-        "url": "/docs/index",
+        "url": "docs/index",
         "icon": "book"
       },
       "Contact": {

package/templates/landing/pages/docs/cookies.md

@@ -0,0 +1,25 @@
+# Cookies and Local Storage
+
+**Example policy — replace before publishing. Last updated: September 17, 2026.**
+
+This page explains how the Brightfield Labs website uses cookies and browser storage.
+
+## What we store
+
+The website does not use advertising or third-party tracking cookies. It stores only preferences requested by the visitor.
+
+| Storage key | Purpose | Duration |
+| --- | --- | --- |
+| `brightfield.preferences` | Remembers theme and policy-notice choices | Until changed or deleted |
+
+This information remains in the visitor's browser and is not used to create an advertising profile.
+
+## Managing stored data
+
+Visitors can remove local preferences through their browser's privacy or site-data settings. Removing them resets the saved theme and may display the policy notice again.
+
+If optional analytics or other cookies are introduced, this policy and the website's consent controls should be updated before those technologies are enabled.
+
+## Contact
+
+Questions about this example policy can be sent to [privacy@example.com](mailto:privacy@example.com).

package/templates/landing/pages/docs/index.md

@@ -0,0 +1,13 @@
+# Documentation
+
+Welcome to the Brightfield Labs documentation center. Use this template for product guides, company policies, technical references, or any other structured content.
+
+## Company Policies
+
+* [Terms of Service](tos.md)
+* [Privacy Policy](privacy.md)
+* [Cookies and Local Storage](cookies.md)
+
+## Getting Started
+
+Add Markdown files anywhere inside the `pages` folder. Subfolders become sections, and ordinary assets such as stylesheets and downloads are copied into the generated site.

package/templates/landing/pages/docs/privacy.md

@@ -0,0 +1,50 @@
+# Privacy Policy
+
+**Example policy — obtain appropriate legal review before publishing. Last updated: September 17, 2026.**
+
+This policy describes how **Brightfield Labs** (**we**, **us**, or **our**) handles personal information when someone visits **example.com** or contacts us.
+
+## Information we process
+
+We aim to collect only the information needed to operate and protect the website, communicate with visitors, and provide requested services.
+
+This may include:
+
+* ordinary technical request data, such as IP address, browser information, requested pages, and timestamps;
+* preferences stored locally in the visitor's browser;
+* contact details and message content supplied when someone writes to us; and
+* information required to provide a service requested by a customer.
+
+We do not sell personal information or use website visitor information to create advertising profiles.
+
+## Why we use information
+
+We may use information to operate and secure the website, prevent abuse, respond to enquiries, deliver requested services, meet legal obligations, and protect our rights. The appropriate legal basis depends on the context and applicable law.
+
+## Cookies and local storage
+
+The website may store limited preferences in the visitor's browser. See our [Cookies and Local Storage Policy](cookies.md) for details.
+
+## Service providers and transfers
+
+Trusted providers may process information when they host, maintain, deliver, or secure the website. We expect providers to handle information under suitable contractual and legal safeguards, including safeguards for international transfers where required.
+
+## Retention and security
+
+We retain information only as long as reasonably necessary for its purpose, legal obligations, security, and dispute resolution. We use reasonable technical and organizational safeguards, although no internet service can guarantee absolute security.
+
+## Individual rights
+
+Depending on location, individuals may have rights to access, correct, delete, restrict, or receive a copy of their personal information, or to object to certain processing. Identity verification may be required before a request is completed.
+
+## Changes
+
+We may update this policy as the website, our practices, or applicable requirements change. The revision date above identifies the latest version.
+
+## Contact
+
+**Brightfield Labs**  
+100 Example Street  
+Sample City, EX 10000
+
+Email: [privacy@example.com](mailto:privacy@example.com)

package/templates/landing/pages/docs/tos.md

@@ -0,0 +1,49 @@
+# Website Terms
+
+**Example terms — obtain appropriate legal review before publishing. Last updated: September 17, 2026.**
+
+These terms govern access to the Brightfield Labs website at **example.com**. By using the website, visitors agree to these terms.
+
+## Website purpose
+
+The website provides general information about Brightfield Labs, its services, and example work. Descriptions, demonstrations, roadmaps, and other materials are informational and do not create a binding offer, warranty, or service commitment.
+
+Separate agreements may govern paid products, professional services, software licenses, support, or customer projects. Those agreements take precedence for the services they cover.
+
+## Intellectual property
+
+Unless stated otherwise, Brightfield Labs owns the original website content and design or uses them with permission. Visitors may view the website for ordinary informational and business-evaluation purposes, but may not republish or commercially exploit substantial content without permission.
+
+Third-party names, trademarks, and materials remain the property of their respective owners.
+
+## Acceptable use
+
+Visitors must not use the website unlawfully, interfere with its operation or security, attempt unauthorized access, introduce malicious code, impose unreasonable automated load, or misrepresent an affiliation with Brightfield Labs.
+
+## External services
+
+Links to third-party websites are provided for convenience. Brightfield Labs does not control their availability, security, content, or terms.
+
+## Availability and disclaimer
+
+We may change, suspend, or discontinue the website at any time. The website and its informational content are provided on an **"as available"** basis. To the extent permitted by law, we do not guarantee that the website will always be available, error-free, complete, or suitable for a particular purpose.
+
+## Liability
+
+To the extent permitted by law, Brightfield Labs is not liable for indirect or consequential losses arising solely from use of, inability to use, or reliance on this public website. Nothing here excludes rights or liabilities that cannot legally be excluded.
+
+## Privacy
+
+Our handling of personal information is described in the [Privacy Policy](privacy.md), and browser storage is described in the [Cookies and Local Storage Policy](cookies.md).
+
+## Changes
+
+We may update these terms from time to time. Updated terms apply from publication unless otherwise stated.
+
+## Contact
+
+**Brightfield Labs**  
+100 Example Street  
+Sample City, EX 10000
+
+Email: [hello@example.com](mailto:hello@example.com)

package/templates/landing/pages/index.json

@@ -250,17 +250,17 @@
       },
       {
         "title": "Cookies",
-        "href": "/docs/cookies",
+        "href": "docs/cookies",
         "target": "doc"
       },
       {
         "title": "Privacy",
-        "href": "/docs/privacy",
+        "href": "docs/privacy",
         "target": "doc"
       },
       {
         "title": "Terms",
-        "href": "/docs/tos",
+        "href": "docs/tos",
         "target": "doc"
       }
     ]