@rm-industries/create-forge 0.4.0-beta.2 → 0.4.0-beta.3

package/dist/template/README.md

@@ -11,6 +11,30 @@ The template's `.editorconfig` shares UTF-8, LF, final-newline, two-space, and
 120-column settings with supported editors and Oxfmt. `oxfmt.config.ts` contains
 only formatter-specific behavior such as quote and import ordering.
 
+## Start here
+
+The generated documentation is organized by task:
+
+- [Getting started and site configuration](docs/guides/getting-started.md)
+  covers installation, local development, branding, identity assets, pages, and
+  the first verification pass.
+- [Content and CMS editing](docs/guides/content-and-cms.md) covers Markdown
+  articles, drafts, Sveltia local mode, deployed editing, shared model changes,
+  media, and recovery.
+- [Themes and accessibility](docs/guides/themes-and-accessibility.md) covers
+  themes, fonts, layout semantics, automated checks, and manual review.
+- [Quality checks, dependency updates, and troubleshooting](docs/guides/quality-and-troubleshooting.md)
+  explains the validation layers, common failures, Dependabot review, and safe
+  support requests.
+- [GitHub Pages deployment](docs/github-pages.md) covers project sites, custom
+  domains, environment protection, and deployment diagnosis.
+- [Accessibility review](docs/accessibility-checklist.md) and the
+  [Lighthouse performance budget](docs/performance-budget.md) record the
+  generated baseline and the manual checks projects must maintain.
+
+The remainder of this README is the complete command and implementation
+reference.
+
 | Command                  | Purpose                                                          |
 | ------------------------ | ---------------------------------------------------------------- |
 | `npm run dev`            | Start Astro's local development server.                          |

package/dist/template/docs/guides/content-and-cms.md

@@ -0,0 +1,123 @@
+# Content and CMS editing
+
+Forge stores article content as Markdown in `src/content/articles/`. Astro and
+Sveltia use the same model from
+`src/config/content-models/articles.ts`, so field rules are not duplicated.
+
+## Publish an article in Markdown
+
+Create `src/content/articles/my-first-article.md`:
+
+```md
+---
+title: My first article
+description: What I learned while building this site.
+publishedAt: 2026-09-02
+tags:
+  - notes
+draft: false
+---
+
+# My first article
+
+Write the article body here.
+```
+
+The file name becomes the article slug. Use a unique lowercase, hyphenated file
+name. Required fields, dates, defaults, and body content are validated during
+development, type checking, and builds.
+
+Set `draft: true` while writing. Draft articles appear during local development
+but are omitted from production article pages and RSS output. Before publishing:
+
+```sh
+npm run typecheck
+npm test
+npm run build
+npm run validate:build
+```
+
+Then inspect the article route and `/rss.xml` in the production preview:
+
+```sh
+npm run preview
+```
+
+## Edit content with Sveltia locally
+
+Local editing writes directly to the checked-out project; it does not require a
+GitHub token.
+
+1. Start the site with `npm run dev`.
+2. Open the printed local address with `/admin/`, normally
+   `http://localhost:4321/admin/`.
+3. Choose **Work with Local Repository**.
+4. Grant access to the generated project root, not only the content folder.
+5. Create or edit an article and save it.
+6. Review the resulting files with Git, run the checks above, and commit them
+   through the normal project workflow.
+
+A Chromium-based browser is the supported baseline for the local directory
+picker. The browser controls directory permission; if access is denied or
+revoked, reload `/admin/` and select the project again. Sveltia does not run a
+separate local proxy server in this setup.
+
+## Configure the deployed CMS
+
+Edit `src/integrations/sveltia/config.ts` and replace:
+
+```ts
+repo: 'your-github-user/your-repository',
+```
+
+with the same `owner/repository` configured in `src/config/site.ts`. The
+generated backend targets `main` and offers Sveltia's GitHub token flow. Tokens
+are entered by each editor in the CMS and must never be committed to the
+repository, configuration, documentation, or environment files.
+
+Before enabling editors, decide who may push to `main`, which branch protections
+apply, and whether the project needs a supported OAuth service instead of
+personal tokens. Treat `/admin/` as an editing application: it is excluded from
+search indexing and public Lighthouse budgets, but it is still publicly
+reachable on a deployed static site.
+
+## Change article fields
+
+Edit only `src/config/content-models/articles.ts`. The registry passes the model
+to both the Astro and Sveltia adapters.
+
+When adding or changing a field:
+
+1. choose whether it is required and whether it needs a default;
+2. update existing Markdown files to satisfy the new model;
+3. update pages or components that render the value;
+4. update or add model, Astro, Sveltia, and preview tests; and
+5. run `npm run quality:core` before checking the editor manually.
+
+Do not create a separate CMS YAML schema. A second schema can drift from the
+validation applied during builds.
+
+## Media
+
+The default CMS stores uploaded media under `public/assets/` and publishes it
+from `/assets`. Add only purposeful assets, keep file sizes appropriate for the
+[performance budget](../performance-budget.md), and provide useful alternative
+text where media conveys meaning. Decorative imagery should use empty
+alternative text at its rendering site.
+
+## Recover from an editing problem
+
+- If an article is missing in production, confirm `draft` is `false`, its front
+  matter passes `npm run typecheck`, and the file extension is `.md` or
+  `.mdx`.
+- If the CMS shows the wrong fields, confirm the model is registered in
+  `src/config/content-models/registry.ts` and reload the editor.
+- If local CMS changes appear in an unexpected directory, revoke the browser's
+  directory permission and select the project root again.
+- If deployed authentication fails, verify the repository identifier, branch,
+  token permissions, and organization access before changing content fields.
+- If a save produced an unwanted change, use Git to inspect and restore the
+  affected content file before committing it.
+
+For broader command failures, use
+[quality checks and troubleshooting](quality-and-troubleshooting.md).

package/dist/template/docs/guides/getting-started.md

@@ -0,0 +1,96 @@
+# Getting started and site configuration
+
+This guide takes a newly generated Forge project from installation to a branded
+local site. Run every command from the project root.
+
+## Install and start the site
+
+Use a supported Node.js and npm version from the `engines` field in
+`package.json`, then install the committed dependency graph:
+
+```sh
+npm ci
+npm run dev
+```
+
+Astro prints the local address, normally `http://localhost:4321`. Stop the
+server with `Control+C`.
+
+Use `npm ci`, rather than `npm install`, when reproducing the committed project.
+Use `npm install <package>` only when deliberately changing dependencies and
+commit both `package.json` and `package-lock.json` afterward.
+
+## Change the site identity
+
+Edit `src/config/site.ts`. The exported `site` object is the single source for
+page metadata, navigation, feeds, the manifest, and CMS branding.
+
+```ts
+export const site = defineSiteConfig({
+  name: 'Example Studio',
+  description: 'Notes about thoughtful product design.',
+  author: 'Example Team',
+  url: 'https://example.com',
+  repository: 'example/example-site',
+  language: 'en',
+  socialImage: '/social-card.svg',
+  navigation: [
+    { label: 'Home', href: '/' },
+    { label: 'Articles', href: '/articles/' },
+    { label: 'About', href: '/about/' },
+  ],
+  socialLinks: [{ label: 'GitHub', href: 'https://github.com/example' }],
+});
+```
+
+Use the complete production URL for `url`. A GitHub Pages project site includes
+its repository path, for example `https://example.github.io/example-site`.
+Root-hosted and custom-domain sites use only their origin. The
+[GitHub Pages guide](../github-pages.md) explains each form.
+
+Keep `repository` in `owner/repository` form. An empty value is valid while a
+repository does not exist, but configure it before using the deployed CMS.
+
+## Replace identity assets
+
+- Replace `public/favicon.svg` with the browser icon.
+- Replace `public/social-card.svg` with the default sharing image.
+- Change `site.socialImage` when the sharing image has a different path.
+- Edit `src/pages/about.astro` and the homepage copy in
+  `src/pages/index.astro` to describe the project.
+
+Files under `public/` are copied to the production build without processing.
+Reference them with site-relative paths and use the path helpers already used
+by the template when a component must support a GitHub Pages project prefix.
+
+## Add a page
+
+Create an Astro file under `src/pages/` and compose the shared layout:
+
+```astro
+---
+import BaseLayout from '../layouts/BaseLayout.astro';
+---
+
+<BaseLayout title="Contact" description="How to contact Example Studio.">
+  <h1>Contact</h1>
+  <p>Send us a message.</p>
+</BaseLayout>
+```
+
+Add the route to `site.navigation` if it belongs in primary navigation. Do not
+add another `main` element: `BaseLayout` already supplies the document shell,
+skip link, landmarks, metadata, header, and footer.
+
+## Verify the first customization
+
+```sh
+npm run quality:core
+npm run dev
+```
+
+Inspect the homepage, the changed page, `/articles/`, and `/admin/` in the
+browser. Run the complete `npm run quality` gate before opening a pull request.
+
+Continue with [content and CMS editing](content-and-cms.md), then review
+[themes and accessibility](themes-and-accessibility.md).

package/dist/template/docs/guides/quality-and-troubleshooting.md

@@ -0,0 +1,118 @@
+# Quality checks, dependency updates, and troubleshooting
+
+Forge provides fast focused commands and one complete release-blocking command.
+Run commands from the generated project root.
+
+## Choose the right check
+
+```sh
+npm run quality:static
+npm run quality:core
+npm run quality
+```
+
+- `quality:static` checks formatting, code, CSS, Markdown, spelling, unused code,
+  types, Astro diagnostics, and dependency policy.
+- `quality:core` adds coverage-enforced unit tests, a production build, and
+  required-output validation.
+- `quality` adds Playwright browser/accessibility tests and Lighthouse budgets.
+
+Use the focused command while developing and run `npm run quality` before
+requesting review. The complete pipeline stops at the first failure.
+
+## Fix common failures
+
+### Installation fails
+
+Confirm the Node.js and npm versions satisfy `package.json`, then retry the
+committed graph:
+
+```sh
+npm ci
+```
+
+Do not delete or regenerate `package-lock.json` merely to bypass an error. If a
+dependency intentionally changes, use npm to update the manifest and lockfile
+together and review the resulting install scripts and package contents.
+
+### Formatting or linting fails
+
+Apply the available safe fixes, then rerun the reported check:
+
+```sh
+npm run format:fix
+npm run lint:code:fix
+npm run lint:css:fix
+npm run lint:markdown:fix
+```
+
+Spelling, type, accessibility, and behavioral failures require a deliberate
+source or dictionary change; do not suppress them without documenting why.
+
+### Type checking or Astro diagnostics fail
+
+Run `npm run typecheck` and `npm run astro:check` separately for focused output.
+Check content front matter, import paths, component props, and the shared content
+model before changing compiler settings.
+
+### A browser test fails
+
+Install the browser version required by the committed Playwright package when
+working on a new machine:
+
+```sh
+npx playwright install chromium
+```
+
+Rerun `npm run test:e2e`. Screenshots and traces are written to
+`test-results/`; the HTML report is written to `playwright-report/`. Both are
+generated and ignored. CI retains them for failed runs.
+
+### Lighthouse fails
+
+Run `npm run lighthouse:ci` and inspect `.lighthouseci/`. Confirm the test used
+the production build, then compare the failing route and resource type with
+`docs/performance-budget.md`. Optimize the change or document a deliberately
+reviewed budget revision; do not raise a threshold only to pass CI.
+
+### The build succeeds but output is incomplete
+
+Run `npm run validate:build`. It verifies the required pages and supporting
+files and scans generated text for unresolved starter values. Add an output to
+the validator when introducing a route that is part of the public contract.
+
+### GitHub Pages does not deploy
+
+Open the `Project` workflow first. Deployment is intentionally blocked unless
+all quality jobs pass on `main`. If they pass, inspect the `github-pages`
+environment, Pages source, branch restrictions, URL configuration, and deploy
+job. Follow the [GitHub Pages guide](../github-pages.md) rather than bypassing
+the quality dependency.
+
+## Review dependency updates
+
+Dependabot proposes npm and GitHub Actions updates. Before merging one:
+
+1. read the upstream release notes and security advisory;
+2. confirm the supported Node.js range and licenses remain acceptable;
+3. review changes to `package.json` and `package-lock.json` together;
+4. keep Sveltia updates within the exact content-model compatibility range;
+5. run `npm run audit`, `npm run quality`, and any affected manual check; and
+6. merge only after project and security workflows pass.
+
+Do not widen `@rm-industries/content-model` peer compatibility inside a
+generated project. Forge publishes tested content-model compatibility first,
+then template dependency automation can adopt it. Existing generated projects
+remain owner-maintained source and do not receive template files automatically.
+
+High-severity audit exceptions are documented narrowly in `audit-ci.jsonc` and
+`docs/performance-budget.md`. Review their expiry and exposure; do not copy an
+exception to silence an unrelated advisory.
+
+## Ask for help safely
+
+When reporting a reproducible problem, include the Node.js and npm versions,
+operating system, exact command, error output, and the smallest safe reproduction.
+Remove tokens, repository secrets, private URLs, and unpublished content. Follow
+the upstream Forge `SECURITY.md` process for vulnerabilities rather than opening
+a public issue.

package/dist/template/docs/guides/themes-and-accessibility.md

@@ -0,0 +1,85 @@
+# Themes and accessibility
+
+Forge starts with four Catppuccin themes, bundled fonts, semantic layout
+components, keyboard navigation, reduced-motion behavior, and automated
+accessibility checks. Customization must preserve those user-facing guarantees.
+
+## Choose a theme
+
+The site follows the operating-system color preference: Latte is the default
+light theme and Mocha is the dark theme. Theme definitions live in
+`src/themes/`, and `src/components/theme/ThemeHead.astro` initializes them.
+
+The available `data-theme` values are `latte`, `frappe`, `macchiato`, and
+`mocha`. If a project adds a theme control, apply one of those values to the
+document element, persist only a validated value, and retain an operating-system
+fallback. Test the control with JavaScript disabled so content and navigation
+remain usable.
+
+## Change colors or add a theme
+
+Keep theme values in `src/themes/` instead of scattering colors through Astro
+components. Update `src/themes/site-theme.test.ts` whenever the registered theme
+set or light/dark defaults change.
+
+Prefer DaisyUI component classes in templates. Use Tailwind utilities only for
+layout or behavior that DaisyUI does not provide, and keep ordinary CSS in
+`src/styles/global.css` or `src/styles/print.css`. Do not add component-local CSS
+for patterns that belong to a shared primitive.
+
+After changing a theme, inspect text, links, controls, focus indicators, code,
+cards, and article typography in both color schemes. Then run:
+
+```sh
+npm run lint:css
+npm run test:e2e
+npm run lighthouse:ci
+```
+
+## Replace fonts
+
+Fira Sans and Fira Code are installed through Fontsource and imported by
+`src/styles/global.css`; no remote font service is used. To replace them:
+
+```sh
+npm uninstall @fontsource/fira-sans @fontsource/fira-code
+npm install @fontsource/inter @fontsource/source-code-pro
+```
+
+Replace the imports and the `--font-sans` and `--font-mono` values in
+`src/styles/global.css`. Import only weights the site uses. For system fonts,
+remove the Fontsource packages and imports and retain suitable generic fallback
+families.
+
+Run `npm run build` after changing fonts. Missing weights fail at build time;
+unexpected transfer growth fails the Lighthouse budget.
+
+## Preserve layout semantics
+
+- Wrap pages in `src/layouts/BaseLayout.astro`.
+- Keep one level-one heading that identifies each page.
+- Do not add a second `main` landmark inside the layout.
+- Use real links and buttons rather than clickable generic elements.
+- Preserve the skip link, visible focus states, current-page indication, and
+  named navigation.
+- Use `navigation/Pagination.astro` only with real previous and next routes.
+- Use the shared container and card primitives before creating a new variant.
+
+## Review accessibility
+
+Automation catches many regressions but cannot judge wording, reading order,
+alternative-text quality, or every visual state. After changing content,
+navigation, themes, components, or interaction:
+
+1. run `npm run test:a11y`;
+2. complete `docs/accessibility-checklist.md` with the actual date, browsers,
+   screen sizes, input methods, and result;
+3. test keyboard-only use at desktop and mobile widths;
+4. inspect light, dark, reduced-motion, and print behavior; and
+5. record unresolved failures as issues rather than checking an unverified item.
+
+The CMS interface is supplied by Sveltia and is outside the template's public
+site audit. Evaluate that interface with the people who will edit the site.
+
+See the [accessibility review checklist](../accessibility-checklist.md) and
+[performance budget](../performance-budget.md) for the enforced baseline.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rm-industries/create-forge",
-  "version": "0.4.0-beta.2",
+  "version": "0.4.0-beta.3",
   "description": "Create a content-driven Forge website",
   "keywords": [
     "astro",