flet-box 1.0.6 → 1.0.7

package/bin/utils/templates.js

@@ -55,7 +55,7 @@ export const indexHtml = (appName = "FletBox App") => `<!DOCTYPE html>
     <div id="root"></div>
     <script>
         if ('serviceWorker' in navigator) {
-            navigator.serviceWorker.register('/service-worker.js')
+            navigator.serviceWorker.register('./service-worker.js')
                 .then(reg => console.log('Service Worker registered', reg))
                 .catch(err => console.log('Service Worker registration error', err));
         }
@@ -711,6 +711,8 @@ export const packageJson = (name) => `{
   "scripts": {
     "dev": "bash run.sh",
     "check": "node scripts/check-app.mjs",
+    "fix": "flet-box audit-fix",
+    "api": "flet-box unpack --all --md",
     "build": "flet-box createBundle www",
     "start": "npm run dev",
     "android:init": "npm run build && cap add android",
@@ -1121,58 +1123,85 @@ export const manifest = (appName = "FletBox App") => `{
 }
 `;
 
-// GitHub Actions workflow that builds web + Android + iOS in ONE run.
-// Placed at .github/workflows/ (the only location GitHub reads), NOT inside www/.
+// GitHub Actions workflow that builds and publishes the WEB. Two jobs, the way
+// the docs site does it: `build` checks and bundles `www/` and only *uploads* it,
+// `deploy` is the sole job that can touch Pages — so a build that fails leaves
+// the live site alone. The native builds are a second file (build-native.yml)
+// that only runs when started by hand.
 // NOTE: every GitHub `${{ }}` expression is escaped as `\${{ }}` because this is
 // a JS template literal — an unescaped `${` would be parsed as interpolation.
-export const githubWorkflow = (appName = "FletBox App", appId = "com.fletbox.app") => {
-  const slug = appName
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 40) || "fletbox-app";
-  return `name: Build ${appName}
-
-# One push (or manual trigger) fans out into three parallel jobs:
-#   web     -> bundles the PWA; publishes to GitHub Pages ONLY on release
-#              tags (v*), which is what triggers OTA self-updates
-#   android -> compiles a debug APK and uploads it as an artifact
-#   ios     -> compiles a simulator .app and uploads it as an artifact
-# All three run at the same time on separate runners.
+export const githubWorkflow = (appName = "FletBox App") => `name: Deploy ${appName}
+
+# Publishes the PWA to GitHub Pages. Every push to main (and every manual run)
+# builds a fresh site, and only the deploy job can touch Pages, so a broken
+# bundle never replaces the live one. Android and iOS are NOT here: they live in
+# build-native.yml and run only when you start them, because a macOS runner is
+# not free.
+#
+# One consequence to know about: this Pages site is also what an installed app
+# polls for an OTA update (www/config.json), and the app compares the bundle
+# hash, not the version. So the manifest is left out of every build whose commit
+# carries no \`v*\` tag (see "Ship the update feed only when this commit is a
+# release" below): the site is live on every push, while installed apps keep
+# running the last \`flet-box release\`.
+#
+# Publishing a release: push main, then \`git tag -a v1.2.3 && git push origin
+# v1.2.3\`, then Actions -> this workflow -> Run workflow. The manual run deploys
+# the tagged commit, and it is the run that puts config.json on the site. The tag
+# itself cannot deploy: GitHub refuses Pages deployments that start from a tag.
+
 on:
   push:
     branches: [ main ]
-    tags: [ 'v*' ]
-  pull_request:
-    branches: [ main ]
+    # Deliberately NO tags: trigger. The github-pages environment only accepts
+    # deployments from the default branch, so a run that starts from a tag fails
+    # at the deploy job with "Tag v1.0.0 is not allowed to deploy to github-pages
+    # due to environment protection rules". A release is therefore made by
+    # pushing main and then running this workflow again, by hand, once the tag
+    # exists: that run is on main, and it sees the tag on HEAD.
   workflow_dispatch:
 
-# Cancel superseded runs on the same branch to save Actions minutes.
+# The deploy job needs Pages write access; it is declared once, for the file.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and the latest queued. Do NOT cancel in-progress: a production
+# deployment is allowed to finish, because the site that is live while it runs is
+# the previous one, and a cancelled deploy leaves Pages holding a half-written
+# artifact.
 concurrency:
-  group: \${{ github.workflow }}-\${{ github.ref }}
-  cancel-in-progress: true
+  group: pages
+  cancel-in-progress: false
 
-# The generated app depends on the public \`flet-box\` npm package. If you are
-# developing against a local copy, publish it (or vendor it) before these jobs
-# can \`npm install\` it. package-lock.json is gitignored, so we use npm install.
+# The generated app depends on the public \`flet-box\` npm package. If you
+# develop against a local copy, publish it (or vendor it) before these jobs can
+# \`npm install\` it. package-lock.json is gitignored, so we use npm install.
 
 jobs:
-  # ---------- WEB: bundle + GitHub Pages preview ----------
-  web:
-    name: Web (Pages)
+  # ---------- BUILD: check, bundle, upload. Nothing here reaches Pages. ----------
+  build:
+    name: Build site
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: \${{ steps.deployment.outputs.page_url }}
     steps:
       - uses: actions/checkout@v5
+        with:
+          # The release decision below reads the tags pointing at this commit, and
+          # a shallow checkout of one commit does not fetch them by itself.
+          fetch-tags: true
+
+      # Registers the Pages integration for this run and reports the site's base
+      # path, which is /<repo>/ for a project site and empty on a custom domain.
+      # It belongs in the build job, before the artifact is uploaded.
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
 
       - uses: actions/setup-node@v5
         with:
+          # 22 is the current LTS. 20 is EOL, and the runner says so on every
+          # build of a generated app.
           node-version: 22
 
       - name: Install dependencies
@@ -1183,28 +1212,103 @@ jobs:
       - name: Check app API usage (npm run check)
         run: npm run check
 
-      - name: Bundle web app (flet-box createBundle www)
+      - name: Build site (flet-box createBundle www)
         run: npm run build
 
-      # Pages is the OTA update source (www/config.json), so it is published
-      # ONLY for release tags (v*) created by \`flet-box release\`. Ordinary
-      # pushes still build (to catch breakage in CI) but never publish an
-      # update, so test builds cannot reach installed apps.
+      # Printed before the deploy, because this is the address the whole workflow
+      # is about, and because a missing Pages setting otherwise shows up as a
+      # green run with no site: Pages lower-cases the owner, hence the tr.
+      - name: Where this lives
+        run: |
+          owner=$(printf '%s' "$GITHUB_REPOSITORY_OWNER" | tr '[:upper:]' '[:lower:]')
+          repo=\${GITHUB_REPOSITORY#*/}
+          echo "  site:    https://$owner.github.io/$repo/"
+          echo "  version: $(node -p "require('./package.json').version")"
+          echo "  If a green run leaves that 404, the source is wrong:"
+          echo "  Settings -> Pages -> Build and deployment -> Source: GitHub Actions"
+
+      # www/config.json is the OTA manifest: an installed app fetches it and
+      # compares its \`hash\` with the bundle it is running, so publishing it from
+      # an ordinary push would offer that unfinished build to every device that
+      # checks for updates. Dropping the file makes the poll fail as "not
+      # deployed yet" (see bin/ota/loader.js), which is the behaviour wanted:
+      # the site is live for reading, the release feed stays on tagged builds.
+      #
+      # The decision reads the commit, not the ref: a tag push cannot deploy (the
+      # environment refuses it), so \`github.ref\` is always a branch here. To
+      # publish a release, push main, tag that commit, then run this workflow by
+      # hand from Actions - the manual run is on main and sees the tag.
+      - name: Ship the update feed only when this commit is a release
+        run: |
+          tag=$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)
+          if [ -n "$tag" ]; then
+            echo "  ota:     $tag is on this commit: config.json ships, installed apps may update"
+          else
+            rm -f www/config.json
+            echo "  ota:     web-only: no v* tag on $(git rev-parse --short HEAD), manifest left out"
+          fi
+
       - name: Upload Pages artifact
-        if: startsWith(github.ref, 'refs/tags/v')
         uses: actions/upload-pages-artifact@v5
         with:
           path: www
 
-      # Enable Pages first: Settings -> Pages -> Source = "GitHub Actions".
+  # ---------- DEPLOY: the only job with a path to Pages ----------
+  deploy:
+    name: Deploy to Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        if: startsWith(github.ref, 'refs/tags/v')
         uses: actions/deploy-pages@v5
 
+      # The address in the job log and as a run annotation, so it is readable
+      # from the workflow list without opening anything.
+      - name: Published
+        run: |
+          echo "  live at: \${{ steps.deployment.outputs.page_url }}"
+          echo "::notice title=Site published to GitHub Pages::\${{ steps.deployment.outputs.page_url }}"
+`;
+
+// Native builds: the same two jobs, but they run ONLY when started by hand from
+// Actions -> Run workflow, with a choice of platform. A push never pays for a
+// macOS runner, and `flet-box build android|ios` already covers a local build.
+export const nativeWorkflow = (appName = "FletBox App") => {
+  const slug = appName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40) || "fletbox-app";
+  return `name: Build ${appName} — native (manual)
+
+# Nothing in here runs on a push. Start it by hand: Actions -> "${appName} —
+# native (manual)" -> Run workflow, then pick the platform. Each job bundles the
+# web first, because that bundle is what Capacitor copies into the app.
+
+on:
+  workflow_dispatch:
+    inputs:
+      platform:
+        description: "What to build"
+        type: choice
+        options:
+          - android
+          - ios
+          - both
+        default: android
+
+permissions:
+  contents: read
+
+jobs:
   # ---------- ANDROID: debug APK ----------
   android:
     name: Android (APK)
+    if: inputs.platform == 'android' || inputs.platform == 'both'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
@@ -1246,9 +1350,19 @@ jobs:
           path: android/app/build/outputs/apk/debug/app-debug.apk
           if-no-files-found: error
 
+      # An artifact has no public URL: it is on the run page, and this prints
+      # which run. The debug APK installs as it is; a release one would have to be
+      # signed with your own keystore first.
+      - name: Where the APK is
+        run: |
+          echo "  artifact: ${slug}-android-debug"
+          echo "  download: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          echo "::notice title=APK ready::${slug}-android-debug, on this run page"
+
   # ---------- iOS: simulator build ----------
   ios:
     name: iOS (simulator)
+    if: inputs.platform == 'ios' || inputs.platform == 'both'
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v5
@@ -1295,6 +1409,12 @@ jobs:
           name: ${slug}-ios-simulator
           path: ios/App/build/Build/Products/Debug-iphonesimulator/App.app
           if-no-files-found: error
+
+      - name: Where the build is
+        run: |
+          echo "  artifact: ${slug}-ios-simulator"
+          echo "  download: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          echo "::notice title=Simulator build ready::${slug}-ios-simulator, on this run page"
 `;
 };
 
@@ -1340,6 +1460,8 @@ framework from scratch:
   Claude Code and Cursor.
 - \`.fletbox/api/cheatsheet.md\` — every widget and its real props, generated from the
   installed package. This is the lookup an agent reads instead of the framework.
+- \`.fletbox/api/api.json\` — the same surface as data: per prop its engine target,
+  default, aliases and a \`sample\` value the types prove works. Write calls from this.
 - \`.fletbox/memory/\` — notes the agent keeps between sessions, so it does not
   rediscover the same thing twice.
 - \`scripts/check-app.mjs\` — the gate that catches hallucinated APIs.
@@ -1348,10 +1470,16 @@ framework from scratch:
 npm run check                      # scan src/ for invented widgets, props, imports
 npm run check -- --props Button    # print the real props of one widget
 npm run check -- --list            # print every public export
+npm run fix                        # rewrite typos it can prove (imports, prop keys)
+npm run api                        # regenerate .fletbox/api/api.json and api.md
+flet-box unpack Button             # each prop, where it really goes, and what is dead
+flet-box unpack Button --example   # a paste-ready call using only verified props
+flet-box unpack Modal --diff       # where types, engine, docs and code disagree
 \`\`\`
 
 \`npm run check\` exits non-zero on a real error and also runs in CI. If you upgrade
-\`flet-box\`, regenerate the cheatsheet with \`flet-box check-api --emit-api\`.
+\`flet-box\`, regenerate the cheatsheet with \`flet-box check-api --emit-api\` and the
+machine-readable surface with \`npm run api\`.
 
 ## Android
 
@@ -1414,29 +1542,45 @@ CORS configuration and use HTTPS for the remote service.
 
 ## Continuous Integration (GitHub Actions)
 
-Every project ships with \`.github/workflows/build.yml\`. Once the repo is on
-GitHub, each push to \`main\` (or a manual **Run workflow**) fans out into three
-parallel jobs:
+Two workflow files ship with the project, and they answer to different triggers:
 
-- **web** — bundles the app into \`www/\` and deploys it to **GitHub Pages** so you
-  can view it in a browser.
-- **android** — compiles a debug **APK** and uploads it as a run artifact.
-- **ios** — compiles an unsigned **simulator .app** and uploads it as an artifact.
+- \`.github/workflows/build.yml\` — **the web, automatic**. Every push to \`main\`
+  (and every \`v*\` tag, and a manual run) builds \`www/\` and publishes it to
+  **GitHub Pages**, in two jobs: **Build site** checks the app, bundles it and
+  uploads the result; **Deploy to Pages** is the only job that can replace the
+  live site, so a bundle that fails to build leaves the current one running.
+- \`.github/workflows/build-native.yml\` — **Android and iOS, manual only**. Nothing
+  runs on a push. Open **Actions → "… — native (manual)" → Run workflow** and pick
+  \`android\`, \`ios\` or \`both\`. Each job uploads its build as a run artifact and
+  prints the artifact name and the run URL in its own log.
 
-### Run it on the web (one-time setup)
+### Publish the web (one-time setup)
 
 1. Push this project to a GitHub repository.
 2. Open **Settings → Pages** in that repo.
-3. Set **Source** to **GitHub Actions** (not "Deploy from a branch").
-4. Push to \`main\`, or open the **Actions** tab and click **Run workflow**.
+3. Set **Source** to **GitHub Actions** (not "Deploy from a branch"). Skip this
+   and the deploy step fails on every push.
+4. Push. The **Where this lives** step prints the address before the deploy runs,
+   and the **Published** step prints it again as a run annotation, so you do not
+   have to hunt for the environment box under the job.
 
 The site goes live at \`https://<your-user>.github.io/<repo-name>/\`. That is a
 sub-path, so \`index.html\` uses relative asset paths and works without changes.
 
+**Why a push does not update anyone's app:** this same address is the OTA feed
+installed apps poll, and the update check compares bundle **hashes**, not version
+numbers. So the workflow leaves \`www/config.json\` out of every artifact that is
+not a \`v*\` tag: the site is live for reading, while a device keeps running the
+last \`flet-box release\` until a tag publishes a manifest. The **Where this
+lives** step prints which of the two a given run was. Cut a release with
+\`flet-box release --patch --push\` when the app is worth updating.
+
 ### Download the mobile artifacts
 
-Open the workflow run in the **Actions** tab; the Android APK and the iOS
-\`.app\` are listed under **Artifacts** at the bottom of the run summary.
+Start it by hand — **Actions → "… — native (manual)" → Run workflow**, pick a
+platform — and open that run: the Android APK and the iOS \`.app\` are listed
+under **Artifacts** at the bottom of the run summary, and the job's own log prints
+the artifact name plus the URL of the run it belongs to.
 
 > The workflow installs dependencies with \`npm install\`, which resolves the
 > \`flet-box\` package from npm. If you develop against a local copy of the
@@ -1514,10 +1658,19 @@ updates:
 - Replace \`TU-USUARIO\` with your GitHub username and \`TU-REPO\` with the
   repository name, or set \`update.url\` to any HTTPS host that serves your
   \`config.json\` + bundle.
-- Enable GitHub Pages: **Settings → Pages → Source: GitHub Actions**.
+- Enable GitHub Pages: **Settings → Pages → Source: GitHub Actions**. Without
+  that the deploy step is green and no site exists.
 - Cut a release with \`flet-box release --push\` (bumps the version, rebuilds
   \`www/\`, commits and tags \`vX.Y.Z\`). CI then deploys \`www/\` and installed
   apps self-update the next time they open.
+- A plain \`git push\` also deploys \`www/\` — that is the preview, and the job
+  prints the address. It never publishes \`www/config.json\`, because that file
+  is the update feed and the app compares bundle **hashes**: without it an
+  installed app finds no manifest and stays on the last release. Do not "fix"
+  that gate; the release tag is the only thing that should reach users.
+- Android and iOS are not built on a push. Start
+  \`.github/workflows/build-native.yml\` from **Actions → Run workflow** and pick
+  \`android\`, \`ios\` or \`both\`.
 - The update URL is also reflected in \`www/config.json\` after \`flet-box
   createBundle www\`; it is baked into Android/iOS builds at \`cap sync\` time.
 - Only web files are updated OTA. Native changes (plugins, permissions,
@@ -1896,7 +2049,8 @@ export const agentsMd = (appName, template, version) =>
     '',
     'This file is the contract. Read it before writing any code in this project.',
     'You do **not** need to read the whole framework to work here — sections 1 to 3',
-    'tell you where the authoritative answers live, and the checker in section 4',
+    'tell you where the authoritative answers live, the design system in section 4',
+    'fixes every size and color you may use, and the checker in section 5',
     'proves you right or wrong in seconds.',
     '',
     '## 1. The API is a fact, not a guess',
@@ -1907,8 +2061,11 @@ export const agentsMd = (appName, template, version) =>
     '| --- | --- |',
     '| Which widgets exist and which props each accepts | `.fletbox/api/cheatsheet.md` (generated, covers every widget) |',
     '| Everything for one widget | `npm run check -- --props <Widget>` |',
+    '| Whether a prop actually reaches the DOM, or is typed but dead | `flet-box unpack <Widget>` |',
+    '| A call that is safe to paste | `flet-box unpack <Widget> --example` |',
     '| Prose, types and a worked example | `node_modules/flet-box/docs/widget/<Widget>.md` |',
     '| Every public export of the package | `npm run check -- --list` |',
+    '| The whole surface as data, to build calls from | `.fletbox/api/api.json` |',
     '',
     '**If a name is not in those files, it does not exist.** A prop that silently',
     'does nothing is worse than a compile error: it renders as a broken layout and',
@@ -1917,6 +2074,10 @@ export const agentsMd = (appName, template, version) =>
     '- Do not edit `node_modules/flet-box`. It is a dependency, not source.',
     '- The cheatsheet is generated output. Regenerate it with',
     '  `flet-box check-api --emit-api` after upgrading the package; never hand-edit it.',
+    '- `.fletbox/api/api.json` and `api.md` are generated the same way:',
+    '  `npm run api`. They carry one entry per prop with its engine target, default,',
+    '  aliases and a `sample` value, so a call can be written from data instead of',
+    '  memory.',
     '',
     '## 2. FletBox syntax only — no other framework',
     '',
@@ -2006,7 +2167,62 @@ export const agentsMd = (appName, template, version) =>
     'broken, prove it with a minimal repro and record the finding in memory** — do',
     'not work around it silently.',
     '',
-    '## 4. Verification loop (required)',
+    '## 4. Design system — one scale, three colors',
+    '',
+    'A screen is designed, not decorated. Every size and every color on this app',
+    'comes from the two lists below. A value outside them is a bug you have to',
+    'justify, and `padding: 13` or `#4f46e5` written by hand is the usual sign a',
+    'screen drifted away from the rest.',
+    '',
+    '**Color: three roles, no more.**',
+    '',
+    '| Role | Token | Where it may appear |',
+    '| --- | --- | --- |',
+    '| Brand | `colors.primary` | the one action the screen asks for: primary button, active tab, focus ring, links |',
+    '| Emphasis | `colors.secondary` | a deliberate second voice: gradients, badges, a highlighted stat |',
+    '| Feedback | `colors.success` / `colors.warning` / `colors.danger` | status only — never as decoration |',
+    '',
+    'Everything else is neutral: `colors.background`, `colors.surface`,',
+    '`colors.card`, `colors.text`, `colors.textSecondary`, `colors.textDisabled`,',
+    '`colors.border`, `colors.divider`, plus the `gray50`…`gray900` ramp. Rules:',
+    '',
+    '- A screen uses **one** brand color. Two accent colors competing on one view',
+    '  means one of them is wrong.',
+    '- Never type a hex or `rgb()` literal. If a token is missing, add it to a',
+    '  `theme.js` in this app that re-exports `colors` — do not scatter the value.',
+    '- Text on a dark fill is white; hierarchy comes from opacity',
+    '  (`rgba(255,255,255,.72)`), not from a second color.',
+    '- `error` ≡ `danger` and `*Bg` variants exist for alert fills; use the pair',
+    '  (`colors.danger` + `colors.errorBg`), not a hand-mixed tint.',
+    '',
+    '**Space and type: an 8-based scale.** Use these numbers and nothing between',
+    'them. They are plain props (`padding`, `gap`, `margin`, `width`, `height`,',
+    '`size`, `radius`) — the factory takes the number, no unit and no `px` string.',
+    '',
+    '```',
+    'spacing   4  ·  hairline, icon inset',
+    '          8  ·  tight gaps, chip padding',
+    '         12  ·  control padding (input/button height − text)',
+    '         16  ·  default card padding, section gap, screen gutter',
+    '         18  ·  card-to-card rhythm on a dense grid',
+    '         24  ·  between sections',
+    '         32  ·  between page blocks',
+    '         48  ·  hero spacing',
+    'radius     4 / 8 / 12 / 16 / 999 (pill)',
+    'type      12 caption · 14 body-small · 16 body · 18 subtitle · 24 title · 32 headline',
+    'weight    400 body · 500 label · 600 title · 700 headline',
+    'line-height  1.5 body · 1.2 heading',
+    '```',
+    '',
+    '- Padding inside a card is `16`; the gap between cards is `16` or `24`. Never',
+    '  mix the two on the same list.',
+    '- One text size per element, one weight per role. If a label and its value are',
+    '  the same size, the hierarchy is carried by color, not by a fourth size.',
+    '- Tap targets are at least `40` on a side; get there with `height`, not padding.',
+    '- `useState` bindings, `flex` and `gap` do the layout. Reach for an absolute',
+    '  offset only for overlays, and use `stackPosition` rather than raw coordinates.',
+    '',
+    '## 5. Verification loop (required)',
     '',
     'After every edit, before you say a task is done:',
     '',
@@ -2021,7 +2237,14 @@ export const agentsMd = (appName, template, version) =>
     'It reads the installed package, so it is always in sync with what runs. A',
     'warning is allowed to stay only when you can justify it in one sentence.',
     '',
-    '## 5. Memory — do not relearn the same thing',
+    'When the error is a mistyped name, `npm run fix` rewrites it for you — a',
+    'relative path that does not resolve, a name the target module never exports,',
+    'an identifier used without its `import`, and a prop key the API does not know',
+    '(`chilldren` → `children`, `bgColr` → `bgColor`). It only rewrites when exactly',
+    'one real name is close enough; anything ambiguous is printed untouched for you',
+    'to decide. Run `npm run check` again after it, and read the diff.',
+    '',
+    '## 6. Memory — do not relearn the same thing',
     '',
     'At the start of every session read `.fletbox/memory/MEMORY.md` and any entry it',
     'points at. That is how this agent remembers the framework between chats instead',
@@ -2036,13 +2259,18 @@ export const agentsMd = (appName, template, version) =>
     '  to be wrong rather than appending a correction beside it.',
     '- Commit memory files with the code change they describe.',
     '',
-    '## 6. Commands',
+    '## 7. Commands',
     '',
     '| Command | What it does |',
     '| --- | --- |',
     '| `npm run dev` | static dev server on port 8000 |',
     '| `npm run check` | anti-hallucination gate over `src/` |',
+    '| `npm run fix` | rewrite mistyped imports and prop names it can prove |',
     '| `npm run check -- --props Button` | print the real props of a widget |',
+    '| `flet-box unpack Button` | everything Button accepts **and that actually works** |',
+    '| `flet-box unpack Button --example` | a paste-ready call using only live props |',
+    '| `flet-box unpack Button --diff` | doc vs code gaps: dead, invented, undocumented |',
+    '| `npm run api` | rebuild `.fletbox/api/api.json` + `api.md` for the whole surface |',
     '| `npm run build` | esbuild bundle into `dist/` |',
     '| `flet-box build android` / `ios` | Capacitor native build |',
     '| `flet-box run-native android` | compile and launch on device/emulator |',
@@ -2060,6 +2288,16 @@ export const claudeMd = () =>
     'follow it exactly — FletBox syntax only, real props only, `npm run check` after',
     'every edit.',
     '',
+    'Two shortcuts replace guessing:',
+    '',
+    '- `flet-box unpack <Widget>` prints every prop the widget really honors, with',
+    '  its type, default and engine target. `--example` gives a call you can paste,',
+    '  `--diff` lists the props that are documented but dead or used but undeclared.',
+    '  `.fletbox/api/api.json` is the same surface for all widgets, as data.',
+    '- Design is fixed, not improvised: one brand color per screen from the `colors`',
+    '  tokens (never a hex literal), and sizes only from the 8-based scale —',
+    '  4 · 8 · 12 · 16 · 18 · 24 · 32 · 48. AGENTS.md §4 has the full table.',
+    '',
     'Memory: read `.fletbox/memory/MEMORY.md` before working, and write new entries',
     'there when you learn something the next session should not rediscover.',
     '',
@@ -2079,8 +2317,13 @@ export const cursorRules = () =>
     '- Widgets are function calls returning an element: `Text({ text: "Hi", size: 18 })`.',
     '  No JSX, no positional args, no Flutter/Vue/Svelte/React syntax or imports.',
     '- Before using a widget or prop you have not just seen in',
-    '  `.fletbox/api/cheatsheet.md`, look it up: `npm run check -- --props <Widget>`.',
-    '  If it is not listed, it does not exist — do not invent it.',
+    '  `.fletbox/api/cheatsheet.md`, look it up: `flet-box unpack <Widget>` (or',
+    '  `npm run check -- --props <Widget>`). If it is not listed, it does not exist —',
+    '  do not invent it. `unpack --example` prints a call that is safe to paste.',
+    '- Design rules: one brand color per screen, taken from the `colors` tokens —',
+    '  never a hex literal. Sizes come from the 8-based scale only:',
+    '  4 · 8 · 12 · 16 · 18 · 24 · 32 · 48 spacing, radii 4/8/12/16/999, type',
+    '  12/14/16/18/24/32. See AGENTS.md §4.',
     '- Run `npm run check` after every change and fix what it reports.',
     '- Check `.fletbox/memory/MEMORY.md` at session start; record new non-obvious',
     '  findings there instead of re-deriving them.',

package/docs/cli/README.md

@@ -423,8 +423,86 @@ Capacitor template with different slots keeps working. It:
 The script is idempotent: running it twice leaves identical files. The brand
 color `#1a1a2e` is defined at the top of the script.
 
+## Convert asset images to PNG
+
+Screens need PNG, and a `logo.jpg` dropped into `assets/` still works — until an
+Android or iOS build asks for a format the source photo cannot give it.
+`flet-box to-png` converts a folder of images to PNG using nothing but Node
+itself, so it works on a machine where no image library is installed.
+
+```bash
+flet-box to-png                 # converts ./assets, ./public/assets or ./src/assets
+flet-box to-png assets          # converts one folder
+flet-box to-png assets --dry-run
+```
+
+It recognises a file by its leading bytes, never by its extension, so a
+`logo.jpg` that is really a PNG is treated as the PNG it is. What it converts:
+
+| Format | Notes |
+| --- | --- |
+| JPEG | Baseline and extended sequential, greyscale or colour, any sampling factor (4:4:4, 4:2:2, 4:2:0, 4:1:1), restart intervals. Progressive, arithmetic-coded, lossless, 12-bit and CMYK files are refused with the reason. |
+| PNG | Colour types grey/RGB/palette/grey+alpha/RGBA at 1–16 bits, all five row filters, `tRNS` transparency. Already a PNG, so it is left alone unless you ask with `--optimize` or `--force`. Interlaced (Adam7) files are refused. |
+| GIF | First frame, with or without interlacing and transparency. An animated file converts with a note saying how many frames were dropped. |
+| BMP | Uncompressed 1/4/8/24/32-bit, top-down or bottom-up. Run-length (RLE) files are refused. |
+
+These need a codec or a rasteriser that a zero-dependency package cannot carry,
+so they are reported as declined rather than quietly skipped: WebP, AVIF/HEIF,
+TIFF, ICO and SVG.
+
+Nothing is overwritten. `assets/logo.jpg` becomes `assets/logo.png` beside it and
+the source stays; if `logo.png` already exists the file is kept and reported as a
+name clash, because that collision usually means someone already converted it by
+hand. `--replace` deletes each source, and only after the PNG it replaces has been
+read back and checked:
+
+```bash
+flet-box to-png assets --out build/img   # write the PNGs somewhere else
+flet-box to-png assets --force           # replace an existing logo.png
+flet-box to-png assets --replace         # delete the source once its PNG is verified
+flet-box to-png assets --optimize        # re-pack the PNGs already in the folder
+flet-box to-png assets --flat            # top level only, no sub-folders
+```
+
+The summary counts the outcomes apart — converted, declined, already a PNG, name
+clashes, and with `--optimize` also optimized, already optimal and the bytes saved
+— and only a file whose bytes could not be decoded counts as a failure, which is
+the one case that exits non-zero.
+
+### The PNG it writes is the smallest one that holds the picture
+
+A converted file is not written in one fixed layout. The writer looks at the
+pixels first and keeps whichever arrangement is smallest: a palette when the
+frame really does hold 256 colours or fewer (an exact address per pixel, not a
+quantisation), greyscale when every channel already agrees, three bytes per pixel
+when no pixel uses alpha. It then deflates the five row filters and keeps the
+shortest result. Nothing is approximated, so the file reads back as the same
+picture — and the command checks that before it calls the conversion a success.
+
+`--optimize` asks the same question about files that already are PNG, which is
+how a hand-made asset gets its turn:
+
+```bash
+flet-box to-png assets --optimize
+```
+
+It replaces a PNG only when the new bytes are smaller *and* every pixel matches,
+so running it twice is free: the second pass reports each file as already optimal
+and touches nothing. The repo's own icons lose 13 KB on the 1024 maskable and 3 KB
+on the logo, and the other four come back as already optimal. A 16-bit PNG is left
+alone either way — rewriting it would trade someone else's bit depth for a smaller
+file, and "smaller without losing quality" does not cover that.
+
+What this cannot do is make a photograph small. PNG stores every pixel, and a
+camera JPEG has already thrown most of them away, so the PNG of a photo comes out
+three to four times the file it came from (a 3.5 MB picture writes as 12 MB). The
+command converts it anyway and says so in the report: keep the JPEG — or a WebP
+from a tool that carries a codec — for that picture, and let `to-png` do the flat
+art, the logos and the icons.
+
 ## Command reference
 
+
 | Command | What it does |
 | --- | --- |
 | `flet-box create <name>` | Creates a default project. |
@@ -447,6 +525,10 @@ color `#1a1a2e` is defined at the top of the script.
 | `flet-box run-native <android\|ios>` | Compiles and launches the app on an emulator/simulator or connected device. |
 | `flet-box run-native <android\|ios> --device` | Forces a physical device instead of the emulator. |
 | `flet-box run-native <android\|ios> --livereload` | Launches the app with hot reload on the device. |
+| `flet-box to-png [dir]` | Converts JPEG, GIF, BMP and non-PNG-precision images in a folder to PNG. |
+| `flet-box to-png --dry-run` | Reports what would happen, writes nothing. |
+| `flet-box to-png --replace` | Deletes each source after its PNG was written and read back. |
+| `flet-box to-png --optimize` | Re-packs the PNGs already in the folder, and only when that makes them smaller. |
 | `flet-box pkg` | Opens the package manager. |
 | `flet-box --version` | Shows the CLI version. |
 | `flet-box --help` | Shows the command list. |