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- Data modeling examples — how to shape tables and columns41 - [Collaborative list data model](examples/collaborative-list.md)42 - [Collaborative sets](examples/collaborative-sets.md)43 - [Binary and structured payloads](examples/payloads.md)44 - [Schema evolution](examples/schema-evolution.md)45 - [Nested app namespaces](examples/nested-namespaces.md)46- [Store provisioning](store-provisioning.md)47- [lofi-node](https://lofi.host/node) — the sync node your **users** can run to own their data's48 location; tutorials, guides, and the node reference live in the site's `/node` section49- [Optional installed-app recipes](recipes/README.md)50- [Advanced device-auth primitive](auth.md)5152## The author boundary5354Generated projects intentionally divide application source from versioned framework code:5556```mermaid57flowchart TB58 subgraph Author["You own"]59 Schema["schema.ts"]60 Permissions["permissions.ts"]61 App["app.ts"]62 UI["pages, layouts, islands, styles"]63 Public["public assets"]64 Tests["tests"]65 end6667 subgraph Framework["lofi owns"]68 Runtime["@nzip/lofi package"]69 Storage["storage and subscriptions"]70 Identity["identity and recovery"]71 Lifecycle["sync, PWA, lifecycle"]72 end7374 UI --> Runtime75 Runtime --> Storage76 Runtime --> Identity77 Runtime --> Lifecycle78```7980- Change `src/schema.ts`, `src/permissions.ts`, `src/app.ts`, `src/pages/`, `src/layouts/`,81 `src/islands/`, and `src/styles/`.82- Import documented runtime seams from `@nzip/lofi`; no framework implementation is copied into83 `src/`.84- Change files under `public/` when customizing the icon or manifest. The package build generates85 the service worker.86- Keep application tests under `tests/`.8788## Framework contributor material8990The following documents explain why lofi behaves as it does. They are useful when changing the91framework, but they are not application tutorials:9293- [Developer-experience contract](https://github.com/FelineStateMachine/lofi/blob/main/docs/devx-contract.md)94- [Historical prototype seed](https://github.com/FelineStateMachine/lofi/blob/main/docs/seed.md)95- [`docs/spikes/`](https://github.com/FelineStateMachine/lofi/tree/main/docs/spikes) and retained96 evidence9798Spike evidence records the state of an experiment at a specific commit and package pin. Preserve it99as historical evidence; do not update it to look like the current generated app.