@starci/hfs 4.0.8 → 4.0.10

package/templates/app/ci-workflows/github/workflows/images.yml

@@ -0,0 +1,37 @@
+{{header}}
+# Builds the image of every app on the release tag, so a Dockerfile that no longer builds fails the release (or a manual dispatch) that carries it.
+# It never pushes: publishing an image is the product's decision, not this file's.
+name: images
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One run per ref.
+concurrency:
+  group: images-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  image:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+{{imageMatrix}}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ${{ matrix.file }}
+          push: false
+          tags: {{imageProject}}/${{ matrix.name }}:ci
+          cache-from: type=gha,scope=${{ matrix.name }}
+          cache-to: type=gha,scope=${{ matrix.name }},mode=max

package/templates/app/ci-workflows/sonar-steps.yml

@@ -0,0 +1,9 @@
+      - uses: SonarSource/sonarqube-scan-action@v7
+        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}
+        env:
+          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
+      - uses: SonarSource/sonarqube-quality-gate-action@v1
+        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}
+        timeout-minutes: 10
+        env:
+          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -0,0 +1,66 @@
+{{header}}
+name: ci
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One run per ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    env:
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci
+      - name: lint
+        if: env.SONAR_TOKEN == ''
+        run: npm run lint
+      - name: lint with Sonar import
+        if: env.SONAR_TOKEN != ''
+        run: npm run lint -- --sonar reports/lint.sonar.json
+      - name: format
+        run: npm run format:check
+      - name: typecheck
+        run: npm run typecheck
+      - name: build be
+        run: npm run build:be
+      - name: build fe
+        run: npm run build:fe
+      - name: database migration checks
+        run: npm run db:lint
+{{> app/ci-workflows/sonar-steps.yml}}
+
+  db-types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci
+      - name: start Supabase
+        run: npm run db:start
+      - name: apply migrations
+        run: npm run db:reset
+      - name: regenerate database types
+        run: npm run db:types
+      - name: database types are committed
+        run: git diff --exit-code -- supabase/types/database.types.ts
+      - name: stop Supabase
+        if: always()
+        run: npm run db:stop

package/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml

@@ -0,0 +1,31 @@
+{{header}}
+name: deploy database
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: GitHub environment whose Supabase secrets will be used
+        required: true
+        type: environment
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    env:
+      SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
+      SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
+      SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci
+      - name: push migrations
+        run: npm run db:push

package/templates/app/ci-workflows-lite/github/workflows/images.yml

@@ -0,0 +1,37 @@
+{{header}}
+# Builds each image declared by the lite app. The API image is required; a front-end image is emitted only when declared.
+# It runs on the release tag, so every image is built there, and never pushes.
+name: images
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One run per ref.
+concurrency:
+  group: images-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  image:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+{{imageMatrix}}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ${{ matrix.file }}
+          push: false
+          tags: {{imageProject}}/${{ matrix.name }}:ci
+          cache-from: type=gha,scope=${{ matrix.name }}
+          cache-to: type=gha,scope=${{ matrix.name }},mode=max

package/templates/app/codegen-lite/scripts/codegen.mjs

@@ -0,0 +1,32 @@
+// Generated by {{appBinary}} sync (app root). Do not edit: run "npx {{appBinary}} sync --write".
+// Database types hook, offline: the app compiles against the committed supabase/types/database.types.ts, which `npm run contract:emit`
+// regenerates from the local stack and stamps with the digest of the migrations it was generated from. This refuses a missing or
+// stale file, so lint, typecheck, dev and build never run against types older than the migrations; it starts nothing and needs no stack.
+import { createHash } from "node:crypto"
+import fs from "node:fs"
+import path from "node:path"
+
+const MIGRATIONS = path.join("supabase", "migrations")
+const TYPES = path.join("supabase", "types", "database.types.ts")
+const STAMP = /^\/\/ migrations-sha256: ([0-9a-f]{64})$/
+
+const fail = (message) => {
+    console.error(`codegen: ${message}`)
+    process.exit(1)
+}
+
+const hash = createHash("sha256")
+for (const name of (fs.existsSync(MIGRATIONS) ? fs.readdirSync(MIGRATIONS) : [])
+    .filter((file) => file.endsWith(".sql"))
+    .sort()) {
+    hash.update(`${name}\0${fs.readFileSync(path.join(MIGRATIONS, name), "utf8").replace(/\r\n/g, "\n")}\0`)
+}
+const digest = hash.digest("hex")
+
+if (!fs.existsSync(TYPES))
+    fail(`${TYPES} is missing; start the local stack and run \`npm run contract:emit\`, then commit it`)
+const stamped = STAMP.exec(fs.readFileSync(TYPES, "utf8").split(/\r?\n/, 1)[0])?.[1]
+if (stamped !== digest)
+    fail(
+        `${TYPES} is ${stamped === undefined ? "not stamped" : "older than the migrations"}; run \`npm run contract:emit\` and commit the regenerated types`,
+    )

package/templates/app/docker-ignore/dockerignore

@@ -0,0 +1,50 @@
+{{header}}
+# The build context of every image (be/apps/<app>/Dockerfile, fe/apps/<app>/Dockerfile) is the app root, so every Dockerfile
+# shares this file. It does two jobs, and the second is the one that matters: it keeps the context small, and it keeps
+# secrets out of the context altogether (a file that is never COPYed is still uploaded to the daemon and cached).
+
+node_modules
+**/node_modules
+dist
+**/dist
+build
+coverage
+**/coverage
+.next
+**/.next
+.turbo
+**/.turbo
+**/*.tsbuildinfo
+
+.git
+.github
+.husky
+
+# runtime and developer state
+.claude
+.starciwork
+.tools
+.workspaces
+.artifacts
+**/.artifacts
+reports
+test-results
+
+# secrets and credential material: mounted at run time, never part of an image
+.secrets
+.starcistacks
+.volume
+**/.env
+**/.env.*
+!**/.env.example
+**/*.key
+**/*.pem
+**/kubeconfig*
+
+# tests never enter an image
+**/*.spec.ts
+**/*.e2e-spec.ts
+be/src/tests
+**/__generated__
+docs
+*.log

package/templates/app/gitignore-lite

@@ -0,0 +1,35 @@
+{{> common/gitignore.base}}
+# Supabase CLI state is local Docker metadata, never application source.
+supabase/.temp/
+supabase/.branches/
+# be: the schema Nest writes when it boots GraphQL
+schema.gql
+# fe: Next build output and its generated type file
+.next/
+next-env.d.ts
+# .starcistacks custody at the app root: modules/schemas/stacks-layout.yaml custody.gitignoreRules, in order. Only the
+# declaration, runbooks, key lists, seeds, the rendered environment, the infra definitions and sealed *.enc are tracked.
+.starcistacks/**
+!.starcistacks/**/
+!.starcistacks/**/KEYS.md
+!.starcistacks/**/.gitkeep
+!.starcistacks/application-stacks.yaml
+!.starcistacks/*/README.md
+!.starcistacks/*/environment.json
+!.starcistacks/*/seeds/**
+!.starcistacks/*/infra/metadata.json
+!.starcistacks/*/infra/compose/**
+!.starcistacks/*/infra/k8s/**
+!.starcistacks/*/infra/terraform/**
+.starcistacks/*/infra/**/.env
+.starcistacks/*/infra/**/.env.*
+.starcistacks/*/infra/**/*.env
+.starcistacks/*/infra/**/*.key
+.starcistacks/*/infra/**/*.pem
+.starcistacks/*/infra/**/*.tfvars
+.starcistacks/*/infra/terraform/.terraform/
+.starcistacks/*/infra/terraform/*.tfstate
+.starcistacks/*/infra/terraform/*.tfstate.*
+.starcistacks/*/infra/terraform/files/
+.starcistacks/*/infra/terraform/*.tar.gz
+!.starcistacks/**/*.enc

package/templates/app/hooks/husky/pre-commit

@@ -1,8 +1,7 @@
 {{header}}
-# Commit gate: the secrets guard and work hygiene of the staged files, types, lint and format of the staged files of each side,
-# stylelint over the staged CSS of fe, the unit specs of be the staged files touch. Never integration, e2e or contract.
-npx hfs work-hygiene
-npm run typecheck
+# Commit gate (L0 only): work hygiene and the secrets guard of the staged files, eslint of the staged files of each side,
+# stylelint over the staged CSS of fe, a prettier check of the staged files. Types and the targeted specs belong to the op gate.
+npx starci app hygiene
 be=$(git diff --cached --name-only --diff-filter=ACMR --relative=be -- '*.ts' '*.mts' '*.cts' '*.js' '*.mjs' '*.cjs' || true)
 if [ -n "$be" ]; then
   (cd be && npx eslint $be)
@@ -19,7 +18,3 @@ formatted=$(git diff --cached --name-only --diff-filter=ACMR || true)
 if [ -n "$formatted" ]; then
   npx prettier --check --ignore-unknown $formatted
 fi
-specs=$(git diff --cached --name-only --diff-filter=ACMR --relative=be -- '*.ts' | grep -v -E '(^|/)src/tests/(world|integration|e2e|contract)/|\.(integration|e2e|contract)-spec\.ts$' || true)
-if [ -n "$specs" ]; then
-  npm run test:affected -- --findRelatedTests $specs
-fi

package/templates/app/hooks/husky/pre-push

@@ -1,7 +1,46 @@
 {{header}}
-# Push gate: types, lint (one `hfs lint`: eslint per side, the app checks, stylelint over fe), format, the unit specs of be affected
-# since main. Never integration, e2e or contract.
-npm run typecheck
-npm run lint
-npm run format:check
-npm run test:affected -- --changedSince=origin/main
+# Push gate: a release gate check, never a test run. Nothing but the release cut pushes main or a release tag, and the coordinator
+# backs work up under refs/backup/*. Git hands this hook one line per ref: <local ref> <local sha> <remote ref> <remote sha>.
+#   refs/backup/*                  allowed: the coordinator backup namespace
+#   refs/heads/main, refs/tags/v*  allowed only when HEAD carries an annotated tag v[0-9]* and the release cut recorded the
+#                                  full suite of HEAD: <git common dir>/starci-release/<HEAD sha>.l4.json names that head and tag
+#   any other ref, a delete        refused
+common=$(git rev-parse --git-common-dir)
+case "$common" in /* | [A-Za-z]:*) ;; *) common="$(pwd)/$common" ;; esac
+head=$(git rev-parse HEAD)
+record="$common/starci-release/$head.l4.json"
+status=0
+gate=""
+refuse() {
+  echo "RIGHTS_PUSH_NOT_RELEASE: $1 - the allowed path is the release cut (main and v* tags) or refs/backup/* (backups)" >&2
+  status=1
+}
+# gate: the verdict of the release gate for HEAD, computed once: "ok" or the reason it is closed.
+release_gate() {
+  if [ -n "$gate" ]; then return 0; fi
+  gate="no annotated tag v[0-9]* on HEAD $head"
+  for tag in $(git tag --points-at HEAD --list 'v[0-9]*' 2>/dev/null || true); do
+    if [ "$(git cat-file -t "refs/tags/$tag" 2>/dev/null || true)" != "tag" ]; then continue; fi
+    if [ ! -f "$record" ]; then gate="no L4 record $record"; continue; fi
+    flat=$(tr -d ' \t\r\n' < "$record")
+    case "$flat" in
+      *'"head":"'"$head"'"'*'"tag":"'"$tag"'"'* | *'"tag":"'"$tag"'"'*'"head":"'"$head"'"'*) gate="ok"; return 0 ;;
+    esac
+    gate="the L4 record $record does not name head $head and tag $tag"
+  done
+  return 0
+}
+while read -r local_ref local_sha remote_ref remote_sha; do
+  case "$remote_ref" in
+    refs/backup/*) ;;
+    refs/heads/main | refs/tags/v*)
+      case "$local_sha" in
+        *[!0]*) ;;
+        *) refuse "refusing to delete $remote_ref"; continue ;;
+      esac
+      release_gate
+      if [ "$gate" != "ok" ]; then refuse "$remote_ref is closed: $gate"; fi ;;
+    *) refuse "refusing to push $remote_ref" ;;
+  esac
+done
+exit "$status"

package/templates/app/package-scripts/core.json

@@ -0,0 +1,8 @@
+    "build:be": "cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build:fe": "{{buildFe}}",
+    "codegen": "node scripts/codegen.mjs",
+    "typecheck": "{{typecheck}}",
+    "lint": "{{lintPrefix}}{{appBinary}} lint",
+    "lint:fix": "{{lintPrefix}}{{appBinary}} lint --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",

package/templates/app/package-scripts/package.json

@@ -2,21 +2,14 @@
   "scripts": {
     "prepare": "husky",
     {{appScripts}}
-    "build:be": "cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
-    "build:fe": "{{buildFe}}",
-    "codegen": "node scripts/codegen.mjs",
-    "typecheck": "{{typecheck}}",
+{{> app/package-scripts/core.json}}
     "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
-    "lint": "npm run codegen --silent && hfs lint",
-    "lint:fix": "npm run codegen --silent && hfs lint --fix",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
     "test": "cd be && jest --selectProjects unit --coverage",
     "test:affected": "cd be && jest --selectProjects unit --passWithNoTests",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
     "test:e2e": "npm run typecheck:tests && cd be && jest --selectProjects e2e",
     "test:contract": "npm run typecheck:tests && cd be && jest --selectProjects contract",
-    "test:stack": "cd be && starci-test-stack",
-    "contract:emit": "hfs emit-contracts"
+    "test:stack": "starci app stack",
+    "contract:emit": "starci app emit"
   }
 }

package/templates/app/package-scripts-lite/package.json

@@ -0,0 +1,15 @@
+{
+  "scripts": {
+    "prepare": "husky",
+    {{appScripts}}
+{{> app/package-scripts/core.json}}
+    "db:start": "supabase start",
+    "db:stop": "supabase stop",
+    "db:reset": "supabase db reset",
+    "db:new": "supabase migration new",
+    "db:push": "supabase db push",
+    "db:types": "npm run contract:emit",
+    "db:lint": "{{appBinary}} check --fast",
+    "contract:emit": "{{appBinary}} emit"
+  }
+}

package/templates/app/quality-config/codecov.yml

@@ -1,7 +1,8 @@
 {{header}}
-# The be unit run's lcov ({{lcovReport}}), uploaded by the managed CI workflow. Coverage is the services' alone: the status
-# paths are the one coverage scope whose complement hfs sync renders into sonar.coverage.exclusions, held at 100 on the project and on
-# the patch. fe/ is outside coverage (a front end has no tests).
+# The be unit run's lcov ({{lcovReport}}), uploaded by the managed CI workflow. Coverage is the logic of be/src/modules/**: the status
+# paths are the measured roots of the one coverage scope (derived from the slot manifest's `coverage` field; its complement is rendered into
+# sonar.coverage.exclusions and its roots into be/jest.config.js), held at 100 on the project and on the patch, and each component (one per
+# service app, plus platform) is held at 100 too. fe/ and be/src/features are outside coverage (features are thin by rule; a front end has no tests).
 codecov:
   require_ci_to_pass: true
 coverage:
@@ -18,5 +19,16 @@ coverage:
         threshold: 0%
         paths:
 {{codecovPaths}}
+component_management:
+  default_rules:
+    statuses:
+      - type: project
+        target: 100%
+        threshold: 0%
+      - type: patch
+        target: 100%
+        threshold: 0%
+  individual_components:
+{{codecovComponents}}
 ignore:
   - "fe/**"

package/templates/app/quality-config/sonar-base.properties

@@ -0,0 +1,4 @@
+{{header}}
+sonar.projectKey={{sonarKey}}
+sonar.sourceEncoding=UTF-8
+sonar.sources={{sonarSources}}

package/templates/app/quality-config/sonar-project.properties

@@ -1,7 +1,4 @@
-{{header}}
-sonar.projectKey={{sonarKey}}
-sonar.sourceEncoding=UTF-8
-sonar.sources={{sonarSources}}
+{{> app/quality-config/sonar-base.properties}}
 sonar.tests=be/apps,be/src
 sonar.exclusions={{sonarExclusions}}
 sonar.test.inclusions=**/*.spec.ts

package/templates/app/quality-config-lite/sonar-project.properties

@@ -0,0 +1,5 @@
+{{> app/quality-config/sonar-base.properties}}
+sonar.exclusions={{sonarExclusions}}
+sonar.typescript.tsconfigPaths={{tsconfigPaths}}
+sonar.externalIssuesReportPaths=reports/lint.sonar.json
+sonar.nodejs.maxspace=8192

package/templates/app/skeleton/.starcistacks/dev/seeds/primary-notes.sql

@@ -0,0 +1,5 @@
+-- DEMO-ONLY note for the primary database (connection `primary`). Run after `npm run migrate` with `npm run cli -- seed run`.
+-- Idempotent: an existing note is left as it is.
+INSERT INTO notes (id, body, created_at) VALUES
+    ('00000000-0000-4000-8000-000000000001', 'Welcome to {{project}}', '2026-01-01T00:00:00Z')
+ON CONFLICT (id) DO NOTHING;

package/templates/app/skeleton/.starciwork/features/system-health/index.yaml

@@ -0,0 +1,4 @@
+schema: work/feature@1
+id: system-health
+title: The liveness probe the platform asks before it routes traffic to the app.
+description: The API reports its liveness so the platform can check the application before routing traffic.

package/templates/app/skeleton/.starciwork/{features/index.yaml → index.yaml}

@@ -1,6 +1,6 @@
 schema: work/catalog@1
-id: {{project}}
-description: Product catalog of the features directory. One entry per feature; every record of a feature lives under its directory.
+id: "{{project}}"
+description: The application's product feature catalog.
 features:
   - id: system-health
     directory: features/system-health

package/templates/app/skeleton/README.md

@@ -4,7 +4,7 @@ One StarCi app: its back end in be/, its front end in fe/, one install at the ro
 
 ## Overview
 
-The app starts with one api app (be/apps/api), one Next app (fe/apps/web) and the liveness probe both serve.
+The app starts with the core api app (be/apps/core) and the cli app (be/apps/cli) over one primary database, two Next apps (fe/apps/landing, the public front door, and fe/apps/app, the product) over the shared packages fe/packages/{{project}}-ui and fe/packages/{{project}}-i18n.
 
 ## Stack
 
@@ -13,7 +13,7 @@ TypeScript everywhere; NestJS in be/, Next.js with next-intl in fe/; npm with on
 ## Repository layout
 
 - `be/`: the back end, `apps/<app>/src` composes `src/features` and `src/modules`; its tests live under `src/tests`.
-- `fe/`: the front end, one Next app per `apps/<app>`.
+- `fe/`: the front end, one Next app per `apps/<app>` and the shared workspace packages under `packages/` (the ui drawings and the next-intl stack both apps call).
 - `scripts/`: the app's operational scripts; `hfs.json` declares both sides.
 
 ## Development
@@ -27,9 +27,11 @@ npm run build:be
 npm run build:fe
 ```
 
-The api app reads `PORT` and `HTTP_SECURITY_ALLOWED_ORIGINS` (comma-separated origins allowed to send state-changing browser
-requests) at boot; every door is closed until it is marked public or sign-in is designed. The web app reads
-`NEXT_PUBLIC_SITE_URL`. A missing key stops the process with an error that names it.
+The core api app reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS` (comma-separated origins allowed to send state-changing browser
+requests) and `PRIMARY_DB_URL` at boot; every door is closed until it is marked public or sign-in is designed. The cli app reads
+`PRIMARY_DB_URL`: `npm run migrate` applies the migrations of the primary database before the api starts, and
+`npm run cli -- seed run` runs the dev seeds of `.starcistacks/dev/seeds` (run both from the app root). The product app reads
+`NEXT_PUBLIC_SITE_URL`, the landing `NEXT_PUBLIC_APP_URL` (the product app it hands the reader over to). A missing key stops the process with an error that names it.
 
 ## Work
 

package/templates/app/skeleton-lite/.sops.yaml

@@ -0,0 +1,3 @@
+# Lite secrets have encrypted twins only under .starcistacks/<environment>/secrets.
+# Set a project-owned age recipient before encrypting the first secret.
+creation_rules: []

package/templates/app/skeleton-lite/.starcistacks/dev/environment.json

@@ -0,0 +1,5 @@
+{
+  "environment": "dev",
+  "provider": "supabase",
+  "project": "{{project}}"
+}

package/templates/app/skeleton-lite/.starcistacks/dev/secrets/.gitkeep

@@ -0,0 +1 @@
+

package/templates/app/skeleton-lite/.starciwork/shell/index.yaml

@@ -0,0 +1,55 @@
+schema: work/layout-tree@1
+id: shell
+kind: shell
+state: todo
+rev: 1
+origin: planned
+productLocale:
+  default: vi
+  fallback: vi
+  locales:
+    - vi
+breakpoints:
+  - name: desktop
+    width: 1440
+    height: 900
+  - name: mobile
+    width: 390
+    height: 844
+themes:
+  - light
+apps:
+  - name: web
+    root: fe/apps/web
+    appDir: fe/apps/web/src/app
+    framework: next-app-router
+    localeParam: locale
+    nodes:
+      - id: /
+        parent: null
+        segment: /
+        segmentKind: root
+        url: /
+        origin: planned
+      - id: /[locale]
+        parent: /
+        segment: "[locale]"
+        segmentKind: dynamic
+        url: /[locale]
+        origin: planned
+        files:
+          layout:
+            path: fe/apps/web/src/app/[locale]/layout.tsx
+          page:
+            path: fe/apps/web/src/app/[locale]/page.tsx
+          loading:
+            path: fe/apps/web/src/app/[locale]/loading.tsx
+          error:
+            path: fe/apps/web/src/app/[locale]/error.tsx
+          not-found:
+            path: fe/apps/web/src/app/[locale]/not-found.tsx
+        layout:
+          component: AppLayout
+          chrome: visible
+          state: todo
+          rev: 1

package/templates/app/skeleton-lite/README.md

@@ -0,0 +1,40 @@
+# {{project}}
+
+One StarCi lite app: a Nest API in `be/`, one Next web app in `fe/`, and Supabase as the schema authority.
+
+## Overview
+
+The starter keeps one deployable API and one web app. The browser uses only the public Supabase client under row-level security; privileged Auth and Storage operations stay behind the API.
+
+## Stack
+
+TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, Supabase for Auth and PostgreSQL, npm workspaces, and Turbo for front-end tasks.
+
+## Repository layout
+
+- `supabase/`: local configuration, forward-only SQL migrations, seed data, and generated database types.
+- `be/`: the API, shared platform capabilities, verified identity admission, and privileged Supabase integrations.
+- `fe/`: the web app; all Supabase access is owned by `src/modules/db`.
+- `.starcistacks/`: value-free environment metadata and encrypted-secret custody.
+- `.starciwork/`: product workspace, brand, and shell records.
+
+## Development
+
+```sh
+npm install
+npm run contract:emit
+npm run typecheck
+npm run lint
+npm run build:be
+npm run build:fe
+```
+
+The API reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_URL`, `PRIMARY_DB_SCHEMA`, `SUPABASE_URL`, and `SUPABASE_SERVICE_ROLE_KEY`. The web app reads `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_SUPABASE_URL`, and `NEXT_PUBLIC_SUPABASE_ANON_KEY`. Missing configuration stops the relevant process with a named error; no template supplies credential defaults.
+
+## Database changes
+
+Create a forward-only migration under `supabase/migrations`, keep each table's RLS policies and grants beside the table, and run `npm run contract:emit` to refresh `supabase/types/database.types.ts`.
+
+## Work
+
+The product's Work records live in `.starciwork`.