Native Windows can inspect. It cannot start the stack. The start path is Ubuntu on WSL2, in the Ubuntu shell, not in PowerShell and not in cmd.

Docker has to be Linux containers, with WSL2 integration on. If flisk doctor says the daemon is using the Windows engine, that is the fix it already printed. Switch the engine. Do not keep typing flisk up at the same prompt.

The path in the docs

Run this in Ubuntu. The first command copies the bundled example into your home directory. The second configures that copy.

flisk doctor
flisk project example --path "$HOME/tdk-example"
cd "$HOME/tdk-example"
flisk project --yes
sed -i 's/^INFISICAL_ENABLED=.*/INFISICAL_ENABLED=false/' .env
flisk config verify
flisk doctor
flisk up shop

Leave flisk up shop running. Use a second Ubuntu terminal for curl. Set HTTP_PORT to the port that flisk up printed. That is 80 when port 80 is free, and 8080 on WSL2 when it is not. Do not assume 80 because a Mac screenshot showed 80.

The repo has a smoke test that does the same shape: copy the example, doctor, verify, boot, hit the routed write, watch the worker, tear the stack down. If your manual run cannot create an order and see the worker mark it, you do not have the example running. You have a container that happened to start.

What people skip

sed turns Infisical off in that example's .env. Skip it and the boot is waiting on a secrets tool you did not mean to use.

flisk config verify before the second doctor is there because a hand-edited generated file should fail before Tilt does. If verify fails, regenerate. Do not "fix" the Tiltfile in the Ubuntu home directory and call that a Windows bug.

Files written from Windows onto the Linux filesystem, or the other way around, are a WSL problem, not a Flisk feature. Keep the repo in the Linux home directory if the bind mounts look empty.

WSL2 notes

flisk.sh

flisk up does not need a key. Core is MIT. Most teams should stay there. Premium is optional, at $19 per developer per month, and it unlocks extras. It does not buy an SLA, a weekend page, or a promise that someone will join your incident.

The repo is explicit about what it does not publish: the price lives on the site, the licence terms for the premium code are not in the tree, and a premium key is a feature key. Read that again before you put the key in a runbook titled "support".

What the key is for

The extras called out in the project docs are a local Verdaccio registry, a DDD scaffold, and idle stop. They are gated. The core path, including flisk up, is not.

Set the key in the environment the CLI already looks at:

export TDK_LICENSE_KEY="the-key-you-were-sent"

The variable still says TDK_ because the on-disk names were not all renamed. That is the same CLI. See the post about flisk versus tdk if that bothers you. Do not invent FLISK_LICENSE_KEY and then wonder why the extra stayed locked.

A key is capped. The site says up to 100 project IDs on one key. A key posted in a public chat is not a team plan. It is a key you can no longer revoke per person.

What you do not get

You do not get production hosting. You do not get Helm values. You do not get a measured onboarding number. The speed figures on the site are lab runs, including a 100-service health fixture that is not an ERP. The savings calculator is arithmetic on inputs you type.

You also do not get a second support tier because you paid. If flisk doctor fails, the fix is the ℹ Fix: line. A key does not change that line.

If you want a key, use the request on flisk.sh. If you do not want the extras, do not request one. The free CLI is the product. The $19 is a feature flag with a price, not a reason to migrate a monorepo.

github.com/flisk-sh/flisk

flisk resource --type backend scaffolds Bun and Hono. That is the default on purpose. Omit --language and the output stays byte-identical to the historical scaffold. Interactive create does not ask you to pick a language.

Python, Go, Rust, and Node are opt-in. You name them, or you do not get them.

flisk resource api --type backend --stack shop --yes
flisk resource api --type backend --language go --stack shop
flisk resource --type backend --frameworks

The first command is the default. The second is an explicit provider. The third lists registered backend frameworks: id, display name, the language they scaffold with, and the command that creates them. An unknown id fails before any file is written. Python and python match. A legacy service.json with no language field stays valid and is not rewritten.

What Go actually writes

--language go writes go.mod, main.go, and main_test.go. The server is the standard library, GET /health, reads PORT, and listens on every interface. The image is a golang:1.23 build stage plus a production stage, because Tilt builds --target production. A test stage is there so CI can run the language's tests in the image.

The id is stored as framework in service.json. Omitting the flag writes no framework field.

Live reload is also opt-in. Add it, then run flisk up again:

{ "dev": { "liveReload": true } }

What not to do in a pull request

One language per pull request. Copy the Python provider and its tests. Register it. Add the Dockerfile template. Do not edit engine/schemas/service-schema.json to add the id. language there is an open string. The CLI registry is what rejects an unknown id.

Do not add that language's dependencies to the CLI package. Do not "improve" the default by making interactive create prompt for a language. Bun stays the default so old output does not move under you.

flisk config regenerate rebuilds project-level config. It does not recreate resource source. If you wanted a Go service and you already generated Bun, make a new resource with --language go. Do not hand-convert main.go into the Bun directory and expect verify to bless it.

Backend language providers

flisk.sh

services/orders-api/ .autogenerated/ Docker service.json -- tdk up --> Dockerfile | src/ Tiltfile v Traefik routes Tilt watches | v api.shop.localhost A small shop stack looks like this: tdk up shop | +-------------------+-------------------+ | | | orders-api storefront postgres | | | +-------------------+-------------------+ | Traefik | *.shop.localhost The shortest loop: mkdir shop && cd shop tdk project --yes tdk resource orders-api --type backend --stack shop --yes tdk up shop --dry-run tdk up shop tdk doctor checks Docker, Tilt, and ports. tdk ui is a terminal dashboard for the running services. tdk config verify catches drift if someone hand-edits a generated file. It is local dev only. Production stays on Helm, Argo CD, or Kustomize. Core is MIT and does not need a key. You need Docker and Tilt. macOS and Linux work directly. Windows needs WSL2 Ubuntu. Native Windows can inspect, not start the stack. Repo: https://github.com/tdk-landscape/tdk-cli-core If Compose or Tilt already works for you, would a service.json still be worth it, or is that just another file to keep in sync?

This article draws the whole system in one Mermaid diagram, then walks through it. The diagram follows the repository's own maintainer guide (docs/TOPOLOGY.md) and the folders I read in the source. Some labels are summaries, so check the names against the repo before you rely on a single one.

The diagram

flowchart TD
    %% ---------- People and clients ----------
    DEV["Developer at a terminal"]
    AGENT["AI agent: Codex or Claude Code"]
    IDE["IDE and editor"]

    %% ---------- Inputs you own ----------
    subgraph INPUTS["Inputs you own"]
        PROJ[".tdk/project.json"]
        SVC["service.json per service"]
        SRC["Application source code"]
        TILTF["Project Tiltfile"]
        ENVF["Environment files and secrets"]
    end

    %% ---------- CLI in TypeScript ----------
    subgraph CLI["CLI in TypeScript: cli/src"]
        direction TB
        CMDS["commands: project, resource, up, down, status, logs, ui, doctor, config, mcp"]
        CFG["config and types"]
        GEN["generator: Handlebars project files"]
        FEPROV["frontend-frameworks: react, vue, svelte, solid, preact, lit, qwik, vanilla, tanstack-router"]
        BEPROV["backend-languages: bun, go, python, rust"]
        BFW["backend-frameworks: hono, express, elysia, fastify, nestjs, koa, h3, mcp"]
        MCPSRV["mcp server over stdio: doctor, up, down, status, logs, resource_list"]
        UI["ui: terminal dashboard"]
        UTIL["utils and components"]
    end

    %% ---------- CLI templates ----------
    subgraph TPL["CLI templates: cli/templates"]
        TPLT["Tiltfile.hbs"]
        TPLS["spec.master.hbs"]
        TPLSTACK["TILT_TECH_STACK.star.hbs"]
        TPLDEF["TILT_RESOURCE_DEFAULTS.star.hbs"]
    end

    %% ---------- Discovery in Starlark ----------
    subgraph DISC["Discovery in Starlark: discovery/"]
        DORCH["discovery_orchestrator.star"]
        DREG["registry.star"]
        DMAN["manifest scan and validation"]
        DSNAP["snapshots"]
    end

    %% ---------- Engine in Starlark ----------
    subgraph ENG["Engine in Starlark: engine/topologies"]
        direction TB
        subgraph GENS["tilt/generators"]
            GIDX["index.star"]
            GVITE["Vite and TypeScript configs"]
            GNPM["npm and bunfig config"]
            GPRISMA["Prisma config"]
            GENV["environment files and API helpers"]
            GAGENTS["AGENTS.md notice"]
        end
        subgraph RES["tilt/resources"]
            RDECL["resource declaration"]
            RORCH["orchestrator and generators"]
            RDEP["startup order and dependsOn"]
            RTRIG["triggers and live update"]
        end
        subgraph MAN["tilt/manifest"]
            MLOAD["manifest loader"]
            MSCHEMA["schema and constants"]
        end
        subgraph PLAT["platform"]
            PDOCK["docker: language and frontend Dockerfiles"]
            PNET["networking and Traefik"]
            PINFRA["Postgres and optional infra"]
        end
    end

    %% ---------- Generated runtime files ----------
    subgraph GENOUT["Generated per service: .autogenerated"]
        DFILE["Dockerfile.app.autogenerated"]
        NGINX["nginx.autogenerated.conf"]
        VCONF["vite and tsconfig files"]
        APIC["api-client.ts and env.ts"]
        SNAP[".tdk-contract snapshots"]
        SYAML["service.yaml projection"]
    end

    %% ---------- Checks ----------
    subgraph CHECKS["Checks"]
        DOCTOR["tdk doctor: host and canUp"]
        DRIFT["drift check: generated files vs snapshots"]
        DRYRUN["tdk up --dry-run: plan only"]
        MIGWARN["doctor warning: migration in start script"]
        READY["readiness: status and up JSON"]
    end

    %% ---------- Runtime ----------
    subgraph RUNTIME["Runtime on your machine"]
        TILT["Tilt: builds, watches, live-updates"]
        DOCKER["Docker engine"]
        TRAEFIK["Traefik proxy"]
        PG["PostgreSQL"]
        SVCS["Service containers: frontends, APIs, workers, MCP servers"]
        NATS["NATS messaging when enabled"]
    end

    %% ---------- Outside the local loop ----------
    subgraph PROD["Outside TDK: production"]
        HELM["Helm"]
        ARGO["Argo CD"]
        KUST["Kustomize"]
    end

    %% ---------- Flows ----------
    DEV --> CMDS
    IDE --> SRC
    AGENT --> MCPSRV
    MCPSRV --> CMDS

    CMDS --> GEN
    GEN --> TPL
    CMDS --> FEPROV
    CMDS --> BEPROV
    CMDS --> BFW
    CMDS --> UI
    CMDS --> CFG
    CFG --> UTIL

    PROJ --> DORCH
    SVC --> DORCH
    DORCH --> DREG
    DORCH --> DMAN
    DMAN --> MLOAD
    DREG --> DSNAP

    TILTF --> DORCH
    TILTF --> RDECL
    RDECL --> RORCH
    RORCH --> GIDX
    GIDX --> GVITE
    GIDX --> GNPM
    GIDX --> GPRISMA
    GIDX --> GENV
    GIDX --> GAGENTS
    RORCH --> RDEP
    RDEP --> RTRIG
    MLOAD --> MSCHEMA
    RORCH --> PDOCK
    RORCH --> PNET
    RORCH --> PINFRA

    GENS --> GENOUT
    PDOCK --> DFILE
    PNET --> NGINX
    GVITE --> VCONF
    GENV --> APIC
    GENOUT --> SNAP
    GENOUT --> SYAML

    CMDS --> DOCTOR
    SNAP --> DRIFT
    DRIFT --> TILT
    CMDS --> DRYRUN
    RORCH --> MIGWARN
    TILT --> READY

    SRC --> TILT
    ENVF --> TILT
    TILT --> DOCKER
    DOCKER --> TRAEFIK
    DOCKER --> PG
    DOCKER --> SVCS
    DOCKER --> NATS
    TRAEFIK --> SVCS
    SVCS --> PG
    SVCS --> NATS

    HELM --> ARGO
    KUST --> ARGO

    %% ---------- Styling ----------
    classDef cli fill:#e8f1ff,stroke:#1d4ed8,color:#0f172a
    classDef engine fill:#fff4e5,stroke:#c2410c,color:#0f172a
    classDef runtime fill:#e8fbef,stroke:#15803d,color:#0f172a
    classDef check fill:#fdecec,stroke:#b91c1c,color:#0f172a
    classDef prod fill:#f3f4f6,stroke:#6b7280,color:#0f172a
    class CMDS,CFG,GEN,FEPROV,BEPROV,BFW,MCPSRV,UI,UTIL cli
    class DORCH,DREG,DMAN,DSNAP,GIDX,RDECL,RORCH,RDEP,RTRIG,MLOAD,MSCHEMA,PDOCK,PNET,PINFRA engine
    class TILT,DOCKER,TRAEFIK,PG,SVCS,NATS runtime
    class DOCTOR,DRIFT,DRYRUN,MIGWARN,READY check
    class HELM,ARGO,KUST prod

How to read it

Start at the top left. A developer, or an agent over MCP, enters the CLI. The CLI has three jobs: scaffolding files through templates and providers, reading the project's commands, and starting the stack.

The middle of the diagram is the two-stage generation the maintainer guide describes. The CLI writes starter files in TypeScript. At Tilt time, Starlark discovery reads each service.json, and the engine's generators write the runtime files under .autogenerated/. Those files are what Docker and Tilt run.

The right side shows the checks. doctor answers whether the machine can run the stack. The drift check compares generated files with their snapshots before startup. The dry run prints the plan. The readiness output tells you, or an agent, when a service is ready.

The bottom shows the runtime: Tilt drives Docker, Docker runs the Traefik proxy, Postgres, the service containers, and NATS when it is enabled. Production sits outside the loop. The diagram ends with Helm, Argo CD, and Kustomize, because TDK does not generate cluster manifests by default.

Things the diagram leaves out

It does not show every module or every generator. The .tdk-contract snapshots, the optional observability stacks, and the golden image layer are simplified or omitted. Use the repo's topology guide when you need the full list.

Summary

TDK CLI is a loop: TypeScript commands write project files, Starlark generators turn service.json into runtime files, checks confirm the result, and Docker and Tilt run it. Keep the inputs in your hands, treat the generated files as output, and let the checks tell you when something has drifted.

Good review of generated code asks different questions from review of code written by a colleague who knows the system.

Check the claims first

Start with what the change says it does. Compare the description, the tests, and the diff. If the author says "adds retry logic" and the diff does not touch the call site, something is missing. Agents sometimes report success for work they did not complete.

Check what is not there

Generated code often omits the things a human would remember: timeouts, input validation, error handling for the failure path, cleanup of resources, and logging that helps someone debug at night. Look for what should be present and is not.

Check the dependencies

An agent may add a package you did not choose, or pick a version that does not match the rest of the project. Review every change to the manifest and the lockfile. Confirm each new package is one you would have chosen, and check that its name is spelled correctly. Typosquatted packages are a real risk.

Check the data and the secrets

Search the diff for keys, tokens, and connection strings. Check what data the code reads, stores, or sends, and where it goes. Generated code is good at moving data to convenient places, which is not always the right place.

Check the edges

Ask what happens with empty input, a very large input, a slow dependency, and two requests at once. These are the cases generated code most often skips.

Keep the review small

A reviewer can check a few hundred lines carefully. Ten thousand generated lines get a skim. If an agent produced a large change, ask it to split the work into reviewable pieces, each with its own checks.

Use tools to reduce the load

Linters, type checkers, and tests catch a large share of the mechanical errors, so the human reviewer can focus on intent and design. Run them before review, and require them to pass.

Record what you reviewed

For changes that matter, keep a short note: what was checked, what was tested, and what remains unverified. That note is useful when something fails later, and it discourages approval by habit.

Summary

Review AI-generated code by checking the claims, the omissions, the dependencies, the secrets, and the edges, in that order. Keep each review small, let tools handle the mechanical checks, and write down what you verified. Speed of generation does not change the standard a change must meet.

The sequence below follows the repo's documented behaviour: the host check, the drift check before Tilt starts, the Starlark generation at Tilt load time, readiness, and the JSON result. Some steps are summarised, so check them against the code and the docs before you rely on one exact message.

The sequence

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant Agent as AI agent over MCP
    participant CLI as tdk CLI (TypeScript)
    participant Host as Host and container runtime
    participant Snap as Snapshots in .tdk-contract
    participant Tilt as Tilt
    participant Disc as Discovery (Starlark)
    participant Eng as Engine generators (Starlark)
    participant Dock as Docker
    participant Svc as Service containers

    Dev->>CLI: tdk up (or agent calls up)
    Agent->>CLI: up (MCP tool runs tdk up --json)

    CLI->>Host: check host type and container runtime
    alt canUp is false
        Host-->>CLI: no Docker, WebContainer, or Windows opt-in missing
        CLI-->>Dev: exit non-zero, tell the reason, do not spawn Tilt
    else canUp is true
        CLI->>Snap: compare generated files with saved snapshots
        alt a generated file was hand-edited
            Snap-->>CLI: drift found, name the file
            CLI-->>Dev: block the start, fix the source and retry
        else no drift
            CLI->>Tilt: spawn Tilt with the project Tiltfile
            Tilt->>Disc: load service.json files
            Disc-->>Tilt: resources, stacks, dependsOn
            Tilt->>Eng: generate per-service runtime files
            Eng-->>Tilt: write .autogenerated and service.yaml
            Tilt->>Dock: build images, start containers in order
            Dock->>Svc: start proxy, Postgres, services
            Svc-->>Tilt: health route answers
            Tilt-->>CLI: resources report ready or failed
            CLI-->>Agent: ok true, or ok false with errors
            CLI-->>Dev: TDK is up, with URLs and ports
        end
    end

    Note over Agent,CLI: The agent polls status until readiness.ready is true
    Agent->>CLI: status
    CLI-->>Agent: readiness ready, pending, or failures
    Dev->>CLI: tdk down
    CLI->>Tilt: stop resources
    Tilt->>Dock: stop and remove containers

The steps that can stop you

Four steps can stop a start, and each one tells you something different.

The host check. If canUp is false, the machine is the problem. No change to your project will help until the host has a working container runtime. The command exits without starting Tilt.

The drift check. A hand edit to a file under .autogenerated/ blocks the start and names the file. The fix is upstream: change service.json or the generator, then start again. This check runs before Tilt is spawned, so nothing has been built yet.

Readiness. up returns before the stack is ready, because a build can take longer than one command. The result tells you whether every resource is built, running, and healthy, or which one failed. tdk status --json answers the same question at any time.

The first failed resource. A failure in one service usually stops the ones that depend on it. Read the logs for the first failed resource, not the last. tdk logs --json --service <name> --tail 200 returns a bounded snapshot.

Where the agent fits

An agent does not replace this sequence. It calls the same commands through the MCP server. The useful part for the agent is the loop: call up, poll status until ready, read logs for any failure, then stop. The sequence above shows why the poll is needed. up returns before readiness.

Stopping cleanly

tdk down reverses the lifecycle: Tilt stops the resources, and Docker removes the containers. Run it when you finish. A stack left running keeps its ports, and the next up may refuse to start while an old Tilt still answers on its port.

Summary

One tdk up is a short chain of checks before any container starts: host, drift, then generation and readiness. Each check has its own message, and each message points at the fix. Read them in order, and most starts become a matter of reading the first line that failed.

Controllers, models, views, “where does this function live?”, “which file owns the routing?” — that mental model made sense when the unit of work was a single application. It starts falling apart the moment you have more than a handful of services that need to run together locally.

The useful unit of work is no longer a function or a controller. It’s a resource that belongs to a stack inside a project.

The Old Era vs the New One

If you’re still spending afternoons reading or rewriting Dockerfiles, Tiltfiles, nginx configs, Vite configs, and health-check plumbing, you’re operating in the previous era.

Project → Stack → Resource

flowchart LR
    P["Project<br/>.tdk/project.json"] --> S1["Stack: shop"]
    P --> S2["Stack: billing"]
    S1 --> R1["orders-api<br/>backend"]
    S1 --> R2["storefront-web<br/>frontend"]
    S2 --> R3["checkout-api<br/>backend"]

• Project owns the overall landscape and phases.
• Stack is a business slice you can start on its own (tdk up shop).
• Resource is one service (backend, frontend, worker, migrator, etc.).

You declare the resource once:

{
  "$schema": "https://tdk-landscape.github.io/schema.service.json",
  "schemaVersion": 1,
  "appName": "orders-api",
  "appType": "backend",
  "stack": "shop",
  "port": 4000,
  "healthCheckPath": "/health",
  "dependsOn": []
}

Everything else is derived.

You Don’t Need to Read the Functions Anymore

This is the part that feels wrong at first if you grew up in the MVC era.

In the old model you had to read the functions because the functions were the system. The routing, the dependency wiring, the startup order, the config — all of it lived in code you were expected to understand line by line.

In the PSR model the local infrastructure is a generated artifact. TDK produces the Dockerfile, the Tiltfile, the Traefik routes, the live-update rules, the nginx/Vite/tsconfig/env files, the API client, the health probes, and the Postgres wiring from the contract. You stop treating those files as something you carefully author and constantly re-read.

flowchart TD
    A["Write service.json<br/>+ app code"] --> B["tdk up"]
    B --> C{"Drift check"}
    C -->|Clean| D["Tilt + Docker<br/>Hot reload"]
    C -->|Hand edit detected| E["Exit 2<br/>List files"]
    E --> F["tdk config regenerate"]
    E --> G["--ignore-drift"]

Hand-edits are not silently overwritten. tdk up exits with code 2 and tells you exactly which generated files drifted. You either regenerate from the contract or explicitly keep the customization. The source of truth stays the small declarative file and your application code.

Why This Is the Actual Upgrade

AI made writing application code cheap. It did not make multi-service local infrastructure consistent. Generators that treat their output as derived artifacts (and refuse to quietly wipe your changes) close that gap.

You’re falling behind if:

• You still hand-maintain a docker-compose.yml for more than a couple of services.
• You treat the Tiltfile as source instead of generated.
• You spend time reading generated nginx, Vite, or Dockerfile logic instead of changing the contract.
• Your “local setup” is a wiki page instead of tdk doctor + tdk up.

The MVC era taught us to organize code inside one process. The PSR era organizes resources that can be started, stopped, and hot-reloaded as slices of a larger system — without forcing you to re-read the plumbing every time the generator improves.

The functions still exist. You just stop needing to live inside them for the local infrastructure layer.

Getting Started

npm install -g @tdk-landscape/tdk-cli-core
tdk doctor
tdk project --yes
tdk resource orders-api --type backend --stack shop --yes
tdk up shop

MVC got you this far.
Project → Stack → Resource is how you stop maintaining the local stack by hand.