@flisk-sh/flisk 1.4.5 → 1.4.7

package/cli/templates/agent-skills/flisk-troubleshoot/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: flisk-troubleshoot
+description: Diagnose and fix Flisk local-dev problems with verified commands. Covers `flisk doctor`, `flisk up` or `flisk down` failing or hanging, "Docker daemon is not responding", red Tilt resources (pull access denied for golden images, missing shared-platform-engineering files, TS2688 bun types, run-only "No such image"), Postgres crash loops, services never reaching healthy, a machine overloaded by many services, Docker image size vs memory questions, and benchmarking how many services fit on a machine. Use this whenever someone works in flisk or a Flisk project (flisk-erp-system, flisk-saas-starter, flisk-restaurant-example, auth-user) and anything about flisk, Tilt, or Docker is broken, slow, or being measured, even if they never say "troubleshoot".
+license: MIT
+compatibility: Requires the flisk CLI, Docker and Tilt on the local machine. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Flisk troubleshooting
+
+This skill comes from a long session on 2026-09-25. It brought `flisk-erp-system` (107 services) up, measured it, and wasted a lot of the user's time along the way. Everything below marked **measured** or **verified** was run on the user's 16 GB MacBook Air (Docker VM: 8 CPUs, 7,934 MiB). Anything else is labelled as unknown.
+
+## How to work (the expensive lessons)
+
+- **Say what you measured, what you estimated, and what you don't know, in that order.** Most of the frustration came from confident claims that a later measurement contradicted, such as "memory is ~16 MiB/container" (`docker stats`, which undercounts) and "112 s boot" (actually the launcher script). "I don't know yet, here is how I'd find out" is a good answer.
+- **Check machine load before blaming Docker, Tilt or the code.** An overloaded Mac makes every tool look broken.
+- **Before anything that runs longer than about 5 minutes or starts dozens of containers, say so and give an estimate.** A full ERP `flisk up` froze this machine once. Ask first.
+- **Give short status lines while waiting.** Silence during long builds reads as "nothing works".
+- **Don't polish a proxy metric.** Shrinking images didn't touch the real bottleneck. Ask what actually hurts (time, CPU, a freeze) and measure that.
+
+## First 60 seconds: triage
+
+```bash
+sysctl -n vm.loadavg; top -l 1 -n 0 | grep -E "CPU usage|PhysMem"
+time docker ps -q | wc -l
+pgrep -fl "tilt up"
+docker info --format 'CPUs={{.NCPU}} MemTotal={{.MemTotal}}'
+```
+
+- **`docker ps` taking more than about 5 s means overload, not breakage.** Measured: 6–13 s with 110 ERP containers plus Tilt running, load average 28–43, 99 MB free RAM. `flisk doctor` and `flisk down` both fail their own 10 s Docker check in that state.
+- **A `tilt up` process still running recreates any container you `docker stop`** within seconds. Stop Tilt first.
+- **Other Flisk projects share the `*-autogenerated-*` container naming** (for example kitchen, guest, operations and auth from the restaurant and auth projects). Filter by stack name before stopping anything.
+
+## Symptoms, causes and fixes (verified)
+
+### "Docker daemon is not responding (`docker ps` hung for 10s)"
+
+**Cause:** overload, as above. `flisk down` is blocked by the same check.
+
+**Fix:** stop Tilt, then stop the project's containers directly.
+
+```bash
+pkill -TERM -f "tilt up -f $PWD/.flisk/.flisk-out/Tiltfile"
+docker ps --format '{{.Names}}' | grep -E '^(finance|hr|sales|inventory|manufacturing|supply_chain|analytics)-autogenerated-' | xargs docker stop
+```
+
+### Postgres restarting with "Database is uninitialized and superuser password is not specified"
+
+**Cause:** the container was created while `DB_PASSWORD` was empty. Environment variables are fixed when a container is created, so fixing `.env` later doesn't help.
+
+**Check:**
+
+```bash
+docker inspect <project>_postgres --format '{{range .Config.Env}}{{println .}}{{end}}' | grep POSTGRES_PASSWORD
+```
+
+**Fix:** recreate the container (Tilt or compose `up` recreates it). The data volume survives.
+
+### Tilt build error `pull access denied ... docker.io/library/<project>-l4-backend:latest`
+
+**Cause:** the golden layers aren't built yet (the `golden-layers-build` resource is still running).
+
+**Fix:** wait for it to finish. Tilt does **not** retry resources that failed before it finished, so trigger every errored resource yourself.
+
+```bash
+tilt get uiresources -o json | python3 -c 'import json,sys; [print(i["metadata"]["name"]) for i in json.load(sys.stdin)["items"] if i.get("status",{}).get("updateStatus")=="error"]' | xargs -n1 tilt trigger
+```
+
+### `*-run-only` resources fail with `No such image: <stack>_<svc>:dev`
+
+**Cause:** they ran `docker compose up --no-build` before the image existed.
+
+**Fix:** once the image builds, `tilt trigger` them.
+
+### Missing generated files in the build context
+
+The build fails with `"/shared-platform-engineering/docker-templates/<x>.sh": not found` or `"/package.json": not found`.
+
+**Cause:** the project is missing its generated runtime assets.
+
+**Fix:**
+- `flisk project --yes` copies `shared-platform-engineering/docker-templates` (verified).
+- If the root `package.json` is still missing, add a Bun workspace manifest. This is what fixed ERP:
+
+  ```json
+  { "name": "<project>", "private": true, "type": "module", "workspaces": ["services/*/*"] }
+  ```
+
+- `flisk doctor` now reports both (`checkGeneratedProjectRuntimeAssets`).
+
+### `bun run build` fails with `TS2688: Cannot find type definition file for 'bun'`
+
+**Cause:** the generated tsconfig sets `"types": ["bun"]`, but the service's `package.json` has no `@types/bun`.
+
+**Fix:** add `"@types/bun": "^1.4.2"` to `devDependencies`. `flisk doctor` now reports this (`checkTypeScriptTypeDependencies`).
+
+### `flisk up <stack>` queues every stack
+
+**Observed, not root-caused:** `flisk up finance` left 129 resources pending across all stacks.
+
+**Protect the machine:** check the counts, then disable the other stacks.
+
+```bash
+tilt get uiresources -o json | python3 -c 'import json,sys,collections; print(collections.Counter(i.get("status",{}).get("updateStatus") for i in json.load(sys.stdin)["items"]))'
+tilt disable <other-stack-resource> <...>
+```
+
+### Engine edits have no effect
+
+**Cause:** projects run a vendored copy of the engine at `.flisk/.flisk-out/flisk-cli-ext/`. The installed `/usr/local/bin/flisk` vendors **its own bundled engine**, so it can silently overwrite your local one.
+
+**Fix:** re-vendor from your local checkout, then check the copy matches.
+
+```bash
+(cd <core>/cli && bun run build)
+FLISK_EXTENSION_SOURCE=<core> node <core>/cli/bin/flisk.js project --yes
+diff -rq <core>/engine/topologies/platform/docker .flisk/.flisk-out/flisk-cli-ext/engine/topologies/platform/docker
+```
+
+### Reading Tilt state
+
+- Use the CLI. The HTTP API (`localhost:10350/api/view`) returns 403 "missing session token".
+- `tilt get uiresources <name> -o json` shows a resource's state. **`buildHistory[0]` is the newest build**; reading `[-1]` shows a stale error and misleads you.
+- `tilt logs <resource>` gives the full build log.
+
+## ERP project layout
+
+| Thing | Value |
+|---|---|
+| Service manifests | `services/<stack>/<svc>/service.json` |
+| Image names | `<stack>_<svc>:dev` |
+| Compose project | `<stack>-autogenerated` |
+| Compose file | `services/<stack>/.autogenerated/docker-compose.app.autogenerated.yml` |
+| Postgres | `services/platform/database-management/docker-compose.yml` |
+| Traefik | `.flisk/.flisk-out/docker-compose.traefik.yml` |
+| Databases | `<project>_<stack>`, created with `createdb` |
+| Golden images | `<project>-l1`, `-l2`, `-l3-*`, `-l4-*` |
+
+## Measuring without fooling yourself
+
+### Image size is disk, not RAM
+
+- `docker images` counts shared layers once per image. Real disk use is `docker system df`. The 107 ERP images add up to 26 GB listed, but all 151 images on the machine together use 6 GB on disk.
+- See what fills an image, layer by layer:
+
+  ```bash
+  docker history <img> --format '{{.Size}}\t{{.CreatedBy}}'
+  ```
+
+- **Measured:** ERP backends are 176–276 MB each, but only 4.5–8.8 MB is service-specific. The rest is shared: Bun binary 93 MB, Alpine 9 MB, L1 packages 30 MB.
+- **Measured:** `auth_auth-api-backend:dev` is 826 MB on disk, yet uses 33 MiB of RAM when running. Of the 826 MB, two copies of `node_modules` take 199 MB each, and hugo takes 57 MB. The duplicate-copy fix is only on branch `autoresearch/sep25`. The hugo removal is on `main`. Both need a rebuild to take effect.
+
+### RAM: `docker stats` undercounts
+
+It leaves out Docker's per-container overhead in the VM (containerd shims and the init process). Use the change in the Docker VM's own memory instead:
+
+```bash
+docker run --rm alpine awk '/MemTotal/{t=$2}/MemAvailable/{a=$2}END{printf "%d MiB used\n",(t-a)/1024}' /proc/meminfo
+```
+
+- **Measured:** 100 idle ERP containers cost **2,076 MiB real (about 21 MiB each)**. `docker stats` reported 1,693 MiB for the same containers.
+- The VM measurement is noisy for small counts: the same 20-container setup read 442 MiB one time and 214 MiB the next. Use 100 containers, or repeat the run and report the range.
+
+### Time: start containers in parallel, as Tilt does
+
+A serial `docker run` loop measures the launcher, not the services. For parallel starts on macOS:
+
+```bash
+tr '\n' '\0' < cmds.txt | xargs -0 -n1 -P8 sh -c
+```
+
+- **Measured:** 100 ERP containers were all healthy in **31.7 s** starting 8 at a time, with 0 crashes. Starting the containers took 26.6 s of that.
+- The website claims "full boot in under 5 seconds". Measured, that only holds for about 5 services (4.5 s).
+
+### North-star math: 100 services in 16 GB
+
+(Docker VM MemTotal − 512 MiB for infrastructure) ÷ 100 = the per-service budget. On this Mac that's (7,934 − 512) ÷ 100 ≈ **74 MiB per service**. The measured 21 MiB fits, but only for idle containers answering `/health`. It hasn't been measured under real load.
+
+## Tools in this repo and how far to trust them
+
+| Tool | Status |
+|---|---|
+| `bun scripts/benchmark/container-scale.ts --synthetic` | **Verified** for 5 to 100 containers. Starts containers serially, so "all healthy" is about the launch time. |
+| `container-scale.ts` default (compose) mode | **Verified at tier 5** (2026-09-26): real generated compose files, real Postgres, real Traefik, 5/5 requests through Traefik returned 200, all healthy in 4.9s. Not yet run at 100 — that's the one that answers the north star. Its first run hung indefinitely (`Bun.spawn()` + a `Bun.sleepSync()` poll on `exitCode` never observes the exit, because `sleepSync` blocks the event loop Bun needs to record it) — fixed by launching with `spawnSync` instead. If you see a `container-scale.ts` run sit for minutes with 0% CPU while its containers are already healthy, this bug is back; check for `Bun.spawn` + `sleepSync` polling anywhere in the file. |
+| `scripts/autoresearch/layer-eval.sh` with the `layer-autoresearch` skill | **Verified** (4 runs). Run it from a worktree outside `~/Developer/Codex`. |
+| `scripts/measure-idle-footprint.sh <container>` | Written but **never run**. |
+| `tilt alpha tiltfile-result -f <Tiltfile>` | Runs Starlark without starting anything. `print` output is swallowed, so return data with `fail('RESULT' + encode_json(r))`. `load()` needs a literal path. |
+| `tests/tilt-engine/test_runtime_container_footprint.py` | Runs the real generators through Tilt. |
+
+## Environment traps
+
+- **`.flisk/.project-id` is not gitignored by default and is easy to accidentally stage.** It's created the first time anything checks a Premium license (`getOrCreateProjectId` in `cli/src/generator/extension-fetch.ts`) - a random UUID sent alongside `FLISK_LICENSE_KEY` to the license server for per-project tracking, not itself a secret credential, but it's local machine state that has no business in a shared repo. Found staged (`git status`, not yet committed - caught before it reached `origin/main`) in `flisk-erp-system` on 2026-09-26; `flisk-saas-starter` and `flisk-restaurant-example` had the same `.gitignore` gap with no file yet; `flisk-user-management` has **no `.gitignore` at all** (currently harmless - only 35 minimal tracked files, nothing sensitive - but unprotected the moment real development starts there). The CLI has no `.gitignore` template of its own to fix at the source (`flisk project` doesn't generate one; each starter repo ships its own) - check every project's `.gitignore` for `.flisk/.project-id` individually, and `git status`/`git log --all -- .flisk/.project-id` before assuming it's fine.
+
+- **Auto-commit tool.** Something outside Claude commits and pushes edits in `~/Developer/Codex/*` repos to `origin/main` within about a minute, with messages like "skill" or "specs". Do experiments in a worktree outside that folder:
+
+  ```bash
+  git worktree add ~/Developer/<name> <branch>
+  ```
+
+- **macOS shell:**
+  - There's no `timeout` command.
+  - `xargs -I` has a 255-character limit, so use the `-0` form above.
+  - System `python3` is 3.9: add `from __future__ import annotations` before using `X | None` types.
+  - Bash is version 3.2.
+- **Lint only the files you touched:**
+
+  ```bash
+  cd cli && ./node_modules/.bin/biome check <files>
+  ```
+
+  `bun run lint -- <files>` still lints the whole repo, which has many pre-existing errors.
+- **Failures that aren't yours:**
+  - pytest `test_docker_generator_bugs.py::test_expose_line_must_be_numeric_port` and `test_health_endpoints.py::test_overall_health_endpoint_structure` also fail on the unmodified code.
+  - vitest `saas-starter-integration` and `stack-features-e2e` time out when Docker is busy.
+
+## Resolved since the first version of this skill
+
+- **`flisk up <stack>` queuing every stack — fixed and verified (2026-09-26).** `flisk up finance` computed the right 16-service list but passed it to Tilt as bare positional args. The generated Tiltfile's focus filter (`Config.apply_focus` / `apply_focus_filter` in `profiles.star`) only reads the `--focus` flag - the positional-args catch-all it also defines (`cfg['args']`) is never read anywhere. So every stack-scoped `flisk up` silently fell back to Tilt's default "pre-alpha" phase and enabled every stack in it (verified: 247 enabled resources instead of 16-40). Fix: `buildTiltUpArgs` (`cli/src/utils/tilt.ts`) now passes `--focus=<stackName>`, reusing the Tiltfile's own dependency-aware domain expansion. **Argument order matters**: `--focus=...` must come after a `--` separator (`tilt up -f <path> -- --focus=finance <names>`) - `tilt up` rejects `--focus` as an unrecognized top-level flag otherwise (`tilt up --help` lists its real flags; custom Tiltfile config flags only reach `config.parse()` via `--`). Verified end-to-end: `tilt get uiresources` showed 402 Disabled / 24 Enabled for `flisk up finance` after the fix, and the 24 enabled were exactly finance's services plus required infra.
+
+- **What actually overloads a real full `flisk up` at 100+ services — tested and it held (2026-09-26).** Ran a real, uncapped `flisk up` (no stack filter, all 107 services, Tilt doing real builds and reconciliation - not the synthetic/capped benchmark) with a self-killing watchdog sampling load/free-memory/`docker ps` latency every 5s. Result: **110/110 containers reached healthy, zero crashes, zero danger-threshold strikes**, over an 18-minute run. Load peaked around 20 during the busiest build phase (~20-30 containers starting at once) and then *settled back down* to 11-16 as more services came online, finishing at 11.45 with all 110 up. `docker ps` occasionally spiked to 2-6s under load but never approached the 10s `flisk doctor` timeout for long. This is the same scenario that froze the machine on 2026-09-25 (load 28-43, 99 MB free, `docker ps` 6-13s) - it did not recur. Caveat: this is one run on one machine state, and it isn't certain which fix (or whether the host simply had less competing load this time) made the difference; the single-process-CMD image rebuild only covered a minority of services (finance + a couple of supply_chain ones) at the time of this run, so a full image rebuild wasn't a factor. Re-run with the watchdog pattern above (`sysctl -n vm.loadavg`, `vm_stat` free pages, timed `docker ps`) before trusting a "it's fine now" claim on a different machine or after further engine changes.
+
+## Still unknown
+
+- **Whether Bun `--smol` (`BUN_OPTIONS=--smol`) saves memory.** Bun does read the variable, but the A/B test was inconclusive.
+- **Why auth's production `node_modules` is 199 MB.**

package/cli/templates/agent-skills/flisk-up/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: flisk-up
+description: Start a Flisk stack with `flisk up`, preview it first with `flisk up <stack> --dry-run`, and confirm the healthy URLs. Use when the user asks to run, start, or bring up their local services, or after changing service.json files.
+license: MIT
+compatibility: Requires the flisk CLI. Services that declare a `command` need only their own runtime; other services need Docker and Tilt. Does not deploy.
+metadata:
+  author: flisk-sh
+  version: "1.0"
+---
+
+# Flisk up
+
+Start local services from `service.json` manifests. Flisk writes the Docker and Tilt configuration; do not write Dockerfiles, Tiltfiles, or routes by hand.
+
+## Workflow
+
+1. Run `flisk doctor` if the machine has not been checked yet. Stop on unresolved errors.
+2. Preview the stack: `flisk up <stack> --dry-run`. Show the user which services and URLs will start.
+3. Start it: `flisk up <stack>`. Omit `<stack>` to start every stack.
+4. Confirm health with `flisk status --json`. Report each service's URL only after it reports healthy.
+5. If `flisk up` refuses to start because generated files differ from `service.json`, regenerate from the source manifest. Use `--ignore-drift` only when the user asks to start anyway.
+
+## Services that run without Docker
+
+A service whose `service.json` declares `command` (for example `"command": "node server.js"`, with `appName`, `appType`, `port`, `dependsOn` and an optional `healthCheckPath`) runs as a local process. When every selected service has one, `flisk up` needs no Docker and no Tilt: it starts them in `dependsOn` order, prints `http://localhost:<port>` for each, prefixes their output, and restarts a service that exits. It stays in the foreground; `flisk down` stops it from another terminal.
+
+- Prefer `command` services for a simple app (an API, a website, a worker). Use Docker services when the app needs a database, one gateway URL, or the container it deploys.
+- Do not mix the two in one project: `flisk up` refuses with `MIXED_RUNTIME`.
+- `flisk up --json` reports `"runtime": "native"` and each service's URL. Read output with `flisk logs --service <name>`.
+- Guide: docs/run-without-docker.md.
+
+## Guardrails
+
+- Ask before starting a large stack or one likely to build many images; cold builds can take several minutes.
+- Use `flisk up -f` only when the user agrees to kill the existing Tilt process.
+- Do not edit `.autogenerated/` or other generated output. Change `service.json` instead.
+- Flisk runs locally. Do not use it to deploy to a cluster.

package/examples/{tdk-example → flisk-example}/README.md

@@ -10,10 +10,10 @@ flisk project --yes
 flisk up
 ```
 
-Open `http://app.tdk-example.localhost/orders-app/` and create an order, or use the routed API:
+Open `http://app.flisk-example.localhost/orders-app/` and create an order, or use the routed API:
 
 ```sh
-curl -fsS -X POST http://api.tdk-example.localhost/api/orders \
+curl -fsS -X POST http://api.flisk-example.localhost/api/orders \
   -H 'content-type: application/json' -d '{"item":"coffee"}'
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flisk-sh/flisk",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "description": "Flisk CLI — start services on your machine.",
   "homepage": "https://flisk.sh",
   "repository": {
@@ -29,7 +29,7 @@
     "!runtime/**/*.spec.*",
     "!runtime/**/test_*.py",
     "!runtime/**/*_test.py",
-    "examples/tdk-example",
+    "examples/flisk-example",
     "cli/bin",
     "cli/dist/**/*.js",
     "cli/dist-bundle/**/*.js",

package/runtime/discovery/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This folder contains the **service discovery system** for Flisk Landscape's Tilt infrastructure. It scans the repository for service manifests and creates Tilt resources.
+This folder contains the **service discovery system** for Flisk's Tilt infrastructure. It scans the repository for service manifests and creates Tilt resources.
 
 ## Architecture: Two-Layer Scanning with Validation
 

package/runtime/discovery/TILT_DISCOVERY.star

@@ -8,7 +8,7 @@
 # ⚠️  DEVELOPER NOTICE: This is a SYSTEM CONFIG file.
 #    For human-friendly docs, see: TILT_CONFIG.md
 #
-# This file defines service discovery settings for the Flisk Landscape platform.
+# This file defines service discovery settings for the Flisk platform.
 # Discovery automatically finds and registers services from the filesystem.
 #
 # 📖 TO EDIT DISCOVERY SETTINGS:

package/runtime/discovery/deterministic.star

@@ -1,6 +1,6 @@
 # Copyright (c) 2026 Flisk Landscape contributors
 # SPDX-License-Identifier: MIT
-# Deterministic Tilt Configuration for Flisk Landscape
+# Deterministic Tilt Configuration for Flisk
 # Inspired by Mira Murati's "Defeating Nondeterminism" philosophy
 # Goal: Same filesystem state + same environment = identical Tilt output
 

package/runtime/engine/AGENTS.md

@@ -1,6 +1,6 @@
 ---
 disable: false
-description: Topology specialist for Flisk Landscape - expert in Tilt/Starlark, manifest-driven architecture, service discovery, and the complete local development orchestration system. Masters the infrastructure topology that enables 120+ services.
+description: Topology specialist for Flisk - expert in Tilt/Starlark, manifest-driven architecture, service discovery, and the complete local development orchestration system. Masters the infrastructure topology that enables 120+ services.
 mode: subagent
 tools:
   - write
@@ -13,7 +13,7 @@ created: 2026-03-31
 updated: 2026-04-04
 ---
 
-You are a senior topology engineer specialized in the Flisk Landscape Tilt infrastructure. You are the definitive expert on the manifest-driven architecture, Starlark topology modules, service discovery, and the complete local development orchestration system.
+You are a senior topology engineer specialized in the Flisk Tilt infrastructure. You are the definitive expert on the manifest-driven architecture, Starlark topology modules, service discovery, and the complete local development orchestration system.
 
 ## Core Identity: The Infrastructure Cartographer
 
@@ -539,7 +539,7 @@ load('./my_custom_extension.star', 'my_function')
 # Load from parent directory
 load('../common/utils.star', 'helper')
 
-# Load from topologies (Flisk Landscape pattern)
+# Load from topologies (Flisk pattern)
 load('../../../platform/docker/index.star', 'Docker')
 ```
 

package/runtime/engine/README.md

@@ -4,7 +4,7 @@
 
 **Tilt Platform Framework Code**
 
-This directory contains the Flisk Landscape Tilt infrastructure framework - the code that powers our local development orchestration.
+This directory contains the Flisk Tilt infrastructure framework - the code that powers our local development orchestration.
 
 ## What's Here
 

package/runtime/engine/REFACTORING_MANIFEST_SYSTEM.md

@@ -2,7 +2,7 @@
 
 ## Executive Summary
 
-This document outlines a comprehensive refactoring of the manifest parsing and validation system in the Flisk Landscape Tilt infrastructure. The goal is to move from scattered inline logic to a clean, modular, well-tested architecture.
+This document outlines a comprehensive refactoring of the manifest parsing and validation system in the Flisk Tilt infrastructure. The goal is to move from scattered inline logic to a clean, modular, well-tested architecture.
 
 **Current State:**
 - Manifest parsing scattered across `discovery.star`, `registry.star`, and multiple generator files

package/runtime/engine/assets/docker/wake-gateway/decide.ts

@@ -38,7 +38,7 @@ export interface WakeAction {
    * only queues the resource: with Tilt's build slots busy (e.g. 100+
    * resources rebuilding after a re-vendor), a triggered resource waited
    * behind them and the request timed out (observed live against
-   * tdk-erp-system, see tasks.md 7.2). server.ts falls back to `tilt trigger`
+   * flisk-erp-system, see tasks.md 7.2). server.ts falls back to `tilt trigger`
    * when no image exists yet to start from.
    */
   useComposeStart: boolean;

package/runtime/engine/assets/docker/wake-gateway/server.ts

@@ -19,12 +19,12 @@
  *                          the resource name; Compose derives it as
  *                          <project>-<service>-<replica>, confirmed empirically
  *                          against a live Flisk container, e.g.
- *                          "tdk-erp-system-analytics-autogenerated-data-governance-api-1"
+ *                          "flisk-erp-system-analytics-autogenerated-data-governance-api-1"
  *                          for the "data-governance-api" resource).
  *   X-Wake-Deps            Comma-separated "resourceName=containerName" pairs
  *                          for required dependencies (task 1.5: Tilt never
  *                          cascades a trigger to these on its own).
- *   X-Wake-Compose-Project The resource's Compose project (e.g. "tdk-erp-system-analytics-autogenerated").
+ *   X-Wake-Compose-Project The resource's Compose project (e.g. "flisk-erp-system-analytics-autogenerated").
  *   X-Wake-Compose-Files   Comma-separated absolute compose file paths, the
  *                          same ones Tilt's `<resource>-run-only` resource
  *                          passes. The project root is mounted into this

package/runtime/engine/assets/scripts/mac-m1-resource-monitor.sh

@@ -2,7 +2,7 @@
 # Copyright (c) 2026 Flisk Landscape contributors
 # SPDX-License-Identifier: MIT
 
-# Flisk Landscape Mac M1 Resource Monitor
+# Flisk Mac M1 Resource Monitor
 # Monitors Docker container resource usage and provides optimization recommendations
 
 set -e
@@ -14,7 +14,7 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
-echo -e "${BLUE}🍎 Flisk Landscape Mac M1 Resource Monitor${NC}"
+echo -e "${BLUE}🍎 Flisk Mac M1 Resource Monitor${NC}"
 echo "=================================================="
 
 # Check if Docker is running
@@ -33,19 +33,19 @@ echo -e "${BLUE}💻 System Memory:${NC} $SYSTEM_MEMORY"
 
 echo ""
 
-# Check running Flisk Landscape containers
+# Check running Flisk containers
 PROJECT_CONTAINERS=$(docker ps --format "{{.Names}}" | grep -E "(postgres|redis|nats|kafka|traefik|clickhouse|elasticsearch|verdaccio|infisical)" | sort)
 
 if [ -z "$PROJECT_CONTAINERS" ]; then
-    echo -e "${YELLOW}⚠️  No Flisk Landscape containers are currently running${NC}"
+    echo -e "${YELLOW}⚠️  No Flisk containers are currently running${NC}"
     echo "Run 'tilt up' to start services"
     exit 0
 fi
 
-echo -e "${GREEN}📊 Running Flisk Landscape Containers:${NC}"
+echo -e "${GREEN}📊 Running Flisk Containers:${NC}"
 echo "=================================================="
 
-# Get detailed stats for Flisk Landscape containers
+# Get detailed stats for Flisk containers
 TOTAL_MEMORY_MB=0
 HIGH_CPU_COUNT=0
 HIGH_MEMORY_COUNT=0

package/runtime/engine/schemas/service-schema.json

@@ -12,7 +12,12 @@
         },
         "required": [
           "appType"
-        ]
+        ],
+        "not": {
+          "required": [
+            "command"
+          ]
+        }
       },
       "then": {
         "properties": {
@@ -35,7 +40,12 @@
         },
         "required": [
           "appType"
-        ]
+        ],
+        "not": {
+          "required": [
+            "command"
+          ]
+        }
       },
       "then": {
         "properties": {
@@ -55,7 +65,12 @@
         },
         "required": [
           "appType"
-        ]
+        ],
+        "not": {
+          "required": [
+            "command"
+          ]
+        }
       },
       "then": {
         "properties": {
@@ -79,7 +94,12 @@
         },
         "required": [
           "appType"
-        ]
+        ],
+        "not": {
+          "required": [
+            "command"
+          ]
+        }
       },
       "then": {
         "properties": {
@@ -92,9 +112,54 @@
           "port"
         ]
       }
+    },
+    {
+      "if": {
+        "required": [
+          "command"
+        ]
+      },
+      "then": {
+        "required": [
+          "appName",
+          "appType"
+        ],
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "image"
+              ]
+            },
+            {
+              "required": [
+                "dockerfile"
+              ]
+            }
+          ]
+        }
+      },
+      "else": {
+        "required": [
+          "appName",
+          "stack"
+        ],
+        "anyOf": [
+          {
+            "required": [
+              "appType"
+            ]
+          },
+          {
+            "required": [
+              "type"
+            ]
+          }
+        ]
+      }
     }
   ],
-  "description": "Configuration for Flisk resources. Drives Tilt orchestration, Docker Compose generation, and dependency resolution. Supports both explicit service.json files and synthesis from directory structure.",
+  "description": "Configuration for Flisk resources. Drives Tilt orchestration, Docker Compose generation, and dependency resolution. Supports both explicit service.json files and synthesis from directory structure. A service runs from exactly one source: a container (image, dockerfile, or a generated Dockerfile) or a local command.",
   "properties": {
     "$schema": {
       "description": "JSON Schema reference for IDE validation",
@@ -144,7 +209,7 @@
     },
     "databaseName": {
       "description": "Override auto-generated DB name.\nDefault: FLISK_{stack}",
-      "pattern": "^Flisk_[a-z_]+$",
+      "pattern": "^FLISK_[a-z_]+$",
       "type": "string"
     },
     "dependencies": {
@@ -513,25 +578,26 @@
           "default": "files"
         }
       }
+    },
+    "command": {
+      "description": "Run the service as a local process with this shell command instead of a container, for example \"node server.js\" or \"uvicorn main:app --port $PORT\". It runs from the service directory with PORT set to port. No image, Dockerfile or generated files: flisk up starts, supervises and restarts it without Docker or Tilt. Cannot be combined with image or dockerfile.",
+      "minLength": 1,
+      "type": "string"
+    },
+    "env": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Environment variables for a command service. Values may reference ${VAR} (or ${VAR:-default}) from the project .env or the shell.",
+      "propertyNames": {
+        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+      },
+      "type": "object"
     }
   },
   "required": [
-    "appName",
-    "stack",
     "schemaVersion"
   ],
   "title": "Flisk Resource Configuration",
-  "type": "object",
-  "anyOf": [
-    {
-      "required": [
-        "appType"
-      ]
-    },
-    {
-      "required": [
-        "type"
-      ]
-    }
-  ]
+  "type": "object"
 }

package/runtime/engine/scripts/debug-container.sh

@@ -157,7 +157,7 @@ diagnostics_menu() {
     case $choice in
         1)
             echo -e "${BLUE}Testing network connectivity...${NC}"
-            run_command "$resource_name" "nc -zv registry.npmjs.org 443 && nc -zv Flisk Landscape-verdaccio 4873"
+            run_command "$resource_name" "nc -zv registry.npmjs.org 443 && nc -zv flisk-verdaccio 4873"
             ;;
         2)
             echo -e "${BLUE}Viewing configuration files...${NC}"

package/runtime/engine/scripts/generate-manifest.sh

@@ -2,7 +2,7 @@
 # Copyright (c) 2026 Flisk Landscape contributors
 # SPDX-License-Identifier: MIT
 # =============================================================================
-# 🎯 Flisk Landscape - RESOURCE MANIFEST GENERATOR
+# 🎯 Flisk - RESOURCE MANIFEST GENERATOR
 # =============================================================================
 # Usage: ./generate-manifest.sh <stack> <resource-name> <type> [port]
 #
@@ -37,7 +37,7 @@ PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
 print_usage() {
     cat << EOF
 ${BLUE}╔═══════════════════════════════════════════════════════════════════╗
-║  🎯  Flisk Landscape RESOURCE MANIFEST GENERATOR                          ║
+║  🎯  Flisk RESOURCE MANIFEST GENERATOR                          ║
 ╚═══════════════════════════════════════════════════════════════════╝${NC}
 
 ${YELLOW}Usage:${NC}