1# lofi developer documentation23These guides are for developers building an application from the `@nzip/lofi` generated template.4They describe the checked-out package version and its generated project—not the older prototype5sketches under `docs/spikes/`.67## Start here89Work through the guides in order; each builds on the project state the previous one leaves behind.1011| Step | Guide | What you do |12| ---- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |13| 1 | [Getting started](getting-started.md) | Scaffold an app, verify local persistence, and identify the files you are expected to change. |14| 2 | [Data and UI](data-and-ui.md) | Connect a Jazz table to a typed Preact hook and island. |15| 3 | [Permissions](permissions.md) | Understand and change the starter's owner-only access policy. |16| 4 | [Sync and recovery](sync-and-recovery.md) | Provision managed sync and understand the account lifecycle. |17| 5 | [Testing](testing.md) | Run fast tests and the opt-in two-client offline convergence example. |18| 6 | [Deployment](deployment.md) | Build, preview, customize, and host the static PWA. |19| 7 | [Application-origin migration](application-origin-migration.md) | Move a deployed app across a browser security boundary with recovery, verification, rollback, and retirement. |2021Blocked at any step — environment, browser, build, or test failures? Go straight to22[Troubleshooting](troubleshooting.md).2324The root [README](https://github.com/FelineStateMachine/lofi/blob/main/README.md) provides the25shortest product overview and command summary. AI agents can ingest these docs as26[llms.txt](https://lofi.host/llms.txt) (index) or [llms-full.txt](https://lofi.host/llms-full.txt)27(complete corpus including the API reference).2829## Reference3031- [Commands](reference/commands.md)32- [Configuration](reference/configuration.md)33- [Generated project layout](reference/project-layout.md)34- [Identity and recovery model](auth-identity.md)35- [Account and access API](reference/access.md)36- Access template examples — who may touch which rows37 - [Direct sharing](examples/shared.md)38 - [Fixed-role group](examples/group.md)39 - [Policy conditions on typed columns](examples/policy-conditions.md)40- [Nouns and verbs](nouns-and-verbs.md) — declaring verbs, effect units, and the write lifecycle41- [The effect library](effects.md) — built-in effect units and the custom-unit authoring contract42- Data modeling examples — how to shape tables and columns43 - [Collaborative list data model](examples/collaborative-list.md)44 - [Collaborative sets](examples/collaborative-sets.md)45 - [Binary and structured payloads](examples/payloads.md)46 - [Schema evolution](examples/schema-evolution.md)47 - [Nested app namespaces](examples/nested-namespaces.md)48- [Store provisioning](store-provisioning.md)49- [lofi-node](https://lofi.host/node) — the sync node your **users** can run to own their data's50 location; tutorials, guides, and the node reference live in the site's `/node` section51- [Optional installed-app recipes](recipes/README.md)52- [Advanced device-auth primitive](auth.md)5354## The author boundary5556Generated projects intentionally divide application source from versioned framework code:5758```mermaid59flowchart TB60 subgraph Author["You own"]61 Schema["schema.ts"]62 Permissions["permissions.ts"]63 App["app.ts"]64 UI["pages, layouts, islands, styles"]65 Public["public assets"]66 Tests["tests"]67 end6869 subgraph Framework["lofi owns"]70 Runtime["@nzip/lofi package"]71 Storage["storage and subscriptions"]72 Identity["identity and recovery"]73 Lifecycle["sync, PWA, lifecycle"]74 end7576 UI --> Runtime77 Runtime --> Storage78 Runtime --> Identity79 Runtime --> Lifecycle80```8182- Change `src/schema.ts`, `src/permissions.ts`, `src/app.ts`, `src/pages/`, `src/layouts/`,83 `src/islands/`, and `src/styles/`.84- Import documented runtime seams from `@nzip/lofi`; no framework implementation is copied into85 `src/`.86- Change files under `public/` when customizing the icon or manifest. The package build generates87 the service worker.88- Keep application tests under `tests/`.8990## Framework contributor material9192The following documents explain why lofi behaves as it does. They are useful when changing the93framework, but they are not application tutorials:9495- [Developer-experience contract](https://github.com/FelineStateMachine/lofi/blob/main/docs/devx-contract.md)96- [Historical prototype seed](https://github.com/FelineStateMachine/lofi/blob/main/docs/seed.md)97- [`docs/spikes/`](https://github.com/FelineStateMachine/lofi/tree/main/docs/spikes) and retained98 evidence99100Spike evidence records the state of an experiment at a specific commit and package pin. Preserve it101as historical evidence; do not update it to look like the current generated app.