docs: a FAQ that answers the non-JavaScript question

CHANGELOG.md

@@ -10,6 +10,13 @@ Documentation only. No code change.
   verified to resolve: Tests, npm version, npm downloads, MIT.
 - **Added a `dependencies-0` badge.** It is the shortest true thing about this package
   and worth stating on the tin.
+- **New FAQ**, replacing the one dropped in 0.3.0. That FAQ was written pre-AI and
+  asked React questions — Context API, class components, Redux comparisons — about a
+  runtime this package no longer has. The new one leads with the question the old
+  framing obscured: whether this works with frontends that are not JavaScript. It
+  does, and the answer says how, including the one honest limit (`scan` reads
+  React/Next source only; every other stack builds its manifest via `rainfall
+  prompt` and an assistant, which is the recommended path on every stack anyway).
 - Republished so npmjs.com serves the current README. npm renders the README from the
   published tarball, so a docs change only reaches that page on a publish — which is
   why this is a version bump rather than a commit.

README.md

@@ -1,3 +1,8 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Morf-Engineering-Inc/rainfalljs/main/assets/logo.png"
+       alt="RainfallJS" width="150">
+</p>
+
 # RainfallJS
 
 [![Tests](https://github.com/Morf-Engineering-Inc/rainfalljs/actions/workflows/test.yml/badge.svg)](https://github.com/Morf-Engineering-Inc/rainfalljs/actions/workflows/test.yml)
@@ -283,6 +288,138 @@ See [`RECOMMENDATION.md`](RECOMMENDATION.md) for the rationale and
 
 ---
 
+## The worked demo — real numbers you can re-run
+
+[`examples/fintech-demo/`](examples/fintech-demo/) is a complete Next.js finance app —
+accounts, transactions, budgets, net worth, insights — with a `rainfall.json` describing
+it. It exists so the token claim is a measurement rather than a promise.
+
+[`TOKENS.md`](examples/fintech-demo/TOKENS.md) is the output of `rainfall report` against
+those files, not an estimate:
+
+```
+Condensed digest:            ~726 tokens   (what an AI reads instead)
+Mapped source files:         ~3631 tokens  (16 files the manifest describes)
+All project source files:    ~3699 tokens  (17 files, blind-exploration ceiling)
+
+Savings vs reading mapped files:   5.0x fewer tokens per session
+Savings vs exploring the project:  5.1x fewer tokens per session
+```
+
+Scoped to one work item — everything an agent needs to change the add-transaction form
+and nothing else:
+
+```
+~233 tokens focused on "form.transactions.add"   (full digest: ~726)
+```
+
+Roughly **16x** less than reading the project, for a task-sized context.
+
+Re-run it yourself:
+
+```bash
+cd examples/fintech-demo
+npx @morf_engineering/rainfalljs report
+npx @morf_engineering/rainfalljs condense --focus form.transactions.add
+```
+
+[`GROK_PROMPT.md`](examples/fintech-demo/GROK_PROMPT.md) is the prompt used to test
+whether an agent given only the digest can make a correct change — the part that decides
+whether the saving is real or just smaller.
+
+> **Read the numbers honestly.** They compare a digest against reading source files, on
+> one small app. A larger codebase moves the ratio up, and a task that genuinely needs
+> the source still needs the source. The digest tells an agent *where to look*; it does
+> not replace looking.
+
+---
+
+## FAQ
+
+### Does this work with frontends that aren't JavaScript?
+
+**Yes — that is the design, not a workaround.** The two things this tool produces are
+JSON files, not JavaScript:
+
+- **`rainfall.json`** — your map. Entities, endpoints, components, screens, flows.
+- **[`schema/components.json`](schema/components.json)** — the component-shape
+  catalogue: what each UI component type accepts as data and what props it produces.
+
+A SwiftUI, Flutter, Blazor, Django, Rails, Android or Unity frontend reads those the
+same way anything reads JSON, and implements the shapes natively. `rainfall components
+--json` prints the catalogue; `rainfall condense` prints the map. Neither output
+contains a line of JavaScript.
+
+The JS mapper (`/mapper`) is a convenience for projects that happen to be in JS. It is
+one implementation of the catalogue, not the definition of it.
+
+### So what actually requires Node?
+
+Only the CLI itself — it ships on npm, so running `rainfall validate` or `condense`
+needs Node on the machine or in CI. That is a build-time dependency, in the same way a
+linter is. **Nothing at runtime, in any language**, and the artifacts it produces
+outlive it: `rainfall.json` is a plain file you could hand-write and read with
+`json.load`.
+
+If you want the check in a non-Node CI, one step with `npx` covers it:
+
+```yaml
+- run: npx @morf_engineering/rainfalljs validate
+```
+
+### Will `rainfall scan` understand my Swift / Python / Go project?
+
+**No — and this is the honest limit.** `scan` reads React and Next.js source to seed a
+manifest. On any other stack it will find nothing useful.
+
+That matters less than it sounds, because `scan` only ever produces the skeleton. The
+parts worth having — entity fields, response shapes, which component needs which
+endpoint, the flows — require understanding the code, which is why the recommended
+path on *every* stack is:
+
+```bash
+npx @morf_engineering/rainfalljs prompt
+```
+
+and hand the output to an AI assistant, which reads your models and handlers and writes
+the manifest. That works the same whether the code is TypeScript or Kotlin.
+
+### Does my backend have to be JavaScript?
+
+No. Endpoints are **declared**, not introspected. An entry like
+
+```json
+{ "id": "API-001", "method": "GET", "path": "/api/score", "reads": ["User.goals"] }
+```
+
+says nothing about what serves it — Django, Rails, Go, a Lambda, or a mainframe behind a
+gateway. The Data Map's `access` field goes further and records the key expression
+behind an endpoint, which is usually a database concern with no language at all.
+
+### Isn't this just OpenAPI?
+
+They answer different questions and compose well. OpenAPI describes **the API**: routes,
+payloads, status codes. It does not say which screen calls a route, which component
+breaks if a field is renamed, or which business requirement the route exists to serve.
+
+This maps the consumers: requirement → endpoint → component → screen. Keep your OpenAPI
+spec; point the manifest's endpoint ids at it.
+
+### Is this only useful if I use AI?
+
+No. The token saving is the headline because it is measurable, but `validate` earns its
+place without an agent anywhere: it fails the build when a screen references an endpoint
+nobody declares, when an endpoint has no consumer, or when a requirement has nothing
+serving it. That is a stale-architecture-doc problem that has existed far longer than
+coding assistants have.
+
+### Do I have to use the component mapper?
+
+No. The map and the mapper are independent. Plenty of projects will want
+`rainfall.json` and `validate` in CI and nothing else.
+
+---
+
 ## Upgrading from 0.2.x
 
 **0.3.0 removes the React runtime.** `DataProvider`, `useData`, `withData`,

examples/fintech-demo/TOKENS.md

@@ -9,22 +9,32 @@ use the standard ~4 characters/token heuristic.
 ```
 Rainfall tokens-saved report — fintrack
 
-Condensed digest:            ~726 tokens   (what an AI reads instead)
+Condensed digest:            ~726 tokens  (what an AI reads instead)
 Mapped source files:         ~3631 tokens  (16 files the manifest describes)
-All project source files:    ~4977 tokens  (19 files, blind-exploration ceiling)
+All project source files:    ~3699 tokens  (17 files, blind-exploration ceiling)
 
 Savings vs reading mapped files:  5.0x fewer tokens per session
-Savings vs exploring the project: 6.9x fewer tokens per session
+Savings vs exploring the project: 5.1x fewer tokens per session
+
+Estimates use ~4 characters per token. Every AI session pays the reading
+cost again from scratch; the digest cost is all it needs to pay instead.
 ```
 
 Scoped to a single work item (what an agent needs to modify the add-transaction
 form and everything it touches):
 
 ```
-~233 tokens focused on "form.transactions.add"  (full digest: ~726)
+F002 add-transaction: ui:form.transactions.add → api:API-003 → entity:Transaction → entity:Account → api:API-002 → ui:table.transactions.list
 ```
 
-That's **~21x** less than reading the whole project — for a task-sized context.
+That is roughly **16x** less than reading the whole project, for a task-sized context.
+
+**Regenerate these numbers, do not trust them.** They are the literal output of
+`npx @morf_engineering/rainfalljs report` in this directory, and they moved once
+already: an earlier version of this file reported 19 files / ~4977 tokens and a 6.9x
+exploration saving, counting `.gitignore` and a `.claude/` skill file as project source.
+The walker excludes dotfiles now, which is the more honest count — and the multiple
+dropped accordingly. A measurement nobody re-runs becomes a claim.
 
 ## How to read these numbers honestly