@flisk-sh/flisk 1.4.2 → 1.4.5

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Notable changes to the `flisk` CLI. Versions match [npm](https://www.npmjs.com/package/@flisk-sh/flisk?activeTab=versions) and the [binary releases](https://github.com/flisk-sh/releases/releases).
 
+## 1.4.3 (2026-10-25)
+
+- `flisk init` is now an alias of `flisk project`. It accepts the same template names and flags.
+
 ## 1.3.195 (2026-10-21)
 
 - `flisk demo` and `flisk restaurant` now clone the demo template into a fixed directory (`~/.flisk/flisk-demo/`) instead of creating `tdk-restaurant-example-N` directories in the current workspace. Previous runs are cleaned up automatically. The `restaurant` template still creates a named directory in the current folder when used explicitly.

package/README.md

@@ -81,7 +81,11 @@ Stop my Flisk stack with flisk down and confirm nothing is left running.
 <details>
 <summary>Connect your agent to Flisk as an MCP server</summary>
 
-Add this to your agent's MCP settings:
+Install the CLI, then add the Flisk MCP server to your agent's settings:
+
+```bash
+npm install -g @flisk-sh/flisk
+```
 
 ```json
 {
@@ -223,12 +227,9 @@ Fastest way (recommended): open the [Flisk starter](https://github.com/flisk-sh/
 
 </details>
 
-### ⚡ A running stack in about 14 seconds
+### ⚡ A one-backend stack is healthy in about 14 seconds
 
-On a one-backend quickstart with warm image layers, `flisk up` reaches a healthy API in 12.8 to 13.8 seconds ([timing notes](docs/benchmarks/quickstart-timing.md)). An 8-service stack settles in 32 to 42 seconds warm and about 4.5 minutes on its first cold build ([benchmark](docs/benchmarks/results/tdk-up-warm-start-2026-10-11/summary.md)). No vendor lock-in and no hand-written plumbing. Flisk works with:
-* **Runtimes & Frameworks:** Bun, Node, Python, Go, Rust, React, Vue, Svelte, Elysia, Fastify, NestJS
-* **Databases & Tooling:** Prisma, Drizzle, Atlas, Dbmate
-* **Messaging & Gateway:** NATS, Traefik
+On a one-backend quickstart with warm image layers, `flisk up` reaches a healthy API in 12.8 to 13.8 seconds ([timing notes](docs/benchmarks/quickstart-timing.md)). An 8-service stack settles in 32 to 42 seconds warm and about 4.5 minutes on its first cold build ([benchmark](docs/benchmarks/results/tdk-up-warm-start-2026-10-11/summary.md)). No vendor lock-in and no hand-written plumbing.
 
 ### 🤖 Run your AI agents next to your services
 
@@ -311,6 +312,12 @@ See [how `flisk up` works](docs/how-flisk-up-works.md) for the full startup sequ
 | Catch config drift | Compares generated files with what Flisk last wrote | `flisk config verify` |
 | Keep Flisk current | Upgrades the CLI in place | `flisk upgrade` |
 
+Flisk works with:
+
+* **Runtimes & Frameworks:** Bun, Node, Python, Go, Rust, React, Vue, Svelte, Elysia, Fastify, NestJS
+* **Databases & Tooling:** Prisma, Drizzle, Atlas, Dbmate
+* **Messaging & Gateway:** NATS, Traefik
+
 ## Who uses Flisk
 
 Teams that run `flisk up` on their own code (listed with their consent in [ADOPTERS.md](docs/project/ADOPTERS.md)):
@@ -326,67 +333,134 @@ If Flisk saves you time, a ⭐ on [this repo](https://github.com/flisk-sh/flisk)
 
 ## Quick start
 
-There are two ways to get started. Both end with `flisk up <stack>`.
+Get a running local stack in **3 commands**. Works on macOS, Linux, and Windows (via WSL2).
 
-| | Guided scaffolder | Core CLI (manual) |
-| --- | --- | --- |
-| Best for | A first run: pick your services and get a ready project | Full control, or adding Flisk to an existing folder |
-| Package | [`create-microservices`](https://github.com/flisk-sh/create-microservices#readme) | [`@flisk-sh/flisk`](https://www.npmjs.com/package/@flisk-sh/flisk) (this repo) |
+### Prerequisites (install once)
+
+| Tool | Version | Install | Install path |
+|------|---------|---------|--------------|
+| **Docker** | Engine 25+, Compose 2.20.2+ | [docker.com](https://www.docker.com/products/docker-desktop/) | All paths |
+| **Tilt** | 0.25+ | `curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh \| bash` | All paths |
+| **Node.js** | 22.12+ | [nodejs.org](https://nodejs.org/) | npm path (`npm install -g @flisk-sh/flisk`) |
+| **Bun** | 1.2+ | `curl -fsSL https://bun.sh/install \| bash` | Bun path (`bun add -g @flisk-sh/flisk`) |
 
-### Option A: guided scaffolder (recommended for beginners)
+> **Conditional prerequisites**: Node.js is only required when you install Flisk via npm (`npm install -g @flisk-sh/flisk`). Bun is only required when you install via Bun or your project has generated JavaScript services. Docker and Tilt are required for every path.
 
-**Prerequisites.** Install these first. The scaffolder checks your machine while it creates the project and stops if something is missing:
+> **Windows?** Use WSL2 Ubuntu. See the [Windows & WSL2 guide](docs/wsl2.md) for the recommended setup.
 
-- Node.js 22.12 or newer, and npm
-- Docker, installed and running (Engine 25+, Compose 2.20.2+)
-- [Tilt](https://docs.tilt.dev/install.html)
-- [Bun](https://bun.sh/) 1.2+
+---
 
-Run these commands from the directory where you want the new project folder to be created. The target directory must be new or empty; existing files are never overwritten.
+### Fastest path: one-command demo (no manual steps)
 
 ```bash
+# 1. Install Flisk
 npm install -g @flisk-sh/flisk
-npm init create-microservices my-project
-cd my-project
-flisk up main
+
+# 2. Run the demo — scaffolds a project, installs deps, boots the stack, opens the frontend
+flisk demo
 ```
 
-- `npm install -g @flisk-sh/flisk` installs the `flisk` command. Skip it if `flisk --version` already works.
-- `npm init create-microservices my-project` asks how many services to create, then each service's name and type (`backend`, `frontend`, `worker`, or `mcp`).
-- `flisk up main` starts the stack. `main` is the default stack name; if you pass `--stack <name>` to the scaffolder, use that name instead. The scaffolder prints the exact `flisk up` command when it finishes.
+That's it. The demo clones the starter into `~/.flisk/flisk-demo`, installs dependencies, starts the stack, and opens the frontend in your browser. Press `Ctrl+C` to stop, then run `flisk down` to clean up.
 
-The scaffolder creates the project configuration and a skeleton for each service you selected, using Flisk CLI Core. It does not start any containers; `flisk up` does that.
+---
 
-To skip the prompts and get a default `api` (backend) and `web` (frontend):
+### Full control: manual project setup
+
+If you want to build your own service structure:
 
 ```bash
-npm init create-microservices my-project -- --yes
+# 1. Install Flisk (skip if already installed)
+npm install -g @flisk-sh/flisk
+
+# 2. Create a project with a backend API
+mkdir my-project && cd my-project
+flisk project --yes
+flisk resource api --type backend --stack main --yes
+
+# 3. Start the stack
+flisk up main
 ```
 
-For service types, all options, and non-interactive usage, see the [`create-microservices` README](https://github.com/flisk-sh/create-microservices#readme).
+`flisk up` prints the URLs (e.g., `http://api.main.localhost/api/api/health`). Try it:
 
-> [!NOTE]
-> Two similarly named packages exist. [`create-flisk`](https://github.com/flisk-sh/create-flisk) is a landing-page app and does not scaffold projects. [`create-microservices`](https://github.com/flisk-sh/create-microservices#readme) is the project scaffolder used above.
+```bash
+curl http://api.main.localhost/api/api/health
+```
 
-### Option B: core CLI (manual)
+To add a frontend later:
 
-Use this to create the project and each resource yourself with `flisk`. [Install the CLI](#installation) first. Preview what a stack will start before any container runs:
+```bash
+flisk resource web --type frontend --stack main --yes
+flisk up main
+```
+
+---
+
+### Alternative: guided scaffolder
+
+Prefer interactive prompts? The `create-microservices` package asks for your service types and generates a ready project:
 
 ```bash
-flisk up shop --dry-run
+npm install -g @flisk-sh/flisk
+npm init create-microservices my-project
+cd my-project
+flisk up main
 ```
 
-Then try the full flow:
+To skip prompts and get a default `api` + `web`:
 
 ```bash
-mkdir shop && cd shop
-flisk project --yes
-flisk resource orders-api --type backend --stack shop --yes
-flisk up shop
-curl http://api.shop.localhost/api/orders/health
+npm init create-microservices my-project -- --yes
 ```
 
-`flisk up` prints the host ports it chose. It uses port 80 when it is free, so URLs carry no port. Otherwise it picks one from 8080-8180, and the URLs it prints include that port (on Linux and WSL2 a non-root user cannot check port 80, so the range is used there). Use the URL `flisk up` prints, or set `FLISK_HTTP_PORT`. A resource named `orders-api` is served at `/api/orders` (a trailing `-api` is dropped); `flisk up` prints the exact URLs.
+See the [`create-microservices` README](https://github.com/flisk-sh/create-microservices#readme) for all options.
+
+---
+
+### Verify it works
+
+After `flisk up`, you'll see output like:
+
+```
+Flisk is up.
+Tilt UI: http://localhost:10350
+Services:
+  ✓ api → http://api.main.localhost/api/api/health
+  ✓ web → http://web.main.localhost
+Stop: flisk down
+Logs: flisk logs <service>
+Next: flisk help  # or visit https://flisk.sh/docs
+```
+
+- **Tilt UI**: Open to watch live updates, see logs, and debug
+- **Services**: Click the URLs or curl the health endpoints
+- **Stop**: `flisk down` stops everything; containers persist for inspection
+
+---
+
+### Common next steps
+
+| Goal | Command |
+|------|---------|
+| See running services | `flisk ui` |
+| Check environment health | `flisk doctor` |
+| View service logs | `flisk logs api` |
+| Restart a service | `flisk restart api` |
+| Preview without starting | `flisk up main --dry-run` |
+| Catch config drift | `flisk config verify` |
+| Upgrade Flisk | `flisk upgrade` |
+
+### Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `flisk doctor` fails | Run the fix commands it prints, then retry |
+| Port 80/5432 in use | `flisk doctor` shows the owner; stop it or set `FLISK_HTTP_PORT` |
+| Docker not running | Start Docker Desktop / `systemctl start docker` |
+| Windows native | Use WSL2 Ubuntu; see [Windows guide](docs/wsl2.md) |
+| `flisk up` refuses | Run `flisk doctor` first; it explains what's missing |
+
+Full troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
 
 ### What Flisk writes for you
 
@@ -526,7 +600,7 @@ Runnable examples show Flisk on real stacks. Start with the smallest one:
 
 ## Use Flisk with your AI agent
 
-The repository ships agent skills for common Flisk work, including `flisk-doctor` (environment checks) and `flisk-troubleshoot` (fixing `flisk` and Tilt errors), under [`.agents/skills`](.agents/skills). Agents working in this repo also follow [AGENTS.md](AGENTS.md). Use these skills to let your agent check your setup and explain failures instead of guessing at Docker or Tilt configuration.
+The repository ships five agent skills for common Flisk work under [`.agents/skills`](.agents/skills): `flisk-doctor` (environment checks), `flisk-up` (preview and start a stack), `flisk-resource` (create a service), `flisk-status` (health and URLs), and `flisk-troubleshoot` (fixing `flisk` and Tilt errors). Agents working in this repo also follow [AGENTS.md](AGENTS.md). Use these skills to let your agent check your setup and explain failures instead of guessing at Docker or Tilt configuration.
 
 ## Installation
 
@@ -598,7 +672,7 @@ published on 21 September 2026. Those dates describe the current repository and
 
 ## Requirements and support
 
-For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20.2+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. Flisk selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set `FLISK_HTTP_PORT`, `FLISK_HTTPS_PORT`, or `FLISK_POSTGRES_PORT` to override them. Dev ports listen on `127.0.0.1` only, so other machines on your network cannot reach them. Set `FLISK_BIND_ADDRESS` (for example `0.0.0.0`, to test from a phone) to change that; `flisk doctor` warns when it is a wildcard address. Flisk supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run `flisk doctor` to check local readiness (supports `--no-ping` to skip service health checks and `--ping-timeout <ms>`). See [WSL2 setup](docs/wsl2.md).
+For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20.2+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. Flisk selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set `FLISK_HTTP_PORT`, `FLISK_HTTPS_PORT`, or `FLISK_POSTGRES_PORT` to override them. Dev ports listen on `127.0.0.1` only, so other machines on your network cannot reach them. Set `FLISK_BIND_ADDRESS` (for example `0.0.0.0`, to test from a phone) to change that; `flisk doctor` warns when it is a wildcard address. Flisk supports macOS, Linux, and **Windows through WSL2 Ubuntu**; native Windows supports CLI inspection only (`flisk --version`, `flisk doctor`, `flisk up --dry-run`). `flisk up` exits with a clear refusal pointing to WSL2. See the **[Windows & WSL2 guide](docs/wsl2.md)** for the recommended setup, prerequisites, verification steps, and troubleshooting.
 
 On native Windows, `flisk --version`, `flisk doctor`, and `flisk up --dry-run` are inspect-only commands. `flisk up` exits 1 with “Landscape startup needs Ubuntu on WSL2. Native Windows is inspect-only.”
 
@@ -639,7 +713,7 @@ No. Core CLI is MIT and needs no key to run `flisk up`. Premium extras are optio
 <details>
 <summary><strong>Which platforms are supported?</strong></summary>
 
-macOS and Linux are supported directly. Windows is supported through WSL2 Ubuntu; native Windows supports CLI inspection only (`flisk --version`, `flisk doctor`, and `flisk up --dry-run`). See [Requirements and support](#requirements-and-support) and [WSL2 setup](docs/wsl2.md).
+macOS and Linux are supported directly. Windows is supported through WSL2 Ubuntu; native Windows supports CLI inspection only (`flisk --version`, `flisk doctor`, `flisk up --dry-run`). See [Requirements and support](#requirements-and-support) and the **[Windows & WSL2 guide](docs/wsl2.md)** for the recommended setup, prerequisites, verification steps, and troubleshooting.
 
 </details>
 
@@ -735,3 +809,5 @@ Thank you to everyone who has shipped code, docs, and fixes to Flisk since July
 Flisk is MIT-licensed; see [LICENSE](LICENSE). The [license boundary](docs/project/GOVERNANCE.md#license-boundary-and-donation-scope) says which code is MIT and which is downloaded with a key.
 
 Project governance: [GOVERNANCE.md](docs/project/GOVERNANCE.md), [MAINTAINERS.md](docs/project/MAINTAINERS.md), [ADOPTERS.md](docs/project/ADOPTERS.md).
+
+<img src='https://raw.githubusercontent.com/flisk-sh/flisk-emoji/main/png/flisk-thunder-64.png' width='20' alt='flisk'> Using Flisk in Slack or Discord? Get the [Flisk green thunder emoji](https://github.com/flisk-sh/flisk-emoji) (SVG and PNG, MIT).

package/cli/dist/backend-languages/bun.js

@@ -24,9 +24,14 @@ app.get('/health/db', async (c) => {
 `
         : "";
     return `import { Hono } from 'hono';
+import { cors } from 'hono/cors';
 ${drizzleImports}
 const app = new Hono();
 
+// The frontend runs on its own *.localhost origin (app.<project>.localhost), so the browser needs CORS to call this API.
+const LOCAL_FRONTEND_ORIGIN = /^https?:\\/\\/([a-z0-9-]+\\.)+localhost(:\\d+)?$/;
+app.use('*', cors({ origin: (origin) => (LOCAL_FRONTEND_ORIGIN.test(origin) ? origin : undefined) }));
+
 // Health check endpoint (required by TILT_RESOURCE_DEFAULTS.star)
 app.get('/health', (c) => {
   return c.json({ status: 'ok', service: '${name}' });

package/cli/dist/backend-languages/go.js

@@ -34,7 +34,9 @@ import (
 func writeJSON(w http.ResponseWriter, status int, body any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(body)
+	if err := json.NewEncoder(w).Encode(body); err != nil {
+		log.Printf("failed to encode JSON response: %v", err)
+	}
 }
 
 func newMux() *http.ServeMux {

package/cli/dist/cli.js

@@ -12,6 +12,7 @@ import { showHelp } from "./commands/help.js";
 import { createProgram } from "./program.js";
 import { ensureGlobalInstall } from "./utils/cli-command.js";
 import { formatColdPreflight, runColdPreflight } from "./utils/cold-preflight.js";
+import { stopDemoStack } from "./utils/demo-reset.js";
 import { unknownHelpTarget } from "./utils/help-command.js";
 import { bareTemplateArg } from "./utils/project-templates.js";
 const program = createProgram();
@@ -68,6 +69,7 @@ if (templateArg) {
         }
     }
     const destination = isAbsolute(targetName) ? targetName : resolve(cwd(), targetName);
+    console.log(chalk.gray(`📁 Demo folder: ${destination}`));
     // Reusing an existing checkout is what keeps a second take free: the clone and the
     // dependency install are skipped, so the recording starts on the interesting part.
     let reused = false;
@@ -85,6 +87,13 @@ if (templateArg) {
             await openUrl(running.url);
             process.exit(0);
         }
+        // Take the old stack down before its folder goes, so a Traefik left behind does not keep port 80.
+        try {
+            stopDemoStack(destination);
+        }
+        catch (error) {
+            console.log(chalk.yellow(`Could not stop the previous demo stack: ${error.message}`));
+        }
         if (keep) {
             reused = true;
         }

package/cli/dist/commands/completion.js

@@ -463,7 +463,14 @@ _flisk_resources() {
 ${subCommandLists}
 
 ${typeValueFunctions}
-compdef _flisk flisk
+
+# Autoloaded from fpath, this file is the body of _flisk, so run it now to complete the first TAB.
+# Sourced (\`source <(flisk completion zsh)\`), register it instead.
+if [ "$funcstack[1]" = "_flisk" ]; then
+    _flisk "$@"
+else
+    compdef _flisk flisk
+fi
 `;
 }
 /** The `_arguments` spec of one flag, with the values it completes when it has them. */

package/cli/dist/commands/config.js

@@ -9,7 +9,8 @@ import { hasVerdaccioLicense } from "../generator/extension-fetch.js";
 import { generateMasterConfigs, readProjectConfig, TemplateEngine, verifyMasterConfigs, } from "../generator/template-engine.js";
 import { isMasterConfigFileName } from "../types/index.js";
 import { assertValid, handleDryRun } from "../utils/command-helpers.js";
-import { MASTER_CONFIG_FILES, PROJECT_JSON } from "../utils/constants.js";
+import { explainConfigFile } from "../utils/config-explain.js";
+import { MASTER_CONFIG_FILES, PROJECT_JSON, RESOURCE_DEFAULTS_FILE, TECH_STACK_FILE, } from "../utils/constants.js";
 import { clearDiscoveryCache } from "../utils/discovery-context.js";
 import { checkPrismaConsistency } from "../utils/doctor-wiring.js";
 import { errorFactories, requireProjectRoot, runCommand, showError } from "../utils/errors.js";
@@ -20,6 +21,12 @@ import { SERVICE_MANIFEST_SCHEMA_VERSION, validateServiceManifest, } from "../ut
 import { discoverResourcesWithProblems, discoverServiceManifestPaths, warnAboutSkippedFiles, } from "../utils/services.js";
 import { evaluateSharedPlatformPostgres } from "../utils/shared-platform-postgres.js";
 import { validateOptionalInfraService } from "../utils/validation.js";
+/** Human wording for `flisk config explain`, one line per drift outcome. */
+const DRIFT_LABELS = {
+    "blocks-up": "yes, until the edit is removed or --ignore-drift is passed",
+    none: "no",
+    unknown: "unknown",
+};
 export const configCommand = new Command("config")
     .description("Manage project configuration and regenerate master files")
     .addCommand(new Command("regenerate")
@@ -36,72 +43,104 @@ export const configCommand = new Command("config")
             const newFiles = engine.generateAll(projectConfig);
             const outputDir = join(projectRoot, ".flisk", ".flisk-out");
             const filesToCheck = MASTER_CONFIG_FILES;
+            const fileGroups = [
+                {
+                    title: "📋 Core orchestration",
+                    files: [TECH_STACK_FILE, RESOURCE_DEFAULTS_FILE],
+                    description: "Tilt tech stack and resource defaults; drives all service generation",
+                },
+                {
+                    title: "📦 Project spec",
+                    files: ["spec.master"],
+                    description: "Compiled project specification; used by Tilt for service discovery",
+                },
+            ];
             let hasChanges = false;
-            for (const filename of filesToCheck) {
-                // Runtime validation with type guard eliminates type assertion
-                if (!isMasterConfigFileName(filename)) {
-                    continue; // Skip unknown files (shouldn't happen with const array)
-                }
-                const newContent = newFiles[filename];
-                const filePath = join(outputDir, filename);
-                if (!existsSync(filePath)) {
-                    console.log(chalk.yellow(`📁 ${filename}`));
-                    console.log(chalk.gray("   Status: NEW (file does not exist)\n"));
-                    hasChanges = true;
-                    continue;
-                }
-                const currentContent = readFileSync(filePath, "utf-8");
-                if (currentContent === newContent) {
-                    console.log(chalk.green(`✓ ${filename}`));
-                    console.log(chalk.gray("   Status: No changes\n"));
-                }
-                else {
-                    console.log(chalk.yellow(`📝 ${filename}`));
-                    console.log(chalk.gray("   Status: MODIFIED"));
-                    const currentLines = currentContent.split("\n").length;
-                    const newLines = newContent.split("\n").length;
-                    const lineDiff = newLines - currentLines;
-                    if (lineDiff > 0) {
-                        console.log(chalk.gray(`   Lines: ${currentLines} → ${newLines} (+${lineDiff})`));
+            for (const group of fileGroups) {
+                let groupHasChanges = false;
+                const groupChanges = [];
+                for (const filename of group.files) {
+                    if (!filesToCheck.includes(filename))
+                        continue;
+                    if (!isMasterConfigFileName(filename))
+                        continue;
+                    const newContent = newFiles[filename];
+                    const filePath = join(outputDir, filename);
+                    if (!existsSync(filePath)) {
+                        groupHasChanges = true;
+                        groupChanges.push({ filename, isNew: true, lineDiff: 0, diffLines: [] });
+                        continue;
                     }
-                    else if (lineDiff < 0) {
-                        console.log(chalk.gray(`   Lines: ${currentLines} → ${newLines} (${lineDiff})`));
-                    }
-                    else {
-                        console.log(chalk.gray(`   Lines: ${currentLines} (content changed)`));
-                    }
-                    const currentLinesArr = currentContent.split("\n");
-                    const newLinesArr = newContent.split("\n");
-                    let firstDiffLine = -1;
-                    for (let i = 0; i < Math.max(currentLinesArr.length, newLinesArr.length); i++) {
-                        if (currentLinesArr[i] !== newLinesArr[i]) {
-                            firstDiffLine = i;
-                            break;
+                    const currentContent = readFileSync(filePath, "utf-8");
+                    if (currentContent !== newContent) {
+                        groupHasChanges = true;
+                        const currentLines = currentContent.split("\n").length;
+                        const newLines = newContent.split("\n").length;
+                        const lineDiff = newLines - currentLines;
+                        const currentLinesArr = currentContent.split("\n");
+                        const newLinesArr = newContent.split("\n");
+                        let firstDiffLine = -1;
+                        for (let i = 0; i < Math.max(currentLinesArr.length, newLinesArr.length); i++) {
+                            if (currentLinesArr[i] !== newLinesArr[i]) {
+                                firstDiffLine = i;
+                                break;
+                            }
                         }
-                    }
-                    if (firstDiffLine >= 0) {
-                        console.log(chalk.gray(`   First change around line ${firstDiffLine + 1}:`));
-                        const contextStart = Math.max(0, firstDiffLine - 1);
-                        const contextEnd = Math.min(currentLinesArr.length, firstDiffLine + 2);
-                        for (let i = contextStart; i < contextEnd; i++) {
-                            const line = currentLinesArr[i];
-                            const newLine = newLinesArr[i];
-                            if (line !== newLine) {
-                                if (line !== undefined) {
-                                    console.log(chalk.red(`     - ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
+                        const diffLines = [];
+                        if (firstDiffLine >= 0) {
+                            const contextStart = Math.max(0, firstDiffLine - 1);
+                            const contextEnd = Math.min(currentLinesArr.length, firstDiffLine + 2);
+                            for (let i = contextStart; i < contextEnd; i++) {
+                                const line = currentLinesArr[i];
+                                const newLine = newLinesArr[i];
+                                if (line !== newLine) {
+                                    if (line !== undefined) {
+                                        diffLines.push(chalk.red(`     - ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
+                                    }
+                                    if (newLine !== undefined) {
+                                        diffLines.push(chalk.green(`     + ${newLine.substring(0, 60)}${newLine.length > 60 ? "..." : ""}`));
+                                    }
                                 }
-                                if (newLine !== undefined) {
-                                    console.log(chalk.green(`     + ${newLine.substring(0, 60)}${newLine.length > 60 ? "..." : ""}`));
+                                else {
+                                    diffLines.push(chalk.gray(`       ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
                                 }
                             }
+                        }
+                        groupChanges.push({ filename, isNew: false, lineDiff, diffLines });
+                    }
+                }
+                if (groupHasChanges) {
+                    console.log(chalk.blue(`\n${group.title}`));
+                    console.log(chalk.gray(`   ${group.description}\n`));
+                    for (const change of groupChanges) {
+                        if (change.isNew) {
+                            console.log(chalk.yellow(`  📁 ${change.filename}`));
+                            console.log(chalk.gray("     Status: NEW (file does not exist)\n"));
+                        }
+                        else {
+                            console.log(chalk.yellow(`  📝 ${change.filename}`));
+                            console.log(chalk.gray("     Status: MODIFIED"));
+                            if (change.lineDiff > 0) {
+                                console.log(chalk.gray(`     Lines: +${change.lineDiff}`));
+                            }
+                            else if (change.lineDiff < 0) {
+                                console.log(chalk.gray(`     Lines: ${change.lineDiff}`));
+                            }
                             else {
-                                console.log(chalk.gray(`       ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
+                                console.log(chalk.gray("     Lines: content changed"));
                             }
+                            for (const diffLine of change.diffLines) {
+                                console.log(diffLine);
+                            }
+                            console.log("");
                         }
                     }
-                    console.log("");
                     hasChanges = true;
                 }
+                else {
+                    console.log(chalk.green(`\n✅ ${group.title} — all up to date`));
+                    console.log(chalk.gray(`   ${group.description}\n`));
+                }
             }
             if (hasChanges) {
                 console.log(chalk.blue("💡 Run without --dry-run to apply these changes.\n"));
@@ -268,6 +307,42 @@ export const configCommand = new Command("config")
         return;
     }
     await runCommand(action);
+}))
+    .addCommand(new Command("explain")
+    .description("Explain whether a project file is Flisk-generated and what editing it does on flisk up")
+    .argument("<file>", "Project file to explain, relative to the current directory or absolute")
+    .option("--json", "Emit a machine-readable explanation")
+    .action(async (file, options) => {
+    const action = async () => {
+        const projectRoot = options.json ? findProjectRoot() : requireProjectRoot();
+        if (!projectRoot)
+            throw errorFactories.notInProject();
+        const explanation = explainConfigFile(projectRoot, file);
+        if (options.json) {
+            console.log(JSON.stringify(createMachineEnvelope(explanation)));
+            return;
+        }
+        console.log(chalk.blue(`${explanation.file}\n`));
+        console.log(`  Ownership: ${explanation.ownership}`);
+        console.log(`  ${explanation.reason}`);
+        if (explanation.source)
+            console.log(`  Source: ${explanation.source}`);
+        console.log(`  Edited now: ${explanation.isEditedNow ? "yes" : "no"}`);
+        console.log(`  Editing it blocks flisk up: ${DRIFT_LABELS[explanation.driftOnUp]}`);
+        console.log(chalk.blue("\nNext:"));
+        for (const step of explanation.next)
+            console.log(chalk.gray(`  - ${step}`));
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (error) {
+            writeMachineError(error);
+        }
+        return;
+    }
+    await runCommand(action);
 }))
     .addCommand(new Command("edit").description("Open .flisk/project.json in your $EDITOR").action(async () => {
     await runCommand(async () => {