@finesoft/front 0.5.1 → 0.5.3

package/docs/engineering/ci-release-flow.md

@@ -1,244 +1,57 @@
-# Engineering: CI & release flow
+# Engineering: validation and release
 
-How the framework itself is released, and how to set up the same workflow for an app that depends on it.
+`@finesoft/front` and `@finesoft/create-app` are the published packages. Core, Web, Browser, SSR and Server remain private. The front build bundles their implementation into explicit ESM entries and declarations. Each native renderer keeps its selected UI peer external.
 
-## What ships
+## Local checks
 
-Only `@finesoft/front` is published to npm. The internal `core` / `browser` / `ssr` / `server` packages are bundled into `front` via `tsdown`'s `noExternal: [@finesoft/*]`.
-
-This means:
-
-- One npm package for users to install
-- Internal refactors don't bump multiple versions
-- Single CHANGELOG to read
-
-`create-finesoft-app` is its own published package (a CLI), separate from the framework runtime.
-
-## The release workflow
-
-The repo ships a single `.github/workflows/release.yml` that handles everything inline. Trigger: push to `main`.
-
-```
-push to main
-    │
-    ▼
-Checkout main (with PAT, not GITHUB_TOKEN)
-    │
-    ▼
-Reconcile npm registry with main
-    ├── npm == main? → continue
-    ├── main > npm? → catch-up publish current main version
-    └── npm > main? → error, manual investigation
-    │
-    ▼
-Generate auto-changeset (one patch per push)
-    │
-    ▼
-Apply version bump
-    ├── changes? → continue
-    └── no changes? → done, nothing to publish
-    │
-    ▼
-Commit "chore(release): version packages"
-    │
-    ▼
-Build all packages, publish @finesoft/front to npm
-    │
-    ▼
-Push commit + tag back to main (with rebase retry)
-```
-
-### Why one inline workflow instead of changesets/action's PR mode
-
-The standard changesets workflow opens a PR ("Version Packages") that, when merged, triggers a second workflow run that publishes. **But `GITHUB_TOKEN`-merged commits don't trigger subsequent workflows** (GitHub's anti-recursion safety) — the publish never fires. The inline workflow does everything in one run, no PR hop.
-
-### Why a PAT instead of `GITHUB_TOKEN`
-
-The repo has a ruleset enforcing signed commits, linear history, and required PRs on `main`. Bypass actors include `RepositoryRole=5 (admin)` but **not** `github-actions[bot]`. GitHub's UI does not allow adding the bot to the bypass list. Push from a PAT owned by an admin user matches the existing bypass entry.
-
-The PAT is `Contents: Read & Write` only — the minimum needed for `git push`.
-
-## Concurrency
-
-```yaml
-concurrency: release-${{ github.ref }}
+```sh
+vp install
+vp run --filter '@finesoft/front...' build
+vp check
+vp test --coverage
+vp run -r build
+vp exec node scripts/verify-publish-transforms.mjs
+vp exec node scripts/verify-runtime-boundaries.mjs
 ```
 
-Multiple pushes to `main` queue rather than cancel. This matters because:
-
-- Cancellation mid-publish leaves npm in an inconsistent state
-- Each push must wait for the previous to finish to avoid version-number races
-- The next run's reconcile step picks up whatever the previous one published
-
-## Idempotency
-
-`changeset publish` skips versions already on npm. So if push to `main` fails after publish:
+`vp pack` is the library build command. `vp pm pack` creates a local package tarball. Front's paired prepack/postpack scripts rewrite its publish manifest and restore the exact working manifest, including when preparation fails. Scaffolder preparation copies the current six templates and makes their package and TypeScript configuration standalone.
 
-- npm: has version 0.1.75
-- main: stuck at 0.1.74
+## Repository automation
 
-The next release run's reconcile detects `main < npm`, refuses to "catch up backwards," and errors out. Manual remediation: open a PR that bumps `packages/front/package.json` to match npm and merges. Subsequent pushes resume normally.
+Both Quality jobs first build front and its workspace dependencies. The root Vite configuration loads the controller type generator, which imports the built core package; this preparation is required on a fresh checkout.
 
-## Setting up the same for an app
+Pull requests run Quality (`vp check` and `vp test --coverage`). A push to `main` starts Release, which calls the same Quality workflow and waits for both checks to pass. CodeQL runs independently over `packages/{core,web,browser,ssr,server,front}/src/**`.
 
-Most apps don't need a publish step — they have deploys instead. But the changeset + auto-bump shape still works:
+Release checks out the tested commit, generates a patch changeset for both public packages, applies Changesets (including any explicit minor/major changesets), updates the lockfile and builds. It then pushes the version commit to `main` with the built-in `GITHUB_TOKEN` before publishing to npm. If another push advances `main`, publication stops; the newer push gets its own validation and release. The workflow never rebases an already-built artifact or overwrites newer commits. Git tags are pushed after npm publication succeeds.
 
-```yaml
-name: Release
+The publishing job uses a GitHub-hosted runner with `id-token: write`, no dependency cache and no npm token. Changesets invokes the repository's pnpm 11 through Vite+; pnpm supports npm OIDC and automatic provenance natively. Both public packages declare their source repository and public registry. `RELEASE_PUSH_TOKEN` and `NPM_TOKEN` are no longer used.
 
-on:
-    push:
-        branches:
-            - main
+### npm configuration
 
-concurrency: release-${{ github.ref }}
+In Settings for **each** of `@finesoft/front` and `@finesoft/create-app`, add a GitHub Actions trusted publisher:
 
-jobs:
-    release:
-        runs-on: ubuntu-latest
-        if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
-        permissions:
-            contents: write
-        steps:
-            - uses: actions/checkout@v5
-              with:
-                  ref: main
-                  fetch-depth: 0
-                  token: ${{ secrets.RELEASE_PUSH_TOKEN }}
+| Field                | Value                                                 |
+| -------------------- | ----------------------------------------------------- |
+| Organization or user | `GaKireiTsuki`                                        |
+| Repository           | `finesoft-front`                                      |
+| Workflow filename    | `release.yml`                                         |
+| Environment name     | Leave empty; the workflow does not use an environment |
+| Allow npm publish    | Enabled for this automatic release workflow           |
 
-            - uses: voidzero-dev/setup-vp@v1
-              with:
-                  node-version: 24
-                  cache: true
+Keep “Require two-factor authentication and disallow bypass 2fa tokens” selected; it is compatible with trusted publishing. This pipeline publishes directly, so a stage-only connection cannot authorize it. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/). Saving the connection alone does not prove publication works: verify the first Release run and the actual versions on npm.
 
-            - run: vp install --frozen-lockfile
+### Retry a failed release
 
-            - name: Configure git
-              run: |
-                  git config user.name "github-actions[bot]"
-                  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+After fixing the cause, select **Release → Run workflow → main**, or run:
 
-            - name: Generate auto changeset
-              run: vp run release:auto:changeset
-
-            - name: Apply version bump
-              id: bump
-              run: |
-                  vp run version
-                  if git diff --quiet; then
-                      echo "should_publish=false" >> "$GITHUB_OUTPUT"
-                  else
-                      NEW=$(node -p "require('./package.json').version")
-                      echo "version=$NEW" >> "$GITHUB_OUTPUT"
-                      echo "should_publish=true" >> "$GITHUB_OUTPUT"
-                  fi
-
-            - name: Commit version
-              if: steps.bump.outputs.should_publish == 'true'
-              run: |
-                  git add -A
-                  git commit -m "chore(release): version packages"
-
-            - name: Build
-              if: steps.bump.outputs.should_publish == 'true'
-              run: vp run build
-
-            - name: Deploy
-              if: steps.bump.outputs.should_publish == 'true'
-              run: vp run deploy # your deploy command
-
-            - name: Push tag and commit
-              if: steps.bump.outputs.should_publish == 'true'
-              run: git push --follow-tags origin HEAD:main
+```sh
+gh workflow run release.yml --ref main
 ```
 
-Replace `vp run deploy` with your platform's deploy command (Vercel, Cloudflare, your own infra).
-
-## Conventional commits + auto-changeset
-
-The `release:auto:changeset` script (in this repo, generates one patch changeset per push) is intentionally simple — every merged PR becomes one patch bump. For semver-driven versioning, replace it with a script that:
-
-- Reads `git log` since the last tag
-- Maps commit prefixes (`feat:`, `fix:`, `BREAKING:`) to changeset types
-- Writes the right `.changeset/*.md`
-
-The framework's repo uses patch-only because:
-
-- Every push is a small change; large changes go through review and become small commits anyway
-- Real breaking changes are rare and warrant manual changesets
-- It avoids a class of "the prefix lies" bugs
-
-Pick the policy that matches how your team commits.
-
-## Per-PR validation (`quality.yml`)
-
-The repo also has a `quality.yml` workflow on PRs:
-
-```yaml
-on:
-    pull_request:
-    push:
-        branches:
-            - main
-
-jobs:
-    coverage:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v5
-            - uses: voidzero-dev/setup-vp@v1
-              with: { node-version: 24, cache: true }
-            - run: vp install --frozen-lockfile
-            - run: vp test --coverage
-            - uses: actions/upload-artifact@v7
-              with:
-                  name: coverage-report
-                  path: reports/coverage
-                  if-no-files-found: error
-```
-
-The `check` job (format + lint + types) is gated off by `if: false` in this repo because Vite+ runs them all locally via pre-commit. Re-enable it if your team doesn't run pre-commit hooks consistently.
-
-## CodeQL
-
-The repo enables CodeQL on a schedule and PRs. Scan scope is restricted to `packages/{core,browser,ssr,server,front}/src/**` — tests, templates, scripts, and the scaffolder are excluded.
-
-For application repos, enable the default CodeQL config — its noise is low and it catches real issues (open redirects, SQL injection, secret exposure).
-
-## Required status checks
-
-The repo ruleset requires:
-
-- `Coverage` (from `quality.yml`)
-- `CodeQL`
-
-PRs cannot merge until both pass. The release workflow bypasses these via the admin PAT — release runs after merge, on `main`, so the checks already passed on the PR.
-
-## Migration: from changesets PR mode to inline
-
-If you're moving an existing repo from `changesets/action` (PR mode):
-
-1. Delete the old release workflow
-2. Create the inline workflow above
-3. Generate a fine-grained PAT, store as `RELEASE_PUSH_TOKEN`
-4. The first push to main after this change will:
-    - Detect main == npm (no catch-up needed)
-    - Generate one patch changeset
-    - Bump + publish + push back to main
-
-If there's a pending "Version Packages" PR from the old workflow, close it without merging. The auto-changeset will pick up everything from there.
-
-## What can go wrong
+Manual dispatch validates and builds the versions already in `main`; it does **not** create another changeset or bump versions. Changesets skips versions already present on npm, so partial publication can be retried. The tag step restores missing release tags. If failure occurred before the version commit reached `main`, retry the original push run while its commit is still the branch head, or push the correction to start a new release.
 
-| Symptom                                         | Cause                                                                             | Fix                                                            |
-| ----------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `[remote rejected] HEAD -> main`                | PAT actor not in ruleset bypass; PAT lacks `Contents: Write`                      | Verify PAT scope; confirm push actor is an admin user          |
-| `npm ... is ahead of main`                      | Previous run published but failed to push                                         | Open a PR syncing `packages/front/package.json` to npm version |
-| Workflow doesn't trigger after a release commit | `if: "!startsWith(github.event.head_commit.message, 'chore(release):'"` filtering | Working as intended — recursion prevention                     |
-| Pre-commit hook (`vp check`) fails CI           | Local formatter not run                                                           | `vp check --fix` locally; commit; rerun                        |
+Local versioning uses `vp run changeset` and `vp run version`. `vp run release` builds and publishes; `vp run release:publish` only publishes an existing build. A local build or tarball test does not publish, deploy, push a commit or validate an external environment.
 
-## See also
+## Application projects
 
-- The actual release workflow: `.github/workflows/release.yml`
-- The actual quality workflow: `.github/workflows/quality.yml`
-- [Changesets docs](https://github.com/changesets/changesets) — for understanding `vp run version` and `vp run release`
+Use the generated application's own `vp run build` and deployment configuration. Keep environment secrets in the chosen host's bindings. Install only the renderer and host peers that the application imports. The complete local runtime and installed-consumer evidence is described in the repository's `docs/application-boundaries-acceptance.md`.

package/docs/engineering/project-structure.md

@@ -1,296 +1,53 @@
-# Engineering: project structure
+# Application structure
 
-Recommended layout for apps past the scaffolded starter. The shape that works for ~20 routes and ~10 engineers without major reorganization.
+The React, Vue and Svelte templates have two consistent tiers. Each generated project is standalone and uses only the public package entries.
 
-## Layout
+## Choose a tier
 
-```
-my-app/
-├── src/
-│   ├── bootstrap.ts             # routes + DI setup (shared SSR + CSR)
-│   ├── main.ts                  # browser entry
-│   ├── ssr.ts                   # SSR entry
-│   ├── App.vue                  # root component
-│   │
-│   ├── routes/                  # route definitions, grouped by domain
-│   │   ├── home.ts
-│   │   ├── product.ts
-│   │   ├── checkout.ts
-│   │   └── admin.ts
-│   │
-│   ├── controllers/             # controllers, one file per intent
-│   │   ├── home.ts
-│   │   ├── product.ts
-│   │   └── checkout.ts
-│   │
-│   ├── views/                   # view components, mirror controllers
-│   │   ├── Home.vue
-│   │   ├── Product.vue
-│   │   └── Checkout.vue
-│   │
-│   ├── lib/
-│   │   ├── api/                 # HttpClient subclasses
-│   │   │   ├── user.ts
-│   │   │   └── product.ts
-│   │   ├── guards/              # reusable middleware
-│   │   │   ├── auth.ts
-│   │   │   ├── locale.ts
-│   │   │   └── analytics.ts
-│   │   ├── di/
-│   │   │   ├── keys.ts          # APP_KEYS const map
-│   │   │   └── register.ts      # central registration
-│   │   ├── i18n/
-│   │   │   └── translator.ts    # Translator factory
-│   │   └── pages/
-│   │       └── types.ts         # Page union type
-│   │
-│   ├── locales/
-│   │   ├── en-US.json
-│   │   ├── zh-Hans.json
-│   │   └── ja-JP.json
-│   │
-│   └── env.ts                   # env var parsing + validation
-│
-├── public/                      # static assets, served at /
-├── index.html
-├── vite.config.ts
-├── package.json
-└── tsconfig.json
-```
-
-## Why this shape
-
-### `routes/` separate from `controllers/`
-
-A route is **where** an intent is exposed (URL pattern, guards, render mode). A controller is **what** an intent does. Splitting them lets you:
-
-- Reuse a controller across multiple URLs without route definitions cluttering its file
-- Find "what URLs does my app serve" by reading one folder
-- Find "what does intent X compute" by reading one folder
-
-### `controllers/` mirrors `views/`
-
-One file per intent on both sides. The intent id, controller file, and view file share the same name. Finding the rendering code for `/products/:id` becomes mechanical.
-
-### `lib/` for everything cross-cutting
-
-Anything that isn't a route, controller, or view. The framework's `bootstrap()` reaches into `lib/di/register.ts` for the heavy registration; controllers reach into `lib/api/*` for clients; guards live in `lib/guards/`.
-
-### `env.ts` at the top of `src/`
-
-Parse and validate environment variables once, in one file. Use [zod](https://zod.dev/) or hand-rolled checks. Re-export typed constants everywhere else.
-
-```ts
-// src/env.ts
-function requireEnv(name: string): string {
-    const v = process.env[name];
-    if (!v) throw new Error(`Missing env: ${name}`);
-    return v;
-}
-
-export const env = {
-    UPSTREAM_URL: requireEnv("UPSTREAM_URL"),
-    SESSION_SECRET: requireEnv("SESSION_SECRET"),
-    NODE_ENV: process.env.NODE_ENV ?? "development",
-} as const;
-```
-
-This makes "what env vars does this app need" trivially discoverable, and the build fails fast on missing values instead of crashing at request time.
-
-## `bootstrap.ts` shape
-
-Keep `bootstrap.ts` thin — it should orchestrate, not contain logic:
-
-```ts
-// src/bootstrap.ts
-import { type Framework } from "@finesoft/front";
-import { registerDependencies } from "./lib/di/register";
-import { homeRoutes } from "./routes/home";
-import { productRoutes } from "./routes/product";
-import { checkoutRoutes } from "./routes/checkout";
-import { adminRoutes } from "./routes/admin";
-
-export function bootstrap(framework: Framework): void {
-    registerDependencies(framework.container);
-
-    homeRoutes(framework);
-    productRoutes(framework);
-    checkoutRoutes(framework);
-    adminRoutes(framework);
-}
-```
-
-Each `*Routes` function calls `defineRoutes(framework, [...])` with its own routes. Adding a new route group is one import + one call.
-
-## Per-domain route file
-
-```ts
-// src/routes/product.ts
-import { defineRoutes, type Framework } from "@finesoft/front";
-import { ProductController } from "../controllers/product";
-import { ProductListController } from "../controllers/product-list";
-import { authGuard } from "../lib/guards/auth";
-
-export function productRoutes(framework: Framework): void {
-    defineRoutes(framework, [
-        { path: "/products", intentId: "product-list", controller: new ProductListController() },
-        { path: "/products/:id", intentId: "product", controller: new ProductController() },
-        {
-            path: "/products/:id/edit",
-            intentId: "product-edit",
-            controller: new ProductEditController(),
-            beforeLoad: [authGuard],
-            renderMode: "csr",
-        },
-    ]);
-}
-```
-
-## Central DI registration
-
-```ts
-// src/lib/di/register.ts
-import { type Container, DEP_KEYS } from "@finesoft/front";
-import { APP_KEYS } from "./keys";
-import { UserApi } from "../api/user";
-import { ProductApi } from "../api/product";
-import { ConsoleLogger } from "@finesoft/front";
-import { env } from "../../env";
-
-export function registerDependencies(container: Container): void {
-    container.register(DEP_KEYS.LOGGER, () => new ConsoleLogger("app"));
-
-    container.register(
-        APP_KEYS.USER_API,
-        () =>
-            new UserApi({
-                baseUrl: env.UPSTREAM_URL,
-            }),
-    );
-    container.register(
-        APP_KEYS.PRODUCT_API,
-        () =>
-            new ProductApi({
-                baseUrl: env.UPSTREAM_URL,
-            }),
-    );
-}
-```
-
-Centralizing keeps the wiring inspectable. Adding a service is a single edit, not a search across the project.
-
-## Typed DI keys
-
-```ts
-// src/lib/di/keys.ts
-export const APP_KEYS = {
-    USER_API: "userApi",
-    PRODUCT_API: "productApi",
-    SESSION: "session",
-    FEATURE_BUCKETING: "featureBucketing",
-} as const;
-
-export type AppKey = (typeof APP_KEYS)[keyof typeof APP_KEYS];
-```
-
-Then in any controller:
-
-```ts
-import { APP_KEYS } from "../lib/di/keys";
+| Tier    | Pages and routes                                                          | Demonstrated behavior                                                                                        |
+| ------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Full    | Home `/`, product `/products/:id`, search `/search?q=...`, About `/about` | SSR, CSR About, URL actions, typed parameters, DI, mapper/API client examples, authentication and SEO guards |
+| Minimal | Feed `/`, detail `/item/:id`, Notes `/notes`                              | Tabs and stacks, entry drafts, global profile, session restoration, locale JSON and SSR hydration            |
 
-async execute(params, container) {
-    const api = container.resolve<UserApi>(APP_KEYS.USER_API);
-    // ...
-}
-```
-
-A typo in `APP_KEYS.USER_PAI` is a compile error. A typo in `"userPai"` is a runtime error.
-
-## Page type union
-
-```ts
-// src/lib/pages/types.ts
-import type { HomePage } from "../../controllers/home";
-import type { ProductPage } from "../../controllers/product";
-import type { CheckoutPage } from "../../controllers/checkout";
-import type { ErrorPage } from "./error";
-
-export type Page = HomePage | ProductPage | CheckoutPage | ErrorPage;
-```
-
-Use a discriminated union with a `kind` field. The view layer's root component switches on `page.kind`:
+Within a tier the three frameworks have the same routes, controller results, content and interactions. Both tiers use one native App with its layout around Outlet. The names describe the example applications, not a ranking of framework capabilities.
 
-```vue
-<script setup lang="ts">
-import type { Page } from "@/lib/pages/types";
-const props = defineProps<{ page: Page }>();
-</script>
+## Files
 
-<template>
-    <Home v-if="page.kind === 'home'" :page="page" />
-    <Product v-else-if="page.kind === 'product'" :page="page" />
-    <Checkout v-else-if="page.kind === 'checkout'" :page="page" />
-    <Error v-else-if="page.kind === 'error'" :page="page" />
-</template>
+```text
+src/config.ts          # app identity / persistence namespace
+src/app-definition.ts  # page definitions, routes, guards and optional navigation
+src/views.ts           # native view registry shared by browser and SSR
+src/main.ts            # standard browser startup and HMR disposal
+src/ssr.ts             # selected standard SSR renderer
+src/App.<native>       # full layout or minimal navigation/profile chrome
+src/pages/             # native page components (.tsx / .vue / .svelte)
+src/components/        # reusable full-template presentation components
+src/lib/controllers/   # BaseController page loaders and explicit public data
+src/lib/models/        # typed page/data contracts
+src/styles.css         # identical styling within each tier
+src/locales/           # minimal: en-US and zh-Hans JSON messages
 ```
 
-The discriminant narrows the type inside each branch — view components get a fully typed `page` prop without casts.
+Full additionally keeps its product data, mapper, HTTP client and guards under `src/lib/`,. Minimal reads `app.getSnapshot()` through the selected native `useSnapshot` binding. Profile state and component roots belong to the native app; the Web session owns guarded navigation and persistence.
 
-## Splitting the SSR and browser entries
+## Controllers and page declarations
 
-Keep `ssr.ts` and `main.ts` thin. They differ only in:
+All six templates use `BaseController`: classes in `lib/controllers/` implement business loading, while `app-definition.ts` registers factories with `definePage({ id, create: () => new HomeController() })` and reuses the returned `route()`, `leaf()` and `bindView()` references. `views.ts` binds native components, which receive the result through `page`.
 
-- `ssr.ts` calls `createSSRRender` and exports `render` + `serializeServerData`
-- `main.ts` calls `startBrowserApp` and mounts the view layer
+Import controllers, Web page types and `markPublic` from `@finesoft/front`. Controllers are created for actual execution; entry drafts and global profile state belong to page instances and the application store respectively. The `getErrorPage` factory creates error pages. See [routes, controllers and typed pages](../02-routing-and-controllers.md) for parameters, DI, `fallback` and function handlers.
 
-Everything else — routes, controllers, DI, i18n — is shared via `bootstrap.ts`.
+## State and locale
 
-```ts
-// src/ssr.ts
-import { createSSRRender, serializeServerData } from "@finesoft/front";
-import { renderToString } from "vue/server-renderer";
-import { createSSRApp } from "vue";
-import App from "./App.vue";
-import { bootstrap } from "./bootstrap";
-
-export const render = createSSRRender({
-    bootstrap,
-    getErrorPage: () => ({ kind: "error", title: "Server error" }),
-    async renderApp(page) {
-        const html = await renderToString(createSSRApp(App, { page }));
-        return { html, head: `<title>${page.title}</title>`, css: "" };
-    },
-});
-
-export { serializeServerData };
-```
-
-```ts
-// src/main.ts
-import { startBrowserApp } from "@finesoft/front/browser";
-import { createSSRApp } from "vue";
-import App from "./App.vue";
-import { bootstrap } from "./bootstrap";
-
-startBrowserApp({
-    bootstrap,
-    mount(target, { framework }) {
-        createSSRApp(App, { framework }).mount(target);
-    },
-});
-```
+In minimal, the detail input and Notes textarea live inside `data-restore-root`. Switching tabs retains both drafts; reloading restores them. Popping a detail entry destroys its draft. The profile is global to one mounted application and survives reload. `mountApplication(target, persistenceKey, "memory", "/notes")` allows an embedded application with a distinct persistence key.
 
-## When to break this layout
+All three minimal templates default to `zh-Hans`. Set `configuration.locale` in `src/app-definition.ts` to `en-US` or `zh-Hans` and restart/rebuild. The locale demonstration covers JSON loading and translation after hydration; the navigation labels and sample item data remain English.
 
-The shape above works through ~50 routes. Past that, consider:
+Full's unauthenticated `/admin` route redirects to `/login?from=...`; the template deliberately leaves the application's real login page and authentication service to its author. A demo `auth_token` cookie lets the guard continue.
 
-- **Per-feature folders** (`src/features/checkout/{routes,controllers,views,api}.ts`) for very large apps. Each feature is independently understandable.
-- **Lazy-loaded route bundles** with `import()` inside the route definition. The Vite plugin splits them automatically.
-- **Workspace packages** if multiple apps share the same controllers / API clients. Move shared code to `packages/shared` and import from there.
+## Maintaining parity
 
-Don't pre-emptively reorganize. The flat `routes/` + `controllers/` shape is fine well into the hundreds of files.
+Framework-neutral files are identical checked-in source in each same-tier project. Native imports, UI syntax, framework dependencies and app identities are the allowed differences. The projects need no sibling-template imports or private runtime aliases. The scaffolder packages these same source files and includes a local README.
 
-## See also
+Run `vp test packages/create-app/test` to check file/adapter parity, then build the six templates and run `vp exec node scripts/verify-template-renderers.mjs` for shared browser behavior. `vp exec node scripts/verify-created-consumers.mjs /absolute/path/to/front.tgz` prepares, installs and builds every generated project outside the workspace against the selected local package.
 
-- [Engineering: testing](./testing.md) — how to test against this structure
-- [DI container](../07-di-container.md) — registration patterns
+Optional independent data operations and Node/Worker hosts can be added in separate `src/data-app.ts`, `src/node.ts` and `src/worker.ts` modules. They share application contracts through the public entries.