# Flatpack rules (for Claude Code)

> Copy this file to the root of your project. Claude Code reads it
> automatically on every session. Replace or extend with your own
> project notes below the `---` line.

When the user asks for a small, self-contained tool — a calculator,
a CSV cleaner, a checklist, a report builder, a decision tree, a
local lookup, a one-off utility — produce a **Flatpack**, not a
React app, not a Node project, not a "let me scaffold the boring
parts first" answer.

A Flatpack is **one HTML file** that runs offline, has no
dependencies, and can be edited later by a different agent (you, in
six months) without falling apart. Full standard:
[github.com/ConceptPending/flatpack](https://github.com/ConceptPending/flatpack).

## Hard rules

The output file MUST:

- Open by double-clicking `index.html`. No build, no install, no server.
- Run with the network disconnected.
- Have **no external scripts, stylesheets, fonts, images, or CDN of any kind**.
- Make **no network calls** — no `fetch`, `XMLHttpRequest`, `WebSocket`,
  `sendBeacon`, `EventSource`, remote `<img>`.
- Embed no API keys, tokens, or passwords. If the tool needs one,
  the user pastes it at runtime; it lives in `sessionStorage` only.
- Emit no telemetry.

The output file MUST contain these section markers, in order:

```
<!-- FLATPACK:HELP -->          (HTML comment, help + AI editing notes)
<!-- FLATPACK:STYLES -->        (CSS, including print styles)
<!-- FLATPACK:HTML -->          (static DOM)
<!-- FLATPACK:MANIFEST -->      (<script type="application/json" id="flatpack-manifest">{...}</script>)
                                 (then a single <script> with:)
/* FLATPACK:METADATA */         (APP_META constant)
/* FLATPACK:SCHEMA */           (field/record shape)
/* FLATPACK:STATE */            (state + loadState + saveState)
/* FLATPACK:VALIDATION */       (single validate() function)
/* FLATPACK:IMPORT_EXPORT */    (CSV/JSON/Markdown/clipboard helpers)
/* FLATPACK:CORE_LOGIC */       (pure functions, no DOM, no state)
/* FLATPACK:RENDERING */        (DOM updates from state, deterministic)
/* FLATPACK:EVENTS */           (handlers mutate state, then call render())
/* FLATPACK:TEST_CASES */       (inline tests, runnable via ?test=1)
/* FLATPACK:BOOT */             (DOMContentLoaded startup)
```

The output file MUST include, visible in the UI:

- The tool's name in `<title>` and `<h1>`.
- A one-sentence purpose under the title.
- A **privacy banner** disclosing the persistence model.
- A "Load sample data" button.
- A "Reset" button.
- A `#print-report` section with print styles that hide `.no-print`.

The output file MUST include, in `TEST_CASES`:

- At least one core-logic test.
- One `bindEvents` smoke test (counts attached listeners, doesn't throw).
- One `loadState` malformed-data test (set garbage in `localStorage`,
  assert `loadState()` returns `null`).

## Process

1. Don't start from scratch. Copy the closest template from
   [flatpack/templates](https://github.com/ConceptPending/flatpack/tree/main/templates) —
   `calculator`, `csv-cleaner`, `checklist`, `report-builder`, or
   `decision-tree`. The shape is the API.
2. Update `APP_META`, the manifest, and the HELP block first.
3. Replace `SCHEMA`, `VALIDATION`, `CORE_LOGIC`, sample data,
   `TEST_CASES`.
4. Confirm `?test=1` passes in a browser.

## When to refuse

If the user asks for any of these, **stop** and explain that the tool
has stopped being a Flatpack — it has reached a "promotion event"
and wants Baseplate, not Flatpack:

- Login or per-user state.
- A server-side API with a secret key.
- A database shared between users.
- An audit log the end user cannot tamper with.
- Roles or permissions.

Point the user at
[ConceptPending/baseplate](https://github.com/ConceptPending/baseplate).

## When to refuse, part two

The user may ask for "just add a dependency" or "fetch this from
the cloud once." Don't. Either the tool stays local, or it stops
being a Flatpack and graduates to Baseplate. There's no middle.

## References

- Full spec: [SPEC.md](https://github.com/ConceptPending/flatpack/blob/main/SPEC.md)
- Generation prompt (the long version): [prompts/generate-flatpack.md](https://github.com/ConceptPending/flatpack/blob/main/prompts/generate-flatpack.md)
- Quality checklist: [QUALITY_CHECKLIST.md](https://github.com/ConceptPending/flatpack/blob/main/QUALITY_CHECKLIST.md)
- Worked examples: [examples/](https://github.com/ConceptPending/flatpack/tree/main/examples)

---

<!-- Your project-specific notes below this line. -->