v1.0.2

Version 1.0.2 gives private forks a one-command way to take upstream updates, moves the starter to a develop/main branch model with an automated release pipeline, and makes Node.js 24 the only supported runtime. It also removes Nx Cloud, adds and tightens several repository-wide guards, and records the Railway deployment in the repository. Several of these changes ask something of every fork: read Fork migration below before merging.

The first area is the fork and release workflow. A client project that must stay private cannot be a GitHub fork of a public repository, so it lives as a private mirror. Run inside a mirror, npm run upstream:pull fetches upstream, prints the CHANGELOG changes since the last merge, merges upstream/main, resolves lockfile-only conflicts and finishes with npm run ci:verify; the separate fork-init tool creates the mirror in the first place (#540). Upstream now develops on develop and reaches main only through an automated release pull request, so every advance of main is a tagged release with its own CHANGELOG section. A new /release-workflow skill prepares each release by promoting the ## [Unreleased] section to the new version and bumping package.json, and two workflows open the release pull request and publish the tag and GitHub Release (#539). Structured issue forms and a refreshed pull request template make new issues easier to triage (#504).

The second is toolchain and CI. Node.js 24 LTS is now the only supported runtime: engines.node is ^24.18.0, and a new .nvmrc pins 24.18.0 (#537). Nx Cloud is removed and tasks use the local Nx cache only, so a stray access token can no longer fail CI or report a private mirror's runs to the starter's public Nx Cloud workspace (#542). The repository-wide guards now run as one Nx check target, both locally and in a new remote CI job, so a push that skipped the pre-commit hook no longer skips them (#527). One of those guards is new: code comments must explain the code as it is now, and an issue or pull request number in a comment fails the build (#499). The lint rule against direct process.env access now allows eight named files instead of three whole directories, and the integration tests read their settings through the typed environment schemas (#501).

The third is styling. Components whose host styling is a fixed set of utilities now declare it with host: { class } instead of :host { @apply … } (#489). Component stylesheets no longer carry the @reference "#tailwind-theme" line: a PostCSS plugin adds it at build time to every stylesheet that uses @apply, and the ui-component generator stops writing it (#523). The dashboard header and the health page now use the theme's semantic tokens instead of hardcoded grays, so both render correctly in dark mode (#520, #513).

The fourth is deployment. A root railway.json records the Railway build command, start command and health check in the repository, so a deploy that cannot reach its database no longer replaces a healthy one (#514). Storybook can be served from a second Railway service by a small static server that uses only Node built-ins (#547). Vercel-specific wording and a dead Speed Insights stub are removed from the code and documentation (#545). A deploy that restarted in a loop on its startup database check turned out to have a connection configuration problem in the deploy environment; correcting that configuration resolved it, with no code change (#511).

Fork migration

Every fork:

• #537 - Use Node.js 24.18.0 or later (nvm use reads the new .nvmrc), move the Node version pins in your own CI workflows and deployment platform to 24.18, then run npm install to pick up @types/node ^24.13.3. engines.node is now ^24.18.0: an older runtime gets an engines warning from npm, and fails the install if your .npmrc sets engine-strict=true.
• #542 - Delete the NX_CLOUD_ACCESS_TOKEN secret from your repository's Actions secrets and unset the token in your shells: nx.json no longer has upstream's nxCloudId, and .github/workflows/ci.yml sets NX_NO_CLOUD: 'true' and uses the local Nx cache only. If your fork uses its own Nx Cloud workspace, keep your own nxCloudId when you resolve the nx.json merge and remove NX_NO_CLOUD from your ci.yml.
• #539 - When you resolve the merge, keep nx.json defaultBase pointing at your own primary branch (upstream's is now "develop"), and point the new push: branches: [develop] trigger in .github/workflows/ci.yml at your primary branch or remove it. Keep merging from upstream/main only; develop is upstream's integration branch.
• #501 - Move direct process.env reads out of your app's code. npm run lint now allows them, in every app under apps/, only in src/api/config/env-utils.ts, env-utils.spec.ts, runtime.ts, runtime.spec.ts, src/test-setup.ts, src/api/integration/setup/global-setup.ts, src/api/integration/setup/env-helpers.ts and src/db/seed.ts. Copy the reference app's versions of src/api/config/runtime.ts, runtime.spec.ts, env-utils.spec.ts and db.env.spec.ts, of env-helpers.ts, auth-helpers.ts, db-helpers.ts and global-setup.ts in src/api/integration/setup/, of src/api/integration/auth/login.integration.spec.ts and of src/db/seed.ts into your app. Route any other read through the typed <domain>Env proxy (seed<Domain>Env in tests), or add a justified explicit entry to the allowlist in eslint.config.mjs.
• #499 - Rewrite every issue or pull request number (#<n>, any length) in the // and /* … */ comments of .ts and generator .ts.template files under apps/ and packages/ as a present-state explanation, or move a durable cross-reference to CHANGELOG.md or docs/. scripts/check-no-issue-refs-in-comments.mjs now fails the pre-commit hook, npm run ci and npm run ci:verify; run node scripts/check-no-issue-refs-in-comments.mjs to list the offending lines.
• #499, #527 - Expect the new check job in .github/workflows/ci.yml to fail your first remote CI run if your tree contains a .env* file, an issue number in a code comment, or a file that is not Prettier-formatted; remote CI did not run these guards before. Run npm run format and the two scripts/check-*.mjs guards before pushing the merge.
• #514 - If you deploy on Railway, edit the new root railway.json before your next deploy: Railway config-as-code overrides your service's settings, and the file builds and starts the reference app (buildCommand: npm run build, startCommand: node dist/reference-app/server/server.mjs, healthcheckPath: /api/health/v1). Make it build your app, start dist/<your-app>/server/server.mjs and check a health path your app serves, or delete the file.

If your fork changed or reuses any of the following:

• #523 - Component stylesheets: you may delete @reference "#tailwind-theme" from your components. The new root PostCSS plugin postcss-inject-tailwind-reference.js, registered first in .postcssrc.json, adds it at build time to every stylesheet that uses @apply and declares no @reference of its own, and the ui-component generator no longer emits it. If you @import a stylesheet of your own into tailwind.config.css and it uses @apply without its own @reference "tailwindcss", add its path suffix to themeEntrySuffixes in postcss-inject-tailwind-reference.js; a missed file shows up as a Tailwind circular-reference build error.
• #523 - Your global stylesheet: if the stylesheet that @imports tailwind.config.css (for example apps/<your-app>/src/styles.css) also uses @apply, move those rules into a separate stylesheet or write them as plain CSS. The plugin injects @reference "#tailwind-theme" into any stylesheet that uses @apply, and in the one that imports the theme that drops the --font-sans and --font-mono tokens, so text falls back to Tailwind's default fonts.
• #513, #520 - The health page or the dashboard shell: apply the dark-mode fixes to your copies. In pages/dashboard/pages/health/health.ts, change border-1 border-gray-200 to border border-border and bg-gray-100 to bg-muted. In dashboard.ts, change the <header appHeader> classes border-b-1 border-gray-200 dark:border-white/10 dark:bg-black/95 to border-b border-border bg-background. In the Header component's host classes, change dark:text-gray-50 to text-foreground.
• #527 - The ci / ci:verify scripts in the root package.json: move any guard you added there into the commands array of the new root check target (nx.targets.check) instead of an && chain, then take upstream's ci / ci:verify, which start with nx run-many -t check stylelint lint typecheck.

Behaviour that changes with no action needed:

• #539 - Upstream now integrates on develop and releases to main only through an automated release pull request, so each advance of upstream/main is one tagged, documented release. The prepare-release-pr.yml and release.yml workflows run only in the upstream repository. Upstream also relies on main branch protection and on Railway deploying the explicit main branch; forks do not inherit these settings, so create them if you want the same guarantee.
• #504, #539 - The new issue templates apply labels your repository may not have: 🦟 bug, 🏎️ enhancement, 📝 documentation, 🛠️ tooling, 🎨 ui-ux, 💼 management, ✍️ draft, 📦 epic, 🧩 initiative and 🚀 release. GitHub skips a missing label, so create these labels, or change the templates' labels: arrays, only if you want them applied.
• #504 - Claude Code no longer adds co-author or attribution trailers to commits and pull requests: the shared .claude/settings.json sets includeCoAuthoredBy: false and gitAttribution: false. Override them in your .claude/settings.local.json if you want attribution.

Full changes

See every merged pull request in v1.0.2.

Changes

Fork and release workflow

• #540 - Adds npm run upstream:pull to merge upstream updates into a private mirror.
• #539 - Adopts the develop/main branch model with an automated release pipeline.
• #504 - Adds structured GitHub issue forms and refreshes the pull request template.

Toolchain and CI

• #537 - Upgrades Node.js to the 24 LTS line and @types/node to 24.x.
• #542 - Removes Nx Cloud, so tasks use the local Nx cache only.
• #527 - Runs the repository-wide guards as one Nx check target, locally and in remote CI.
• #499 - Forbids issue and pull request numbers in code comments and enforces it with a guard.
• #501 - Limits direct process.env access to eight named files and routes the integration tests through the environment schemas.

Styling

• #489 - Moves fixed host styles from :host { @apply … } to host: { class }.
• #523 - Adds @reference "#tailwind-theme" at build time instead of in each component stylesheet.
• #520 - Replaces the dashboard header's hardcoded grays with semantic theme tokens.
• #513 - Makes the health page panels render correctly in dark mode.

Deployment

• #514 - Adds a railway.json with the build command, start command and health check.
• #547 - Serves the Storybook build from a second Railway service.
• #545 - Removes Vercel-specific wording and dead scaffolding from code and documentation.
• #511 - Resolves the startup database health-check failure through deployment configuration.

What's Changed

Merged PRs

• #514 - Add railway.json deploy config (build/start/healthcheck as code) by @rolivencia in #515
• #513 - The application health view does not render correctly in dark mode by @rolivencia in #522
• #489 - Migrate :host @apply to host property and research project-wide @reference elimination by @rolivencia in #521
• #520 - Tokenize the dashboard header chrome — replace hardcoded grays with semantic theme tokens by @rolivencia in #524
• #501 - Tighten no-process-env allowlist to least-privilege; route integration tests through env schemas by @rolivencia in #525
• #523 - Eliminate @reference project-wide via build-time auto-injection by @rolivencia in #528
• #499 - Comment-quality policy: no issue-number or before/after references in code comments (+ sweep) by @rolivencia in #526
• [#529] - Fall back to local Nx cache when Nx Cloud credits are exhausted by @rolivencia in #530
• #504 - Add structured GitHub issue/PR templates, adapted from cuentoneta/cuentoneta by @rolivencia in #531
• #527 - Model repo-wide CI guard scripts as Nx targets (stop chaining && in ci/ci:verify) by @rolivencia in #532
• #537 - Upgrade Node.js to v24 LTS (runtime + @types/node 24.x) by @rolivencia in #538
• #540 - Private-mirror workflow: upstream:pull in-repo, fork-init as a standalone npx tool by @rolivencia in #541
• #542 - Remove Nx Cloud entirely — from the base repo and from fork:init mirrors by @rolivencia in #543
• #539 - Adopt main/develop branching and automate the release process by @rolivencia in #544
• #545 - Remove all Vercel coupling from the repo (integration, comments, docs) by @rolivencia in #546
• #547 - Deploy Storybook to Railway and restore the live-demo link by @rolivencia in #548
• [#533] - Release v1.0.2 by @rolivencia in #549
• Release v1.0.2 by @github-actions[bot] in #550

New Contributors

• @github-actions[bot] made their first contribution in #550

Full Changelog: v1.0.1...v1.0.2