@synopackageland/templates 0.40.2 → 0.40.4

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.40.4
+
+- Ignore private environment variants, key and certificate files, and npm credentials in every scaffold while keeping `.env.example` trackable
+- Include placeholder-only environment examples for the optional AI tests
+- Document secret storage under `synology/` for upstream forks without changing upstream ignore files
+- Verify Git ignore behavior for every template and UI variant, including upstream forks, using the packed templates and actual CLI
+
+## 0.40.3
+
+- Use CLI architecture names in local package tests and SDK constants in background-limit assertions
+- Exercise earlier request deadlines in journal-lock tests without waiting for the SDK's full operation allowance
+- Install scaffold test and build tools with `--include=dev`, including when `NODE_ENV=production`
+- Explain the upstream-web-only `ui: false` layout, retained entry-gate files and removable browser examples
+- Smoke-test freshly generated projects for every template and native UI variant with the current CLI
+
 ## 0.40.2
 
 - Include independent examples and npm scripts for local unit and registry contracts, local package checks, real-NAS ctl, deterministic UI outcomes and optional AI actions

package/README.md

@@ -216,8 +216,18 @@ scripts/assemble.sh --language rust /tmp/app-rs plain jobs  # python, node or ru
 scripts/gate.sh                                           # layout, every combination, binary, npm pack
 scripts/gate.sh --fast                                    # only the combinations the changes reach
 scripts/assemble.sh --list vue jobs                       # the templates a combination uses
+SYNOPKGLAND_CLI="$(command -v synopkgland)" node --test scripts/test/scaffold.test.mjs
 ```
 
+The gate installs the CLI range declared by the shared scaffold into its temporary
+directory, or uses the executable in `SYNOPKGLAND_CLI`. Its existing `node:test`
+harness runs real CLI init for every template and both native UI variants,
+then each generated project's default `npm test`. Native projects assert the
+starter operation; binary and Compose report the expected skip because they
+have no starter registry. One plain native project also runs its generated
+`test:local` check/build/inspect tier. Backend tests and Vue builds stay in the
+existing combination checks; Rust builds and frontend checks run on the Docker host.
+
 Without `SYNOPKGLAND_SDK_DIR` the combinations use the released SDK that
 `backend/go.mod` and `frontend/package.json` pin. With it, `assemble.sh` adds
 `replace github.com/synopackageland/syno-pkg-land-sdk => $SYNOPKGLAND_SDK_DIR`
@@ -344,10 +354,39 @@ configuration and DSM service definition, and upgrades retain the selection.
 Changing ports uses reinstall. Declare `{port: gateway_https}` runtime bindings
 when an upstream application needs its public port in its own configuration.
 
+## Secret files
+
+Every scaffold ignores `.env`, `.env.*`, `*.pem`, `*.key`, `*.p12` and `.npmrc`
+at any depth within its project. `.env.example` remains trackable and contains
+only placeholders for the optional AI tests; those commands load `.env` from
+their working directory. Copy the example only when configuring those tests.
+Keep real credentials out of examples and commits.
+
+Templates ship ignore files as `gitignore` because npm excludes `.gitignore`;
+`synopkgland init` restores the `.gitignore` name in the generated project.
+The scaffold tests use the actual packed templates to verify that behavior.
+
+### Upstream fork secret storage
+
+For `init --upstream-fork`, all wrapper-owned files belong in `synology/`.
+Store secrets in **`synology/.env`, never the fork root**, and run the optional
+tests from `synology/`. Copy `synology/.env.example` only when configuring the
+optional AI tests. Keep keys, certificates and private npm configuration under
+`synology/` as well.
+
+The upstream root `.gitignore` is not ours to edit and may not ignore a root
+`.env`. The generated `synology/.gitignore` protects secrets inside `synology/`;
+it cannot protect files in the parent directory. Preserve upstream ignore files
+and history. Use the CLI's `synopkgland skill show upstream-fork` for the rest of
+the fork workflow.
+
 ## App-open smoke
 
 Every generated project includes `tests/e2e/smoke.e2e.ts`, `e2e.config.ts` and
-a root `package.json`. Run `npm install` at the project root, install Chromium once with
+a root `package.json`. Run `npm install --include=dev` at the project root
+(or `npm ci --include=dev` after committing its lockfile).
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+Install Chromium once with
 `npx @e2e-dev/web install chromium`, then run `npm run e2e:smoke`. Set `DSM_E2E_SSH` and private mode-600 account files in
 `DSM_E2E_ACCOUNT_ADMIN` and `DSM_E2E_ACCOUNT_NORMAL`; grant the normal account
 Application Privileges first. Missing normal credentials/profile produces a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/templates",
-  "version": "0.40.2",
+  "version": "0.40.4",
   "description": "Project templates for synopkgland init: native-go, native-python, native-node and native-rust (plain or Vue, with jobs, delegate and root-ops overlays), binary and compose.",
   "license": "MIT",
   "repository": {

package/templates/_shared/AGENTS.md

@@ -22,7 +22,7 @@ sections at the end name each language's files, types and test commands.
 
 From the project root, run `synopkgland check --json`,
 `synopkgland build --json`, then `synopkgland inspect <spk> --json` on the emitted SPK.
-For Vue, first run `npm ci` and `npm run build` in frontend. Run its tests only if the user chose tests.
+For Vue, first run `npm ci --include=dev` and `npm run build` in frontend. Run its tests only if the user chose tests.
 Do not connect to or change a NAS without explicit task authorization.
 
 ## Optional testing
@@ -33,6 +33,11 @@ on tests. Scaffolding is included by default; writing and running tests are opti
 Read `synopkgland skill show testing` when setting up or extending tests.
 
 The default `npm test` runs only fast local unit/ctl registry contracts.
+At the project root, run `npm install --include=dev` first; after committing its
+lockfile, use `npm ci --include=dev`.
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI and frontend builds need dev tools.
+Before `test:local`, prepare the backend/frontend as described below and run
+`synopkgland ctl generate` for a native App.
 `npm run test:local` opts into check/build/inspect. Only on explicit user request,
 run `npm run test:nas:ctl`, `npm run e2e:smoke`, `npm run e2e:ui` or `npm run e2e:ai`.
 The full suite is slow. Never call these from build, install, DSM hooks or release.
@@ -49,6 +54,20 @@ the cheapest adequate model and low effort; never default to an expensive model.
 Use E2E_LLM_BASE_URL, E2E_LLM_MODEL, E2E_LLM_API_KEY_FILE (mode 600) or
 E2E_LLM_API_KEY, and optional E2E_LLM_REASONING_EFFORT (default low).
 
+## Upstream web UI only
+
+For an `--upstream-fork` wrapper whose only UI is the upstream web panel, set
+`ui: false` in `synology/dsm-package.yaml` and configure `identity_gateway`
+for that panel. `--ui plain` selects `ui/app.js`; it does not mean `ui: false`.
+The current scaffold still creates UI and browser-test examples: remove
+`synology/ui/` (or `synology/frontend/` for Vue), `synology/tests/e2e/`,
+`synology/e2e.config.ts` and `synology/e2e.ai.config.ts`, and remove the
+`e2e:*` scripts from `synology/package.json`.
+Keep `synology/backend/`, `synology/i18n/messages/`, `synology/operations.json` and
+the local/ctl tests: the entry gate still needs the backend and message catalogs.
+Read `synopkgland skill show upstream-fork` and
+`synopkgland skill show orchestrator` for the wrapper workflow.
+
 ## Lifecycle scripts (`dsm-scripts/`)
 
 `dsm-scripts/` holds DSM's own lifecycle scripts (preinst, postinst, preupgrade,
@@ -371,7 +390,7 @@ their capabilities with `synopkgland init --with`.
   `new AppError(code, message)`, `AppError.badRequest(message)`. Call services
   through `service(ctx, op, params)` (`service.ts`), which passes the runtime's
   refusals on; a bare `ctx.runtime` refusal would reach the browser as `internal`.
-- Test with `(cd backend && npm ci && npm test && npm run typecheck)`; `test/support.ts`'s
+- Test with `(cd backend && npm ci --include=dev && npm test && npm run typecheck)`; `test/support.ts`'s
   `call` plays the runtime.
 
 ## Rust backend

package/templates/_shared/tests/local/package.test.mjs

@@ -6,7 +6,7 @@ import { cli } from '../support/cli.mjs';
 // Explicit local build tier; no deployment or NAS connection.
 test('the App checks, builds and passes package inspection', {timeout: 300_000}, () => {
   cli('check');
-  const built = cli('build', '--arch', process.env.APP_TEST_ARCH || 'amd64');
+  const built = cli('build', '--arch', process.env.APP_TEST_ARCH || 'x86_64');
   assert.ok(built.outputs.length > 0);
   for (const spk of built.outputs) {
     assert.equal(existsSync(spk), true);

package/templates/binary/.env.example

@@ -0,0 +1,5 @@
+# Optional AI tests only: replace these placeholders in your private .env.
+# For an upstream fork, use synology/.env, never the fork root.
+E2E_LLM_BASE_URL=https://api.example.com/v1
+E2E_LLM_MODEL=replace-with-model
+E2E_LLM_API_KEY=replace-with-api-key

package/templates/binary/README.md

@@ -0,0 +1,18 @@
+# __DISPLAY_NAME__
+
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+The scaffold provides example prebuilt binaries; replace them with your own
+Linux binaries before packaging. See `AGENTS.md` for the package workflow.
+

package/templates/binary/gitignore

@@ -4,3 +4,9 @@ dist/
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc

package/templates/compose/.env.example

@@ -0,0 +1,5 @@
+# Optional AI tests only: replace these placeholders in your private .env.
+# For an upstream fork, use synology/.env, never the fork root.
+E2E_LLM_BASE_URL=https://api.example.com/v1
+E2E_LLM_MODEL=replace-with-model
+E2E_LLM_API_KEY=replace-with-api-key

package/templates/compose/README.md

@@ -0,0 +1,27 @@
+# __DISPLAY_NAME__
+
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Configure the upstream image and its real readiness endpoint before
+`test:local`; see `AGENTS.md` for the Compose packaging workflow.
+
+## Secrets in an upstream fork
+
+With `--upstream-fork`, store secrets in `synology/.env`, never in the fork root.
+Run the optional tests from `synology/`; its `.gitignore` protects `.env`,
+`.env.*`, `*.pem`, `*.key`, `*.p12` and `.npmrc`, while `.env.example` remains
+trackable with placeholders only. The upstream root `.gitignore` is not ours
+to edit and may not ignore a root `.env`.
+See the [fork guide](https://github.com/synopackageland/syno-pkg-land-templates#upstream-fork-secret-storage).
+

package/templates/compose/gitignore

@@ -1,5 +1,11 @@
 node_modules/
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc
 dist/
 *.spk

package/templates/native-go/.env.example

@@ -0,0 +1,5 @@
+# Optional AI tests only: replace these placeholders in your private .env.
+# For an upstream fork, use synology/.env, never the fork root.
+E2E_LLM_BASE_URL=https://api.example.com/v1
+E2E_LLM_MODEL=replace-with-model
+E2E_LLM_API_KEY=replace-with-api-key

package/templates/native-go/README.md

@@ -25,10 +25,36 @@ independent package-account worker and report phase/progress. Authenticate
 status/result polling by that ID; a slow NAS or failed status read leaves the
 last queued/running state intact. After a lost admission reply, reuse the same
 idempotency key and input instead of replaying a mutation with a new key.
-Jobs default to 30 minutes; approved executor limits remain separate. ctl keeps
+Jobs use the SDK's default operation allowance; approved executor limits remain separate. ctl keeps
 its 62-second transport default; use an explicit `--timeout` or an existing
 nonblocking job. See the SDK's [request deadline contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/main/docs/request-deadlines.md).
 
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
+## Secrets in an upstream fork
+
+With `--upstream-fork`, store secrets in `synology/.env`, never in the fork root.
+Run the optional tests from `synology/`; its `.gitignore` protects `.env`,
+`.env.*`, `*.pem`, `*.key`, `*.p12` and `.npmrc`, while `.env.example` remains
+trackable with placeholders only. The upstream root `.gitignore` is not ours
+to edit and may not ignore a root `.env`.
+See the [fork guide](https://github.com/synopackageland/syno-pkg-land-templates#upstream-fork-secret-storage).
+
 ## Quick start
 
 Needs Node.js with `synopkgland` installed, and Go 1.26.10.
@@ -443,3 +469,16 @@ Draft writes require a non-mutating preview and explicit human confirmation.
 Long operations use the existing job flow; tools own polling and pagination.
 
 Use a matching SDK/CLI/templates release containing the registry support.
+
+## Upstream web UI only
+
+`init --upstream-fork --ui plain` still creates a plain SDK UI; it does not
+select `ui: false`. For an upstream web panel with no SDK UI, set `ui: false`
+in `synology/dsm-package.yaml` and configure `identity_gateway` for the panel.
+Remove `synology/ui/` (or `synology/frontend/` for Vue),
+`synology/tests/e2e/`, `synology/e2e.config.ts` and
+`synology/e2e.ai.config.ts`, and remove the `e2e:*` npm scripts.
+Keep `synology/backend/`, `synology/i18n/messages/`, `synology/operations.json` and
+the local/ctl tests: the entry gate still needs the backend and message catalogs.
+Read `synopkgland skill show upstream-fork` and
+`synopkgland skill show orchestrator` for the wrapper workflow.

package/templates/native-go/backend/internal/app/background_test.go

@@ -34,6 +34,10 @@ func newBgEnv(t *testing.T) *bgEnv {
 }
 
 func (e *bgEnv) call(auth api.Authenticator, method, params string) (string, map[string]any) {
+	return e.callContext(context.Background(), auth, method, params)
+}
+
+func (e *bgEnv) callContext(ctx context.Context, auth api.Authenticator, method, params string) (string, map[string]any) {
 	e.t.Helper()
 	// SDK policy provides owner routes immediately.
 	routes := newBackgroundRoutes(e.store, e.dataDir)
@@ -42,6 +46,7 @@ func (e *bgEnv) call(auth api.Authenticator, method, params string) (string, map
 		e.t.Fatal(err)
 	}
 	req := httptest.NewRequest(http.MethodPost, "/api.cgi", strings.NewReader(`{"method":"`+method+`","params":`+params+`}`))
+	req = req.WithContext(ctx)
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Sec-Fetch-Site", "same-origin")
 	rec := httptest.NewRecorder()
@@ -112,8 +117,18 @@ func TestBackgroundStatusReportsLimitsAndWorker(t *testing.T) {
 		t.Fatalf("%s %v", code, out)
 	}
 	limits := d["limits"].(map[string]any)
-	if limits["maxInputBytes"].(float64) != 512*1024 || limits["maxQueued"].(float64) != 16 || limits["maxTotalBytes"].(float64) != 16<<20 || limits["jobTimeoutSeconds"].(float64) != 30*60 {
-		t.Fatalf("limits: %v", limits)
+	for name, want := range map[string]float64{
+		"maxInputBytes":     background.MaxInputBytes,
+		"maxQueued":         background.MaxQueued,
+		"maxSchedules":      background.MaxSchedules,
+		"maxTotalBytes":     background.MaxTotalBytes,
+		"maxOwnerPending":   background.MaxOwnerPending,
+		"maxOwnerBytes":     background.MaxOwnerBytes,
+		"jobTimeoutSeconds": background.JobTimeout.Seconds(),
+	} {
+		if got := limits[name]; got != want {
+			t.Errorf("limits[%q] = %v, want %v", name, got, want)
+		}
 	}
 	info := background.WorkerInfo{PID: os.Getpid(), UID: os.Getuid(), Username: "pkg"}
 	if err := e.store.Heartbeat(context.Background(), info); err != nil {

package/templates/native-go/gitignore

@@ -3,3 +3,9 @@ dist/
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc

package/templates/native-go-jobs/backend/internal/app/background_routes_test.go

@@ -52,7 +52,7 @@ func TestBackgroundBusyErrorCode(t *testing.T) {
 	}
 }
 
-func TestBackgroundRequestSubmitBusyAndProductionConstruction(t *testing.T) {
+func TestBackgroundRequestSubmitDeadlineAndProductionConstruction(t *testing.T) {
 	e := newBgEnv(t)
 	dir := filepath.Join(t.TempDir(), "background")
 	e.store = background.NewRequestStore(dir)
@@ -68,12 +68,17 @@ func TestBackgroundRequestSubmitBusyAndProductionConstruction(t *testing.T) {
 		t.Fatal(err)
 	}
 	defer syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+	// Use an earlier caller deadline instead of waiting for the SDK's full
+	// operation allowance. The API reports that deadline, not jobs_busy.
+	budget := min(50*time.Millisecond, background.RequestLockTimeout/2)
+	ctx, cancel := context.WithTimeout(context.Background(), budget)
+	defer cancel()
 	start := time.Now()
-	code, out := e.call(alice, "bg.jobs.submit", e.submitParams("k1"))
-	if code != "jobs_busy" || time.Since(start) > background.RequestLockTimeout+time.Second {
-		t.Fatalf("busy submit: %s %+v", code, out)
+	code, out := e.callContext(ctx, alice, "bg.jobs.submit", e.submitParams("k1"))
+	if code != "request_timeout" || time.Since(start) > budget+time.Second {
+		t.Fatalf("submit deadline: %s %+v", code, out)
 	}
-	// The actual production assembly must use the same bounded wait policy.
+	// The production route assembly must also honor an earlier request deadline.
 	srv, err := api.NewServerWithPermissions(alice, []byte(`{"schema":1,"default":"administrators","methods":{}}`), BackgroundRoutes(filepath.Dir(dir))...)
 	if err != nil {
 		t.Fatal(err)
@@ -82,8 +87,8 @@ func TestBackgroundRequestSubmitBusyAndProductionConstruction(t *testing.T) {
 	r.Header.Set("Content-Type", "application/json")
 	r.Header.Set("Sec-Fetch-Site", "same-origin")
 	w := httptest.NewRecorder()
-	srv.ServeHTTP(w, r)
-	if !strings.Contains(w.Body.String(), `"jobs_busy"`) {
+	api.WithRequestDeadline(srv, api.Timeout(budget)).ServeHTTP(w, r)
+	if !strings.Contains(w.Body.String(), `"request_timeout"`) {
 		t.Fatal(w.Body.String())
 	}
 }

package/templates/native-go-vue/README.md

@@ -7,9 +7,37 @@ files, portal, jobs and delegate components come from `@synopackageland/sdk/vue`
 `github.com/synopackageland/syno-pkg-land-sdk` version in `backend/go.mod`. See
 <https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
 
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
+## Secrets in an upstream fork
+
+With `--upstream-fork`, store secrets in `synology/.env`, never in the fork root.
+Run the optional tests from `synology/`; its `.gitignore` protects `.env`,
+`.env.*`, `*.pem`, `*.key`, `*.p12` and `.npmrc`, while `.env.example` remains
+trackable with placeholders only. The upstream root `.gitignore` is not ours
+to edit and may not ignore a root `.env`.
+See the [fork guide](https://github.com/synopackageland/syno-pkg-land-templates#upstream-fork-secret-storage).
+
+## Frontend
+
 ```sh
 cd frontend
-npm ci
+npm ci --include=dev
 npm test
 npm run build
 ```

package/templates/native-go-vue/gitignore

@@ -4,3 +4,9 @@ node_modules/
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc

package/templates/native-node/.env.example

@@ -0,0 +1,5 @@
+# Optional AI tests only: replace these placeholders in your private .env.
+# For an upstream fork, use synology/.env, never the fork root.
+E2E_LLM_BASE_URL=https://api.example.com/v1
+E2E_LLM_MODEL=replace-with-model
+E2E_LLM_API_KEY=replace-with-api-key

package/templates/native-node/README.md

@@ -25,16 +25,33 @@ independent package-account worker and report phase/progress. Authenticate
 status/result polling by that ID; a slow NAS or failed status read leaves the
 last queued/running state intact. After a lost admission reply, reuse the same
 idempotency key and input instead of replaying a mutation with a new key.
-Jobs default to 30 minutes; approved executor limits remain separate. ctl keeps
+Jobs use the SDK's default operation allowance; approved executor limits remain separate. ctl keeps
 its 62-second transport default; use an explicit `--timeout` or an existing
 nonblocking job. See the SDK's [request deadline contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/main/docs/request-deadlines.md).
 
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ## Quick start
 
 Needs Node.js 20 or later with `synopkgland` installed. The SPK depends on DSM's **Node.js v20** package (INFO `install_dep_packages`).
 
 ```bash
-(cd backend && npm ci && npm test && npm run build)   # method tests, then app/*.js
+(cd backend && npm ci --include=dev && npm test && npm run build)   # method tests, then app/*.js
 synopkgland ctl generate
 synopkgland check
 synopkgland build           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk

package/templates/native-node/dsm-package.yaml

@@ -42,7 +42,7 @@ arches: [x86_64, aarch64]
 # and app/permissions.json, then runs `node main.js` in backend/app as the
 # package account, once per call, with Package Center's Node.js (node.package
 # becomes an install dependency). backend/src compiles to backend/app: run
-# `npm ci` and `npm run build` in backend before check and build. sdk is the
+# `npm ci --include=dev` and `npm run build` in backend before check and build. sdk is the
 # SDK release whose runtime and Node SDK (node_modules/@synopackageland/app)
 # the build ships; the build reads the methods from `main.js --describe`.
 backend:

package/templates/native-node/gitignore

@@ -6,3 +6,9 @@ backend/app/*.js
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc

package/templates/native-node-vue/README.md

@@ -7,9 +7,26 @@ delegate components come from `@synopackageland/sdk/vue` (types from
 `@synopackageland/sdk`); its version must equal the `backend.sdk` in dsm-package.yaml. See
 <https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
 
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ```sh
 cd frontend
-npm ci
+npm ci --include=dev
 npm test
 npm run build
 ```

package/templates/native-node-vue/gitignore

@@ -6,3 +6,9 @@ backend/app/*.js
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc

package/templates/native-python/.env.example

@@ -0,0 +1,5 @@
+# Optional AI tests only: replace these placeholders in your private .env.
+# For an upstream fork, use synology/.env, never the fork root.
+E2E_LLM_BASE_URL=https://api.example.com/v1
+E2E_LLM_MODEL=replace-with-model
+E2E_LLM_API_KEY=replace-with-api-key

package/templates/native-python/README.md

@@ -25,10 +25,27 @@ independent package-account worker and report phase/progress. Authenticate
 status/result polling by that ID; a slow NAS or failed status read leaves the
 last queued/running state intact. After a lost admission reply, reuse the same
 idempotency key and input instead of replaying a mutation with a new key.
-Jobs default to 30 minutes; approved executor limits remain separate. ctl keeps
+Jobs use the SDK's default operation allowance; approved executor limits remain separate. ctl keeps
 its 62-second transport default; use an explicit `--timeout` or an existing
 nonblocking job. See the SDK's [request deadline contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/main/docs/request-deadlines.md).
 
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ## Quick start
 
 Needs Node.js with `synopkgland` installed, and Python 3.8 or later.

package/templates/native-python/gitignore

@@ -4,3 +4,9 @@ __pycache__/
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc

package/templates/native-python-vue/README.md

@@ -7,9 +7,26 @@ delegate components come from `@synopackageland/sdk/vue` (types from
 `@synopackageland/sdk`); its version must equal the `backend.sdk` in dsm-package.yaml. See
 <https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
 
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ```sh
 cd frontend
-npm ci
+npm ci --include=dev
 npm test
 npm run build
 ```

package/templates/native-python-vue/gitignore

@@ -5,3 +5,9 @@ node_modules/
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc

package/templates/native-rust/.env.example

@@ -0,0 +1,5 @@
+# Optional AI tests only: replace these placeholders in your private .env.
+# For an upstream fork, use synology/.env, never the fork root.
+E2E_LLM_BASE_URL=https://api.example.com/v1
+E2E_LLM_MODEL=replace-with-model
+E2E_LLM_API_KEY=replace-with-api-key

package/templates/native-rust/README.md

@@ -25,10 +25,27 @@ independent package-account worker and report phase/progress. Authenticate
 status/result polling by that ID; a slow NAS or failed status read leaves the
 last queued/running state intact. After a lost admission reply, reuse the same
 idempotency key and input instead of replaying a mutation with a new key.
-Jobs default to 30 minutes; approved executor limits remain separate. ctl keeps
+Jobs use the SDK's default operation allowance; approved executor limits remain separate. ctl keeps
 its 62-second transport default; use an explicit `--timeout` or an existing
 nonblocking job. See the SDK's [request deadline contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/main/docs/request-deadlines.md).
 
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ## Quick start
 
 Needs Node.js with `synopkgland` installed, Rust through rustup, Zig and `cargo-zigbuild`: `backend/rust-toolchain.toml` pins 1.97.1 with the three DSM targets, so the first `cargo` run installs them.

package/templates/native-rust/gitignore

@@ -4,3 +4,9 @@ backend/target/
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc

package/templates/native-rust-vue/README.md

@@ -7,9 +7,26 @@ delegate components come from `@synopackageland/sdk/vue` (types from
 `@synopackageland/sdk`); its version must equal the `syno-pkg-land-app` tag in backend/Cargo.toml. See
 <https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
 
+## Local tests
+
+Copy `.env.example` to the ignored `.env` only for optional AI tests; keep real credentials out of examples and commits.
+
+From the project root, install the test tools before running the optional tests:
+
+```sh
+npm install --include=dev
+npm test
+```
+
+`NODE_ENV=production` skips devDependencies; `test:local` needs the CLI.
+After committing the generated root lockfile, use `npm ci --include=dev`.
+Before `npm run test:local`, prepare the backend and, for Vue, build the
+frontend using the steps below and the backend section in `AGENTS.md`, then
+run `synopkgland ctl generate`.
+
 ```sh
 cd frontend
-npm ci
+npm ci --include=dev
 npm test
 npm run build
 ```

package/templates/native-rust-vue/gitignore

@@ -5,3 +5,9 @@ backend/target/
 # Private NAS smoke sessions and credentials
 .e2e/
 .env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+.npmrc