@horka/app-forge 0.1.0

package/templates/packs/nuxt-web/docs-architecture/SEO_AND_ROUTING.md

@@ -0,0 +1,118 @@
+# SEO & ROUTING — mixed public/private apps on SSR
+
+The default product shape this pack assumes: public marketing pages (home, pricing, features,
+changelog…) and a private app behind auth — in ONE Nuxt codebase. This file is the recipe
+that keeps both worlds correct.
+
+## 1. SSR is on and stays on
+
+`ssr: true` is the pack default. Public pages must deliver their content **in the server
+response** — crawlers and link previews don't run your client fetches reliably, and users
+shouldn't watch spinners for static copy.
+
+Proof command (run it on every public page before calling it done):
+
+```bash
+curl -s http://localhost:3000/pricing | grep -i "your headline text"
+```
+
+If the content isn't in the HTML, the page is fetching client-side — fix the data fetching
+(CONVENTIONS.md §4: `useAsyncData` in setup, `onMounted` only with a `CLIENT-ONLY:` rationale).
+
+## 2. Auth policy lives ON the route — default deny
+
+Public pages declare their own policy, next to their own code:
+
+```ts
+// app/pages/pricing.vue
+definePageMeta({ auth: false })
+```
+
+The global middleware reads route meta and **default-denies** everything else:
+
+```ts
+// app/middleware/auth.global.ts — add the day auth lands; the meta convention starts day one
+export default defineNuxtRouteMiddleware((to) => {
+  if (to.meta.auth === false) return                    // page opted out, explicitly
+  const { isAuthenticated } = useSession()              // your auth provider's session check
+  if (!isAuthenticated.value) {
+    return navigateTo({ path: '/', query: { redirect: to.fullPath } })
+  }
+})
+```
+
+Absolute rules:
+- **Never a name allowlist** (`['index', 'pricing', …]`) — it's a second route table that
+  silently drifts from the real one (ANTI_PATTERNS.md #2).
+- New pages are **private by default**; making one public is a one-line, reviewable, greppable
+  diff on the page itself: `grep -rn "auth: false" app/pages` lists the public surface.
+- The redirect target preserves `redirect=` so login returns the user where they were headed.
+
+> 📖 **War story:** a production team used a hand-maintained array of public page names in the
+> auth middleware. A public changelog page shipped but was never added to the list — anonymous
+> visitors (and crawlers) were silently 302'd to the homepage **for weeks**. No error, no log,
+> no failing test; the sitemap even advertised the URL. Route-meta + default-deny makes that
+> failure impossible: the page carries its own policy, and forgetting it fails *closed* (a
+> private page stays private) instead of breaking the public site invisibly.
+
+## 3. Sitemap & robots — explicit allowlist, never the route table
+
+- The sitemap lists **only an explicit array of public URLs**, maintained next to the sitemap
+  config. Never auto-generate from the route table — your route table contains the private app.
+  With `@nuxtjs/sitemap`: `excludeAppSources: true` + an explicit `urls` list.
+- Adding a public page = page file + `auth: false` + sitemap entry + i18n module. Put this
+  4-item checklist in the PR template.
+- Private sections also send `X-Robots-Tag` via route rules (belt and braces with the auth wall):
+
+```ts
+routeRules: {
+  '/':            { prerender: true },                       // pure-static marketing
+  '/pricing':     { prerender: true },
+  '/changelog':   { swr: 3600 },                             // public but updated often
+  '/app/**':      { headers: { 'X-Robots-Tag': 'noindex' } } // private app surface
+},
+```
+
+- **Staging must never be indexed**: gate a global `robots: noindex, nofollow` meta on the
+  environment from runtime config — not on `NODE_ENV`, which is `production` on staging builds.
+
+## 4. Per-page meta
+
+Every public page owns its meta in setup — no global defaults pretending to be content:
+
+```ts
+useSeoMeta({
+  title: t('pricing.meta.title'),
+  description: t('pricing.meta.description'),
+  ogTitle: t('pricing.meta.title'),
+  ogImage: `${config.public.baseUrl}/og/pricing.png`,   // ABSOLUTE URL — relative og:image is ignored
+  twitterCard: 'summary_large_image',
+})
+```
+
+- `og:image` and canonical URLs must be **absolute**, built from `runtimeConfig.public.baseUrl`
+  — never hardcoded hostnames (they rot across environments).
+- One `<h1>` per page; headings follow document order — crawlers and screen readers share it.
+- Dynamic public pages (blog posts…) set meta from the same `useAsyncData` payload that renders
+  the content, so meta and body can't diverge.
+
+## 5. Routing hygiene
+
+- File-based routes only; no `hashMode`. Deep links into the private app must survive the
+  login round-trip (the `redirect=` query above).
+- Route params are validated in the page (`validate`) — a malformed id is a 404, not a blank
+  page with a console error.
+- Error states route through `error.vue` with correct status codes:
+  `throw createError({ statusCode: 404, statusMessage: 'Not found' })` during SSR returns a
+  real 404 to crawlers — a soft-404 (200 + "not found" text) poisons indexing.
+- i18n URL strategy: app-only products may hide locale (`no_prefix`); indexable multilingual
+  marketing needs per-locale URLs + `hreflang` (I18N.md §5). Record the choice in DECISIONS.md.
+
+## 6. Pre-ship checklist (public pages)
+
+- [ ] `definePageMeta({ auth: false })` present
+- [ ] Content visible in `curl` output (SSR-rendered, no client fetch for primary content)
+- [ ] `useSeoMeta` with title/description/absolute ogImage
+- [ ] Sitemap entry added; staging still noindex
+- [ ] i18n module exists in every locale (parity check green)
+- [ ] Status codes correct for the page's error paths (404 via `createError`, not a soft-404)

package/templates/packs/nuxt-web/gitignore

@@ -0,0 +1,18 @@
+# Nuxt
+.nuxt/
+.output/
+dist/
+node_modules/
+
+# env — never commit real env files
+.env
+.env.*
+
+# test artifacts — generated reports are claims, not proof (ANTI_PATTERNS.md #10)
+coverage/
+playwright-report/
+test-results/
+
+# misc
+*.log
+.cache/

package/templates/packs/nuxt-web/nuxt.config.ts

@@ -0,0 +1,49 @@
+// Layer mapping and the reasoning behind every block: docs-architecture/ARCHITECTURE.md
+export default defineNuxtConfig({
+  compatibilityDate: '2025-07-15',
+
+  // SSR is ON and stays on. Public pages must render their content server-side;
+  // data fetching happens in setup (useAsyncData), never in onMounted without a
+  // written CLIENT-ONLY rationale. See docs-architecture/SEO_AND_ROUTING.md §1.
+  ssr: true,
+
+  devtools: { enabled: true },
+
+  css: [
+    '~/assets/css/tokens.css', // L0 — the ONLY place visual values are defined
+    '~/assets/css/main.css',
+  ],
+
+  // Module auto-registration: DS modules (L3, domain-blind) and feature modules (L4)
+  // expose their components/ subfolder. Adding a module requires zero config here.
+  components: [
+    // NOTE: glob goes in `pattern`, not `path` — a glob inside `path` is silently
+    // ignored by the scanner (zero components registered, no warning).
+    { path: '~/designSystem', pattern: '**/components/**', pathPrefix: false },
+    { path: '~/features', pattern: '**/components/**', pathPrefix: false },
+  ],
+
+  imports: {
+    dirs: [
+      '~/designSystem/**/composables',
+      '~/features/**/composables',
+    ],
+  },
+
+  runtimeConfig: {
+    // Server-only values (override at runtime: NUXT_<KEY>). Secrets live HERE.
+    public: {
+      // Client-visible values (override at runtime: NUXT_PUBLIC_<KEY>) — never secrets.
+      apiBaseUrl: '',
+      baseUrl: 'http://localhost:3000',
+      environment: 'development',
+    },
+  },
+
+  app: {
+    head: {
+      htmlAttrs: { lang: 'en' },
+      title: '{{PROJECT_NAME}}',
+    },
+  },
+})

package/templates/packs/nuxt-web/pack.json

@@ -0,0 +1,11 @@
+{
+  "id": "nuxt-web",
+  "label": "Web app — Nuxt 4 / Vue 3 / TypeScript",
+  "languages": ["typescript", "vue"],
+  "idPrompt": "App identifier (reverse-DNS)",
+  "requirements": [
+    "Node.js 20+ (LTS) and npm",
+    "Playwright browsers for e2e (one-time): npx playwright install"
+  ],
+  "notes": "Skeleton builds and tests day one: npm install && npm run test && npm run build"
+}

package/templates/packs/nuxt-web/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{BUNDLE_ID}}",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "nuxt dev",
+    "build": "nuxt build",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "postinstall": "nuxt prepare",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test"
+  },
+  "dependencies": {
+    "nuxt": "^4.0.0",
+    "vue": "^3.5.0",
+    "vue-router": "^4.5.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "@vitejs/plugin-vue": "^5.2.0",
+    "@vue/test-utils": "^2.4.6",
+    "happy-dom": "^20.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/packs/nuxt-web/playwright.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig, devices } from '@playwright/test'
+
+// E2E suite — real dependency, real config, runs from a clean checkout
+// (one-time per machine: `npx playwright install`). Specs live in tests/e2e ONLY;
+// vitest owns app/** and tests/unit/**. Reports are gitignored — a committed
+// report is a claim, a green run is proof (ANTI_PATTERNS.md #10).
+
+// One source of truth for the e2e origin, so `use.baseURL` and `webServer.url` can never
+// drift apart. Override with PLAYWRIGHT_BASE_URL to point at a deployed preview.
+//
+// ⚠️ Port-collision trap: locally `reuseExistingServer` is true, so if ANYTHING is already
+// listening on this port (a stale `nuxt dev`, another app, a previous crashed run) Playwright
+// silently tests THAT process instead of a fresh build — a false green or false red that has
+// nothing to do with your code. Port 3000 is heavily contended; this skeleton uses a less
+// common 4173. If a run looks wrong, kill stragglers first: `lsof -ti:4173 | xargs kill`,
+// or set PLAYWRIGHT_BASE_URL to a clean port. In CI, reuseExistingServer is false (always fresh).
+const PORT = Number(process.env.PLAYWRIGHT_PORT ?? 4173)
+const BASE_URL = process.env.PLAYWRIGHT_BASE_URL ?? `http://localhost:${PORT}`
+
+export default defineConfig({
+  testDir: 'tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: [['html', { open: 'never' }]],
+  use: {
+    baseURL: BASE_URL,
+    trace: 'on-first-retry',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+  webServer: {
+    command: `npm run dev -- --port ${PORT}`,
+    url: BASE_URL,
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+})

package/templates/packs/nuxt-web/server/api/health.get.ts

@@ -0,0 +1,7 @@
+// The SINGLE health endpoint — Docker HEALTHCHECK, orchestrator checks, deploy
+// gates and uptime monitoring all point HERE and nowhere else (OPS_WEB.md §7).
+export default defineEventHandler(() => ({
+  status: 'ok',
+  service: '{{BUNDLE_ID}}',
+  time: new Date().toISOString(),
+}))

package/templates/packs/nuxt-web/tests/e2e/home.spec.ts

@@ -0,0 +1,19 @@
+import { expect, test } from '@playwright/test'
+
+// Example e2e spec — proves the wiring is real (server boots, page SSRs, DS button reacts).
+// One-time per machine: `npx playwright install`. Then: `npm run test:e2e`.
+test('home page renders server-side and the DS button responds', async ({ page }) => {
+  await page.goto('/')
+  await expect(page.getByRole('heading', { level: 1 })).toContainText('{{PROJECT_NAME}}')
+
+  const button = page.getByRole('button', { name: /clicked/i })
+  await expect(button).toContainText('0')
+  await button.click()
+  await expect(button).toContainText('1')
+})
+
+test('health endpoint answers', async ({ request }) => {
+  const response = await request.get('/api/health')
+  expect(response.ok()).toBeTruthy()
+  expect((await response.json()).status).toBe('ok')
+})

package/templates/packs/nuxt-web/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  // https://nuxt.com/docs/guide/concepts/typescript
+  "extends": "./.nuxt/tsconfig.json"
+}

package/templates/packs/nuxt-web/vitest.config.ts

@@ -0,0 +1,23 @@
+import { fileURLToPath } from 'node:url'
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vitest/config'
+
+// Unit tests run WITHOUT booting Nuxt: pure domain code and DS components mount
+// standalone. Keep it that way — this is the fast feedback loop (ARCHITECTURE.md §7).
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '~': fileURLToPath(new URL('./app', import.meta.url)),
+      '@': fileURLToPath(new URL('./app', import.meta.url)),
+    },
+  },
+  test: {
+    environment: 'happy-dom',
+    // tests/e2e belongs to Playwright — vitest must never pick it up
+    include: [
+      'app/**/*.{test,spec}.ts',
+      'tests/unit/**/*.{test,spec}.ts',
+    ],
+  },
+})

package/templates/packs/swift-ios/CLAUDE.md

@@ -0,0 +1,64 @@
+# {{PROJECT_NAME}} — Claude Code Operating Manual
+
+This project was scaffolded by **AppForge** (pack: iOS/Swift): a Claude-Code-first
+architecture extracted from production apps. You (Claude) are the team lead AND the
+primary developer. Follow this manual exactly — it encodes hard-won lessons, not preferences.
+
+## Identity
+- App: **{{PROJECT_NAME}}** · Bundle id: `{{BUNDLE_ID}}` · iOS 26+ · Swift 6.2 (strict concurrency)
+- Backend: CloudKit-only by default (container `iCloud.{{BUNDLE_ID}}`) — adapt if the PRD says otherwise.
+
+## Session protocol (MANDATORY)
+1. **Session start**: run the `restore-context` skill — read `.claude/memory/*.md` before doing anything. Never invent project facts.
+2. **Empty project / new idea**: run the `kickoff` skill — it interviews the user, writes the PRD, plans slices, then builds autonomously.
+3. **After significant work**: update `.claude/memory/PROJECT_STATE.md` (and DECISIONS/NEXT_STEPS when relevant) — `save-context` skill.
+
+## Architecture (read the docs before coding)
+The knowledge base lives in `docs-architecture/`. Read the relevant doc BEFORE touching that area:
+
+| You are about to… | Read first |
+|---|---|
+| understand the layer model (stack-agnostic) | `ARCHITECTURE_PRINCIPLES.md` |
+| plan/deliver slices, validate, update memory | `DELIVERY.md` |
+| product spans repos (API + SDK + clients) | `MULTI_REPO_CONTRACT.md` |
+| ship/consume a typed SDK | `SDK_CONTRACT.md` |
+| accept user-supplied URLs (webhooks…) | `SECURITY_USER_URLS.md` |
+| write any documentation | `DOCS_PLACEMENT.md` |
+| add caching/feature flags/auth shortcuts | `ANTI_PATTERNS.md` |
+| add/move any file, create a feature | `ARCHITECTURE.md` |
+| write any Swift code | `CONVENTIONS.md` |
+| add a screen, sheet, deeplink, push routing | `NAVIGATION.md` |
+| touch CloudKit, CKShare, sync, subscriptions | `CLOUDKIT_GUIDE.md` |
+| style anything (colors, fonts, spacing) | `DESIGN_SYSTEM.md` |
+| write or modify domain logic | `TESTING.md` |
+| build, run, validate, debug on device | `WORKFLOW.md` |
+
+Layer summary (universal contract in ARCHITECTURE_PRINCIPLES.md, Swift mapping in ARCHITECTURE.md):
+L0 `{{PROJECT_NAME}}DS` tokens · L1 Ops (create when needed) · L2 `DataLayer` (implements L3 contracts) ·
+L3 `{{PROJECT_NAME}}Core` (pure domain — **never imports SwiftUI**) + DS `Components/` (Core UI) ·
+L4 app `Module/` (shared feature bricks) · L5 app `App/` + `Store/` + `Tools/`. Imports point downward only.
+
+## Non-negotiable rules
+- **Packages first**: `swift build`/`swift test --package-path Packages/<X>` before any `xcodebuild`. Fast, precise errors.
+- **Never claim done without proof**: package tests green + app build green + (for UI) a simulator screenshot you actually looked at.
+- **Design tokens only**: no hardcoded colors/fonts/spacing in app code — everything through `{{PROJECT_NAME}}DS`.
+- **Pure domain logic**: engines are `nonisolated enum`s with injected `Calendar`/dates. Every rule ships with a test.
+- **Logging**: `os.Logger` with `privacy: .public` interpolation (print() is invisible on device).
+- **Memory is law**: contradictions between memory files and code → code wins, then fix the memory file.
+
+## Build commands
+```bash
+# per-package loop (seconds)
+swift build --package-path Packages/{{PROJECT_NAME}}Core
+swift test  --package-path Packages/{{PROJECT_NAME}}Core
+
+# app target (after xcodegen generate, only when packages are green)
+xcodebuild -project {{PROJECT_NAME}}.xcodeproj -scheme {{PROJECT_NAME}} \
+  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
+  -derivedDataPath /tmp/{{PROJECT_NAME}}_dd build 2>&1 | grep -E "error:|BUILD"
+```
+Simulator validation: use the `ios-simulator` MCP (install_app → launch_app → screenshot → look at it).
+
+## Git
+- Never push without explicit user approval. Feature branches; commit format `add/update/fix(scope) - description`.
+- No AI attribution in commits or file headers.

package/templates/packs/swift-ios/Packages/DataLayer/Package.swift

@@ -0,0 +1,21 @@
+// swift-tools-version: 6.2
+import PackageDescription
+
+let package = Package(
+    name: "DataLayer",
+    platforms: [.iOS(.v26), .macOS(.v15)],
+    products: [.library(name: "DataLayer", targets: ["DataLayer"])],
+    dependencies: [
+        .package(path: "../{{PROJECT_NAME}}Core"),
+    ],
+    targets: [
+        // REAL repository implementations only (CloudKit, URLSession, …). Protocols AND their
+        // InMemory variant (tests/previews/offline) live in Core — DataLayer ships IO-backed
+        // impls of those contracts. See docs-architecture/ARCHITECTURE.md §2.
+        .target(
+            name: "DataLayer",
+            dependencies: [.product(name: "{{PROJECT_NAME}}Core", package: "{{PROJECT_NAME}}Core")],
+            swiftSettings: [.swiftLanguageMode(.v6)]
+        ),
+    ]
+)

package/templates/packs/swift-ios/Packages/DataLayer/Sources/DataLayer/DataLayer.swift

@@ -0,0 +1,11 @@
+import {{PROJECT_NAME}}Core
+
+/// PERMANENT file — do not delete (an SPM target with zero sources does not build).
+/// DataLayer hosts the REAL repository implementations (CloudKit, URLSession, database…),
+/// each conforming to a contract declared in {{PROJECT_NAME}}Core (ports & adapters).
+/// Real implementations are added by slices that need them; until then this marker keeps
+/// the target alive. See docs-architecture/CLOUDKIT_GUIDE.md before writing a CloudKit impl.
+public enum DataLayer {
+    /// Bump when a real implementation lands, so the placeholder's job is visible in reviews.
+    public static let implementations: [String] = []
+}

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}Core/Package.swift

@@ -0,0 +1,20 @@
+// swift-tools-version: 6.2
+import PackageDescription
+
+let package = Package(
+    name: "{{PROJECT_NAME}}Core",
+    platforms: [.iOS(.v26), .macOS(.v15)],
+    products: [.library(name: "{{PROJECT_NAME}}Core", targets: ["{{PROJECT_NAME}}Core"])],
+    targets: [
+        // Pure domain logic. NEVER imports SwiftUI/UIKit. Fully testable with `swift test`.
+        .target(
+            name: "{{PROJECT_NAME}}Core",
+            swiftSettings: [.swiftLanguageMode(.v6)]
+        ),
+        .testTarget(
+            name: "{{PROJECT_NAME}}CoreTests",
+            dependencies: ["{{PROJECT_NAME}}Core"],
+            swiftSettings: [.swiftLanguageMode(.v6)]
+        ),
+    ]
+)

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}Core/Sources/{{PROJECT_NAME}}Core/Domain/SampleItem.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+/// Sample domain entity — replace at kickoff. Shows the conventions:
+/// value type, Identifiable + Sendable, explicit dates injected (never read the clock here).
+public struct SampleItem: Identifiable, Hashable, Sendable {
+    public let id: UUID
+    public var title: String
+    public var createdAt: Date
+
+    public init(id: UUID = UUID(), title: String, createdAt: Date) {
+        self.id = id
+        self.title = title
+        self.createdAt = createdAt
+    }
+}

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}Core/Sources/{{PROJECT_NAME}}Core/Engine/SampleEngine.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+/// Sample pure engine — replace at kickoff. Conventions on display:
+/// `enum` (no instances), nonisolated pure functions, `Calendar` injected for determinism.
+public enum SampleEngine {
+    /// Items created on the same calendar day as `reference`.
+    public static func items(
+        _ items: [SampleItem],
+        onSameDayAs reference: Date,
+        calendar: Calendar = .current
+    ) -> [SampleItem] {
+        items.filter { calendar.isDate($0.createdAt, inSameDayAs: reference) }
+    }
+}

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}Core/Sources/{{PROJECT_NAME}}Core/Repository/SampleItemRepository.swift

@@ -0,0 +1,27 @@
+import Foundation
+
+/// Sample repository pair — replace at kickoff. The pattern (see docs-architecture/ARCHITECTURE.md §2):
+/// the CONTRACT and the InMemory reference implementation live HERE in Core (testable without IO
+/// frameworks); the real backend implementation (CloudKit/network) lives in DataLayer and imports
+/// this protocol — the one sanctioned upward arrow (ports & adapters).
+public protocol SampleItemRepository: Sendable {
+    func loadItems() async throws -> [SampleItem]
+    func save(_ item: SampleItem) async throws
+}
+
+/// Backs tests, previews and offline-first development.
+public actor InMemorySampleItemRepository: SampleItemRepository {
+    private var items: [SampleItem] = []
+
+    public init() {}
+
+    public func loadItems() async throws -> [SampleItem] { items }
+
+    public func save(_ item: SampleItem) async throws {
+        if let index = items.firstIndex(where: { $0.id == item.id }) {
+            items[index] = item          // update in place — keeps stable order
+        } else {
+            items.append(item)
+        }
+    }
+}

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}Core/Tests/{{PROJECT_NAME}}CoreTests/SampleEngineTests.swift

@@ -0,0 +1,32 @@
+import Foundation
+import Testing
+@testable import {{PROJECT_NAME}}Core
+
+/// Swift Testing (@Test/#expect), deterministic dates via a Fixture helper. This is the pattern
+/// every engine test follows. Delete alongside SampleEngine at kickoff.
+@Suite struct SampleEngineTests {
+    /// Fixed Gregorian/UTC calendar — never `Calendar.current` (its timezone moves day boundaries
+    /// between machines/CI and makes hour/day-boundary tests flaky). Inject it everywhere.
+    private static let calendar: Calendar = {
+        var calendar = Calendar(identifier: .gregorian)
+        calendar.timeZone = TimeZone(identifier: "UTC")!
+        return calendar
+    }()
+
+    private static func date(_ year: Int, _ month: Int, _ day: Int) -> Date {
+        var components = DateComponents()
+        (components.year, components.month, components.day) = (year, month, day)
+        return calendar.date(from: components)!
+    }
+
+    @Test func sameDayFilterKeepsOnlyMatchingItems() {
+        let monday = Self.date(2026, 6, 1)
+        let tuesday = Self.date(2026, 6, 2)
+        let items = [
+            SampleItem(title: "a", createdAt: monday),
+            SampleItem(title: "b", createdAt: tuesday),
+        ]
+        let result = SampleEngine.items(items, onSameDayAs: monday, calendar: Self.calendar)
+        #expect(result.map(\.title) == ["a"])
+    }
+}

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}DS/Package.swift

@@ -0,0 +1,17 @@
+// swift-tools-version: 6.2
+import PackageDescription
+
+let package = Package(
+    name: "{{PROJECT_NAME}}DS",
+    platforms: [.iOS(.v26), .macOS(.v15)],
+    products: [.library(name: "{{PROJECT_NAME}}DS", targets: ["{{PROJECT_NAME}}DS"])],
+    targets: [
+        .target(
+            name: "{{PROJECT_NAME}}DS",
+            swiftSettings: [
+                .swiftLanguageMode(.v6),
+                .defaultIsolation(MainActor.self),
+            ]
+        ),
+    ]
+)

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}DS/Sources/{{PROJECT_NAME}}DS/Color+DS.swift

@@ -0,0 +1,18 @@
+import SwiftUI
+
+/// Semantic palette. Dark-first. Rename/extend at kickoff — never bypass with raw values.
+public extension Color {
+    enum DS {
+        public static let accent = Color(red: 0.35, green: 0.45, blue: 1.00)
+        public static let accentSecondary = Color(red: 0.55, green: 0.30, blue: 0.95)
+        public static let background = Color(red: 0.039, green: 0.039, blue: 0.059)
+        public static let surface = Color.white.opacity(0.06)
+        public static let surfaceStrong = Color.white.opacity(0.10)
+        public static let stroke = Color.white.opacity(0.12)
+        public static let textPrimary = Color.white
+        public static let textSecondary = Color.white.opacity(0.6)
+        public static let textTertiary = Color.white.opacity(0.4)
+        public static let success = Color(red: 0.20, green: 0.85, blue: 0.45)
+        public static let danger = Color(red: 1.00, green: 0.27, blue: 0.36)
+    }
+}

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}DS/Sources/{{PROJECT_NAME}}DS/Components/DSCard.swift

@@ -0,0 +1,22 @@
+import SwiftUI
+
+/// Starter Core-UI component (L3 — domain-blind). The Components/ folder grows at kickoff;
+/// every component here uses tokens only and knows nothing about the domain.
+public struct DSCard<Content: View>: View {
+    private let content: Content
+
+    public init(@ViewBuilder content: () -> Content) {
+        self.content = content()
+    }
+
+    public var body: some View {
+        content
+            .padding(DS.Padding.m)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background(Color.DS.surface, in: RoundedRectangle(cornerRadius: DS.Radius.m))
+            .overlay(
+                RoundedRectangle(cornerRadius: DS.Radius.m)
+                    .stroke(Color.DS.stroke, lineWidth: DS.Size.hairline)
+            )
+    }
+}

package/templates/packs/swift-ios/Packages/{{PROJECT_NAME}}DS/Sources/{{PROJECT_NAME}}DS/DS.swift

@@ -0,0 +1,36 @@
+import SwiftUI
+
+/// Design system namespace. ALL visual tokens live here — app code never hardcodes values.
+public enum DS {
+    /// Responsive scaling hook (1.0 for now; derive from screen size later if needed).
+    public static let ratio: CGFloat = 1.0
+
+    public enum Padding {
+        public static let xs: CGFloat = 4 * DS.ratio
+        public static let s: CGFloat = 8 * DS.ratio
+        public static let m: CGFloat = 16 * DS.ratio
+        public static let l: CGFloat = 24 * DS.ratio
+        public static let xl: CGFloat = 40 * DS.ratio
+    }
+
+    public enum Radius {
+        public static let s: CGFloat = 10 * DS.ratio
+        public static let m: CGFloat = 16 * DS.ratio
+        public static let l: CGFloat = 24 * DS.ratio
+        public static let pill: CGFloat = 999
+    }
+
+    public enum Size {
+        public static let hairline: CGFloat = 1
+        public static let icon: CGFloat = 24 * DS.ratio
+    }
+
+    /// Signature gradients — customize at kickoff to match the app's brand.
+    public enum Gradients {
+        public static let brand = LinearGradient(
+            colors: [Color.DS.accent, Color.DS.accentSecondary],
+            startPoint: .topLeading,
+            endPoint: .bottomTrailing
+        )
+    }
+}