@lampdotdev/lamp 0.0.0-stage → 0.36.2-nightly.16

package/Resources/skills/game-ui/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: game-ui
+description: A game's screens and how they feel - picking the screen flow that fits this game (how it opens, teaches, restarts and returns) before drawing any of them, what the shared display and each phone show in each phase, authored art direction, an overworld where one suits, one signature motion, phone controllers built for the player's job, teaching controls in play, and checking the real opening. Read before designing or changing a game's opening, title, menus, level select, HUD, pause or results, whatever the game is made with; a new web game at home on the Mac starts from the web-game guide and game-feel instead, and the parts of this it needs come as the skills that guide names.
+---
+
+# A game's screens
+
+A game's interface should feel made for its world. The failure to avoid is one screen holding everything: the controls,
+a stage picker, a join code and the settings, around a small game. Apply this to a new game, or when the person asks
+for its screens to change: don't redesign a game they already like on your own.
+
+## A short brief
+
+Before drawing a screen, settle these for yourself, and make each one for this game rather than the first that comes:
+
+- what the players do, and what counts as winning;
+- who is holding what, and from how far they look: a shared TV across the room, a Mac at a desk, a phone in the hand;
+- three qualities of its world (playful, homemade, a bit chaotic);
+- one material or medium the interface is made of (a recipe book, cut paper, a two-ink print, chalk on slate, a tin toy);
+- a palette of a few colors, a shape language, and one signature motion (below).
+
+## Pick the flow first
+
+For a new game, or when the person asks to change how its screens go, decide the flow before drawing any screen: how
+the game opens, where it teaches, how a restart works and how a player comes back. A title over a backdrop is what comes
+first to mind, and few games need it, so ask what the player should do first and what, if anything, has to come before
+that. These are examples of a flow, each with when it fits and what it costs:
+
+- **Instant play** (2048): it opens on the game, ready to play, and the first press is the start press, which brings
+  the controls before the clock or the danger begins. A new game is one quiet press. It fits a game a glance explains, with nothing to choose. There's no
+  moment for mood or choices, so the name stays small and settings wait in pause.
+- **Arcade loop** (Asteroids): the name, the game playing itself and the best scores turn over until someone starts, the
+  controls come as the run begins, and game over comes back round with the score. It fits short runs and a score to beat.
+  The loop has to be worth watching, or it's a title with extra steps.
+- **An opening in the fiction** (UNDERRUN): it opens inside the world, on a transmission, a scene or someone talking, and
+  play grows out of that, with the name arriving when it's earned and the controls where the fiction hands over to
+  play. It fits a game with a story or a strong place. It
+  costs writing and slows a second visit, so it's short and can be skipped at any moment, and the registered state keeps
+  which beat it's on and how far through, so a change or a return goes on from there and a finished one isn't replayed.
+- **A briefing** (HexGL): the course, the vehicle and what's at stake, then the controls with a countdown. It fits a game where what
+  you're about to face changes how you play. It adds a step before every round, so Rematch and Continue go past it.
+- **Calm exploring** (Moonpool): it opens in the place, with nothing to fail, the name passing through and the first
+  thing worth finding in sight. The first press brings the controls, what to do comes from what the player notices, and
+  a return puts them where they left off.
+  It fits a game with no pressure. A goal can go unseen, so the world has to point at it.
+
+Another flow is often better: a game played only with phones may open on joining, a board game on its seats. The
+path with a title below is one more choice, not the default.
+
+Write the choice in APP.md as a `Flow:` line, so a later change keeps it: a sentence or two on how the game opens, where
+it teaches, how a restart and a return go and why that suits this game, never only a name. Leave it where it is when a
+change doesn't touch how the screens go.
+
+### What every flow keeps
+
+Leave out the screens the game has no use for:
+
+1. **A title**, where the flow has one: the game's name in a scene or strong emblem, one dominant Play or Continue, and a
+   few quieter choices (How to play, Settings). It's the first screen and the main menu at once. No level cards or
+   join code here: those are later screens.
+2. **Joining or setup**: only when the game needs it, and only the choices needed now. Rule tweaks go behind a labeled
+   secondary choice.
+3. **Level or mode choice**: a screen of its own, when the choice means something. A game with one endless mode goes
+   straight to play.
+4. **Play**, then **Pause** with Resume first, and **Results** that say what happened before any decoration.
+
+Starting is one action and it visibly changes something: no splash that only asks for a press before the real menu, and
+no second confirmation of what the player just chose. A prompt to press something after the opening is built from the
+real bindings (the game skill says how).
+
+**The opening never shows controls or key bindings**, whatever the flow, and however many players share the keyboard:
+local multiplayer is no exception. That means no key or button name and no label for what a control does (Space, WASD,
+A, "Whack: F"), on a card, on a tag beside a character or in a start prompt. It invites with a word, Play or Start,
+that a click or any of the game's confirm buttons answers. Players learn the controls afterwards, either on a short
+screen of their own after the start press or as the match begins, before play, and the flow chooses which. Rematch and
+Continue go past them, and they stay in pause. The stick and buttons Lamp draws on a touch screen are the controls
+themselves, not labels.
+
+Rematch and quick start keep the session's choices: players, level, mode, and go straight to the round. Settings aren't
+a step on the way to play.
+Back returns to the previous choice with its state intact, and leaving a lobby, restarting a round and quitting read
+as different things. Confirm only what would throw away progress or break up the party.
+
+Each screen has one job. "What is this game?" and "which level?" are two questions, so they're two screens.
+
+### With phones
+
+Before writing a phone's screens, go through each phase of the flow and settle what the shared display shows and what
+each player's phone shows, and keep that as a small table under the `Flow:` line. The shared display is whatever everyone looks at: the
+Mac, a TV, or a phone or iPad running the game. A phone used as a controller, by a phone page or an app of the project's own
+(the phone-controllers skill), is a different thing from a phone running the game, which has only its own screen and
+needs no split.
+
+A party quiz might come out like this; another game's will differ:
+
+| Phase | Shared display | Each player's phone |
+| --- | --- | --- |
+| Joining | the code, who's in | name, then "You're in" |
+| Waiting | who's still to come | what the game is waiting for |
+| A question | the question, the time left | the answers |
+| Results | what happened, the scores | their own result, Again |
+
+- Say who steers a menu everyone can see: the first player, the host, or a vote. All phones moving one marker isn't a
+  design.
+- Waiting always says for what, on both, and the game never sits silent.
+- A phone that drops is named on the shared display, and the flow says whether the game holds or carries on. It comes
+  back to the current phase as the same player, never to the start.
+
+When making or changing a phone controller, design it from the player's job in this game, then its phases:
+
+- **Primary interaction:** what this player mostly does on the phone, shaped by the mechanic. A pattern lock takes the
+  whole screen and is drawn on with one finger, and each attempt's clues stack up beside it.
+- **Supporting actions:** only what the job needs around it (Undo, Submit, ready, a power-up).
+- **Feedback and information:** what the phone tells this player that the shared display doesn't, right where they're
+  acting: a wrong attempt answers on the phone, with no change of phase.
+- **Each phase its own screen:** controls for another phase aren't on it, so a player between rounds isn't left looking
+  at a dimmed copy of play.
+- **A plainer way:** a gesture has one to the same move where the mechanic allows it, spelled out in the design: tap the
+  nodes in order, with Undo and Submit. Where the mechanic is the timing or the skill of the gesture itself, don't
+  promise the same game by another route: give an easier setting, or say there's no plainer way.
+
+Then ask: do the phone's actions, feedback and information fit this player's job? This is a question to answer for the
+game, not a rule against any layout. A buzzer, a wheel or a pad can suit many games, and a pad is often right when eyes
+stay on the shared display. Lock art around generic buttons doesn't fit: the player still only presses buttons.
+
+## Authored, not defaulted
+
+Certain choices mark a game as made in one sitting, because they're what comes first: pill buttons in a centered stack,
+a centered title with its tagline, start prompt and controls underneath, a default rounded font, emoji as art, soft
+drop shadows on cards, a teal gradient, a static backdrop with a panel on it.
+Any of them can be right, but only when chosen for this game. Two games shouldn't share a composition.
+
+The name is treated live text: set in a face that fits, then given size, spacing, a slant, an outline, a stamp or a
+place in the scene. Letters can sit on a sign, follow a path, or be cut out of something. System fonts are a fine
+start, and a licensed font may ship in the game's own folder with its credit, but `assets` doesn't fetch fonts. `make_art`
+paints no lettering, so never ask it for a logo, and its pictures have their own soft, rounded style: use one where that
+suits the medium, and draw the rest in code. A small game needs zero or one new picture.
+
+## Theme in the composition
+
+Theme changes how a screen is built, not only its colors. Choose a small vocabulary and use it on every screen:
+background, surfaces, edges, the focus marker, a display type and a reading type, a few icons, and one way of moving
+between screens.
+
+- **A cooking game**: the title is an open cookbook, the levels are its tabbed recipes with a picture of each dish, a
+  stamped rating marks a finished one, and a page turn carries you between them.
+- **A camping party game**: the title is a campsite at dusk, the levels are stops on a trail map joined by a dotted
+  path, a pennant marks where you are, and the camera moves along the trail.
+
+The metaphor stays a presentation, never a puzzle: destinations keep ordinary names, and what can be chosen looks
+choosable.
+
+Level choices show a preview, a name and progress, with focused, selected, locked and completed each distinct. A lock
+says what opens it. Never tell these states or the players apart by color alone: add a shape, label or icon.
+
+Give the title or scene room, and save the strongest accent for what's focused and what matters now.
+
+## A menu that's a place, where it suits
+
+Some games choose their levels in the world instead of on a screen of cards: a small map where a character or vehicle
+goes from stop to stop. It suits a game with places to go, and it's one idea among others: a cooking game can use its
+recipes, a heist a planning table, and a game of one arena needs none. Don't add one to a small game that asked for
+something plainer.
+
+**Worked example: Pond Hop.** A party game of frogs on three ponds. The title is the first pond, close up, and Play lifts
+the camera to show all three joined by a trail of lily pads. The frog sits on the pad of the chosen pond. Left and right
+hop it to the next pad, the pond's name and best score appear beside it, OK dives in, and Back returns to the title.
+
+What makes it work anywhere:
+
+- The stops are a list of nodes, not a space to steer through: arrows choose, OK enters, Back returns. No analog stick,
+  diagonal, timing or gesture is needed to enter a level, so it works with a TV remote, touch and phones.
+- A returning player never walks the path again: Continue and Rematch start the chosen level directly.
+- Decide who steers it ("With phones", above).
+- In a small window the choices stay the same size; the map recomposes rather than shrinks.
+- What the registered state keeps is yours to name: the screen, the node and the focus, with the camera registered too,
+  restored directly with no intro replayed (the game skill, "Changes while it's played"). The map isn't `busy()`.
+
+## A finished look
+
+A game should look finished, in whatever style suits it:
+
+- **The playfield dominates.** The world takes most of the screen; the HUD shows only what's needed in play and sits
+  clear of the action. A racer's speed and lap sit at the edges of the driving view; a board game's score
+  sits beside its board.
+- **Menus share the world's look.** Title, pause and results are made of the same material, palette and type as play,
+  and pause keeps the scene visible behind it.
+- **Every detail chosen.** Type, spacing, icons and each control's states (rest, focus, pressed, disabled) are styled
+  for this game: nothing is left as a browser or system default by accident.
+- **Focus and access stay.** Keyboard and controller focus is always visible, and controls stay real buttons that every
+  input the game promises can reach.
+
+## Teaching and input
+
+- Teach by doing: a safe first objective, the action named beside the thing it applies to, then the next action when
+  it's needed. A wall of keys before play teaches nothing.
+- How to play and the controls stay reachable wherever the game can stop: from pause, and from its title if it has one.
+  They show the player's actual bindings (the game skill says how). On a phone, say touch, not keys. Essential help
+  never needs hover.
+- A menu opens with visible focus on the likely choice, and works with every input the game promises.
+- Input belongs to the screen on top: a press in a menu never also moves the player behind it.
+- With phones as controllers, the shared screen shows what's public (who's in, whose turn, the score); each phone shows
+  its player's current action, and that a choice was received. A join code belongs to the joining screen (the
+  phone-pages skill), which a game played only with phones may open on; it's never on a title.
+- A phone controller is part of the game ("With phones"), held the way its primary interaction suits: two thumbs
+  sideways, a lock upright. Same medium and palette as the game, and buttons named with its verbs ("Hop", not "OK").
+  What isn't usable now looks it, and a move shows only what the game accepted, so a phone with no game there says so.
+  The phone-pages skill has the layouts, and how views, moves and interrupted gestures work.
+- Never carry essential information by sound alone.
+
+## Feedback and layout
+
+- Every control answers at once: a focus marker that moves, a press that gives. What's routine stays small, so a win
+  can feel bigger. Each response says what happened and how much it mattered, and tuning it in the running game beats
+  any fixed timing.
+- One signature motion the game repeats (a squash and leap, a page turn, a stamp) gives it more character than many
+  effects. Quiet screens are allowed: type and empty space can carry a game, and a results screen needn't explode.
+- Quick transitions that a fast press can interrupt, with no queue of animations. A particle never hides a hazard or
+  an instruction.
+- Keep text readable over anything that moves, with a quiet panel behind it if needed. Try the real strings: long names,
+  big scores, the longest button glyph.
+- Keep clear of safe areas and thumbs on a phone and of cropped edges on a TV (the tv-design skill and the game's device
+  rules have the measurements). A small window recomposes the screen; it doesn't shrink everything.
+- Offer reduced motion and mute where there's motion or sound to reduce, and keep meaning without either.
+
+Sound carries the same world as the screens; the game skill says how to make and play it.
+
+## Proof
+
+Play the journey, don't only look at it:
+
+- the whole of the flow, from its opening through a round to how it ends, then a rematch or a return with the choices
+  kept;
+- pause, help and Back from each place, returning to where they were;
+- each input the game supports, and a mix of them where players differ;
+- long text, a small window and a wide one;
+- mute and reduced motion;
+- how it looks: the opening, play and results read as one game; the HUD stays readable at the smallest window; focus,
+  pressed and disabled look different; nothing shows a browser's default look by accident;
+- joining, a failed join and reconnecting, where the game takes phones, and a gesture interrupted partway (the
+  phone-pages skill).
+
+Look at each screen, and at motion with `look_at_app`'s `motion`: one picture proves appearance, not navigation or
+sound. Lamp can't play a phone page: a join is proved only where phones are really used. When you finish, name any
+device or path you didn't run.
+
+## Check the real opening
+
+After your last edit to any screen and before you say a new game is done, or a change to its flow, see what a new
+player sees. A look from before that edit doesn't count, so every later edit to a screen means this check again.
+
+`look_at_app` with `reopen` starts the game again from its beginning: a plain look shows where the person is in an
+open game, and `use_app` plays on from there, so after playtesting it can be anywhere. While the person has the game
+open, Lamp asks them to press Reload first, with no picture until they do. Its saves stay (a fresh start keeps them),
+so the picture may be a returning player's. Look before pressing anything; where the opening changes by itself, follow
+the look with `use_app` and `wait` before any other move. Say which you saw, and when you couldn't see the opening, say
+so instead of calling it checked.
+
+First, write out every word on the opening, in the scenery and on tags as well as in the text. Any key name, button
+name or control label among them fails, for every flow and however well it teaches: remove it before you say it's done,
+and move it to where the flow teaches the controls.
+
+Then hold the rest against the `Flow:` line, not against a picture of a title: does everything on screen serve what the
+player is doing right now? A game played only with phones may open on joining. What fails is anything there because a
+title usually has it: level cards, a join code that isn't this screen's job, a tagline and prompt stacked under the name
+with no reason in your brief.
+
+Say in a line, by name, what's on that screen that doesn't serve the flow (a rules strip, two cards of controls), or that
+nothing does. Fix what you named and run this check again. Then press start, and see the controls appear before play,
+with prompts that match the real bindings, and starting that does something the first time.
+
+## One critique pass
+
+Once the journey plays, look at each screen against your brief once, the phone page by its code (the phone-pages skill,
+"Seeing the page"). Name the one thing on it that reads as a template, and fix that, along with anything you saw break.
+For a phone controller you made or changed, answer the question in "With phones" when you report, from what you read.
+Then stop polishing; navigation that doesn't work is fixed however many passes it takes. This pass doesn't paint new
+pictures, and a wish that asked for something small stays small.

package/Resources/skills/github-projects/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: github-projects
+description: Someone's project on GitHub named in a request - explaining it, making a Lamp app or game from it ("Lampify it"), or using part of it - reading it in a git clone, and lampify, which credits the exact commit, keeps its licenses, makes the manifest and says what a Lamp app made from it still lacks. Read before using a project from GitHub.
+---
+
+# Someone's project on GitHub
+
+A link to a project on GitHub says where something is, not what to do with it. The request says that. Follow it as
+written: explain it when that's asked, make an app or a game from it when that's asked, use a part of it when that's
+asked. When a link comes with nothing that says which ("https://github.com/owner/game", or "check this out"), ask the
+person with `ask` (explain it, make it into an app or game, something else) before cloning anything.
+
+## Reading it
+
+Clone it shallowly into the reference folder and read it there:
+
+    git clone --depth 1 https://github.com/owner/name .lamp/reference/name
+
+A branch or tag the address names: add `--branch <name>`. The folder is for reading: never build in it or point the app
+at it, it isn't part of the app. A clone that fails because the project is private: call `lampify` with `read_only: true`,
+which fetches it with the person's GitHub sign-in and credits nothing, and read its copy, whose path its answer gives.
+
+Asked to explain it: read it and answer. Nothing is credited and nothing is made.
+
+## A Lamp app someone put on GitHub
+
+When the project has `lamp-app.json` or a `.lampapp` file at its top, it's made with Lamp already: don't rebuild it. Tell
+the person to open it with File → Open from GitHub… and paste its address. Lamp reviews it there.
+
+## Making a Lamp app or game from it
+
+This is making someone's project into a Lamp app ("Lampify it"): Lamp's structure, the project's code and assets in it,
+its credit and licenses in place, and the rest of what a Lamp app has.
+
+1. Clone it and read enough to know what it is: a page drawn with canvas or WebGL, a three.js or Phaser game, native
+   code, an engine Lamp's devices can't run.
+2. Give the app its structure with `make_app_for` (a game or an app, the devices, web or native), and read the skill
+   for that kind (`game`, `web-app`, `2d-game`, `3d-game`). The structure is Lamp's: its page or its Swift package,
+   `build.sh`, `Package.swift`, Lamp's own files, `icon.json`, `APP.md`. A web page with no build step (index.html with
+   its scripts and styles, a canvas or WebGL game among them) is a web app brought in: `kind` "app", `made` "web", and
+   the web-app skill's "A web app brought in" is the rule for everything after, whatever the person's devices are.
+3. Before using any of its code or assets, call `lampify` with its address and the commit your clone is at
+   (`git -C .lamp/reference/name rev-parse HEAD`). Lamp gets its own untouched copy at that commit, credits it in
+   credits.json, keeps every license and notice file under `Licenses/`, and answers with the manifest and what's still
+   missing. `adapted` is true for the project the app is made from (the default): its updates come to the person from
+   there. Anything else you bring in from GitHub (a library, a sprite pack) is cloned and lampified the same way with
+   `adapted: false`. Every later call passes the same commit: lampify never moves on to a newer one by itself.
+4. Bring its code and assets into Lamp's structure: a web page's files into `Web/` as they are, laid out as the project
+   has them, in place of the scaffold's; native code into the package's sources. Keep what makes it work and drop only
+   what the person asked to drop. Never copy its own build scripts, package manifests, workflows or wrapper page over Lamp's
+   files (`Package.swift`, `build.sh`, `Sources/LampSupport.swift`, the `lamp*.js` files), and never run anything it
+   holds (its installers, its build, its scripts). Keep its copyright headers, and its author's credit on screen.
+5. Give it what a Lamp app has that a project on GitHub doesn't: its line in `about.json`, its icon's design in
+   `icon.json`, and `APP.md` saying what it is and what it's based on (and, for a web app brought in, that it came in
+   as it is). Never write `lamp-app.json`, the project's entry
+   in `credits.json` or copies of its licenses yourself: lampify does.
+6. Look at it with `look_at_app` until it works.
+7. Call `lampify` again with the same address and commit, and fix whatever it says is still missing, until it says
+   nothing is.
+8. Tell the person what it's based on, its license, and when it came with none, that whether to share or publish it
+   is their call, and Lamp will remind them when they do. When the address named a tag or a branch, say its updates will come from the project's
+   default branch. Putting it on GitHub is theirs to choose, with Also put on GitHub on its link's Release Update; never do it for them.

package/Resources/skills/icloud-sync/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: icloud-sync
+description: Keeping the person's data the same on every device signed in to their iCloud account with LampSync - declaring it, the API, signing, what the simulator shows, and what may never sync. Read before an app keeps data in iCloud.
+---
+
+# The same data on every device
+
+To keep the person's data the same on every device signed in to their iCloud account (the Mac and the iPhone, or an
+iPhone and an iPad), declare `{"icloud": true}` in `capabilities.json` and keep that data with `LampSync` from
+LampSupport.swift instead of LampStore:
+
+- `@StateObject private var notes = LampSync.collection("notes", of: Note.self)` in the view that owns the list (one
+  object per name, shared by every view that asks), then `notes.items`, `notes.put(note)`, `notes.delete(id)`,
+  `notes.get(id)`; the view follows changes made anywhere.
+- Items are Codable and Identifiable, and the same rules as LampStore's apply to changing a saved type.
+- Use it for the data people would expect everywhere; settings for one device stay in LampStore.
+
+## Signing and status
+
+Lamp signs the app for iCloud with the person's Apple team, which must be in the Apple Developer Program (a free
+account can't use iCloud; the build then fails at signing, and you say so plainly). Sync needs the device signed in
+to iCloud; the simulator usually isn't, so what you see there is the data kept on that device, and
+`LampSync.shared.status` says why. Offer the status in the app's settings.
+
+## What never syncs
+
+Apple's terms forbid keeping sensitive health information about a person in iCloud: what is medical (diagnoses,
+conditions, symptoms, medications, lab results, clinical records, reproductive or mental-health entries) stays on the
+device, in LampStore, never in LampSync. Everyday activity and fitness numbers (steps, distance, active calories,
+workouts, water) aren't that, and may sync. When it's unclear which a kind is, keep it on the device.

package/Resources/skills/iphone-hardware/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: iphone-hardware
+description: What the phone itself offers an iPhone app - motion, the camera and scanning, location, haptics, Face ID, Bluetooth and nearby phones, Apple Health, NFC, AR and music - with the frameworks to use, and the capabilities.json declarations Lamp signs the app for. Read before using any of them.
+---
+
+# The phone's own hardware, and Health
+
+The phone itself is the app's best material: use what it has, without being asked, whenever it fits what the user
+wants.
+
+## What to use for each
+
+- Motion: `LampMotion` from LampSupport.swift (tilt, gravity, acceleration, rotation, compass heading, today's
+  steps, a shake count) for anything that tilts, steers, shakes or counts.
+- Camera: AVFoundation's AVCaptureSession in a UIViewRepresentable for live capture, UIImagePickerController or
+  PhotosPicker to take or choose a picture, VisionKit's DataScannerViewController to read text and codes live and
+  VNDocumentCameraViewController to scan documents.
+- Location and maps: CoreLocation (ask for when-in-use) and MapKit. Notifications at a place:
+  UNUserNotificationCenter with a location trigger.
+- Haptics: `.sensoryFeedback` for taps and successes, CoreHaptics for patterns.
+- Face ID or Touch ID: LocalAuthentication.
+- Bluetooth devices: CoreBluetooth; nearby phones without a network: MultipeerConnectivity.
+- NFC tags: CoreNFC.
+- Siri and Shortcuts: App Intents. AR: ARKit with RealityKit. Music: MusicKit or MediaPlayer.
+
+## Health
+
+`LampHealth` from LampSupport.swift, after `{"healthkit": true}` in capabilities.json: `authorize(read:write:workouts:)`
+once, then `total(.steps)` (today's; a day's sum, or its average for heart rate and the like),
+`dailyTotals(.activeCalories, days: 7)`, `latest(.weight)`, `samples(.heartRate, days:)`, `sleep()` (hours, last
+night), `workouts(days:)`, and `save(.caloriesEaten, 350)` to log what the person tells it; `Kind` lists steps,
+distance, calories, heart rate, sleep, weight, water, protein and the rest, each with `unitName`.
+
+- The simulator has no Health data of its own: save a sample there to have something to read, and only there. Never
+  write test data on a person's own phone, where it would join their real record; what the app logs for them is only
+  what they told it.
+- A Mac has none at all (`LampHealth.isAvailable` is false): an app for both reads on the iPhone and keeps what the
+  Mac shows in LampSync, if it's activity and fitness that may go to iCloud (see the iCloud rule); medical data stays
+  on the iPhone.
+
+## Permissions and declarations
+
+The app already declares why it wants each of these (microphone, speech, camera, photos, location, motion,
+Bluetooth, Face ID, health, NFC, Siri, nearby devices, music), so just request authorization before use and handle
+denial in the interface.
+
+Health, NFC, Siri, nearby phones and background work need a declaration first: write `capabilities.json` at the app's
+root, e.g. `{"healthkit": true, "nfc": true, "siri": true, "weather": true, "homekit": true, "timeSensitive": true,
+"backgroundModes": ["audio", "location"], "bonjourServices": ["_myapp._tcp", "_myapp._udp"], "backgroundTasks":
+["com.example.refresh"]}`, and Lamp signs the app for them and declares them.
+With a free Apple account Apple won't sign NFC, Siri, `weather`, `timeSensitive` or iCloud; the request's device line
+says when the person's team is a free one, and then those stay out.
+
+- Modes: audio, location, fetch, processing, remote-notification, bluetooth-central, bluetooth-peripheral.
+- `bonjourServices` are the service types MultipeerConnectivity browses for (both _tcp and _udp of the same name, up
+  to 15 characters).
+- `backgroundTasks` are the identifiers BGTaskScheduler registers, needed with the fetch and processing modes.

package/Resources/skills/iphone-widgets/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: iphone-widgets
+description: An iPhone app's home screen widgets, Live Activities and Control Center controls (Widget/) - how they're written, the code they share with the app, the data the app hands them, buttons in them, and how to see them in the simulator. Read before writing or changing anything in Widget/.
+---
+
+# Home screen widgets, Live Activities and controls
+
+## Writing them
+
+Write them with WidgetKit, SwiftUI and ActivityKit in a `Widget/` folder at the app's root, beside Sources/, starting
+with Widget/Widget.swift: one `@main` on a `WidgetBundle` holding the widgets (`StaticConfiguration` with a
+`TimelineProvider`, `.containerBackground(.fill.tertiary, for: .widget)`, `.supportedFamilies` for the sizes that fit)
+and any `ActivityConfiguration` (the lock screen's view and the `dynamicIsland` regions). Lamp builds that folder into
+the app as its extension.
+
+It shares no code with Sources/ and has nothing from LampSupport.swift, except Widget/Shared/: Swift there is compiled
+into both the app and the extension (Lamp links it into Sources/ as Sources/WidgetShared; edit it in Widget/Shared/),
+the place for an `ActivityAttributes` type and anything else both sides need.
+
+## The widget's data
+
+- In the app, `LampWidget.share(Summary(…), as: "summary")` with any Codable value, at launch and whenever it changes
+  (it redraws the widgets too).
+- In the widget, `LampWidget.read(Summary.self, from: "summary") { summary in … }` in getSnapshot and getTimeline, or
+  `await` it, from Widget/LampWidgetSupport.swift, which Lamp writes: never edit it. It gives what the app shared
+  last, also while the app is closed, and nil until then: show a short line asking to open the app.
+
+## Live Activities
+
+A Live Activity starts from the app, `Activity.request(attributes:content:)`, and is changed with `update` and ended
+with `end` from the app while it runs; there's no server to push changes, so give a timer or progress an end date
+(`Text(timerInterval:countsDown:)`, `ProgressView(timerInterval:)`) and it moves by itself.
+
+## Buttons and controls
+
+A button or toggle in a widget or Live Activity runs an App Intent, `Button(intent: AddCupIntent()) { … }` or
+`Toggle(isOn:intent:)`: write that intent in Widget/Shared/ as a `LiveActivityIntent`, which iOS performs in the app
+(starting it out of sight when it's closed), and keep the work under `#if !LAMP_WIDGET` (defined only in the widget,
+which can't reach the app's code): change the data there and `LampWidget.share` it, and the widget redraws.
+
+A Control Center control is a `ControlWidget` in the same `WidgetBundle`, marked `@available(iOS 18, *)`:
+`StaticControlConfiguration(kind: "AddCup") { ControlWidgetButton(action: AddCupIntent()) { Label("Add a Cup",
+systemImage: "cup.and.saucer") } }`.
+
+## Seeing them, and what to tell the person
+
+- `use_app` with `key` "lock" shows the lock screen, where a Live Activity is, and "home" the home screen; then the
+  picture.
+- Not every iPhone has a Dynamic Island (the iPhone 14 Pro and Pro Max, and every iPhone 15 and later but the 16e
+  have one; iPads don't): `look_at_app` says which simulator the app is open on, and when it has none, say so and
+  that the person can choose one under Try On.
+- Only the person can add a widget to the home screen, and Lamp shows them how: don't explain it, and say in a
+  sentence that it's ready to add.

package/Resources/skills/lg-developer-mode/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: lg-developer-mode
+description: How Lamp walks the person through turning on Developer Mode on their LG TV (webOS) the way LG supports - opening the Developer Mode app's page in the LG Content Store and then the app itself on the TV, while the person installs it, restarts the TV when asked, signs in and turns its switches on with their own remote. Lamp's TV setup follows the steps below when the person clicks Do It for Me.
+setup-for: tv
+setup-system: webOS
+setup-step: developer-mode
+---
+
+# Turning on Developer Mode on an LG TV
+
+LG lets a TV take the person's own apps once its Developer Mode app is installed, signed in to a free LG developer
+account and switched on. Lamp can't do that for them and mustn't try: installing an app, restarting the TV, signing in
+and turning the switches on are the person's, on the TV, with its remote. What Lamp does is put the right screen in
+front of them at each step and say in one short line what to do.
+
+What happens on the TV, in order:
+
+1. The person installs Developer Mode from the LG Content Store.
+2. On some TVs the app shows no Sign In until the TV has been fully restarted (unplugged, not just turned off with
+   the remote, which only puts it to sleep). Until then its switches can be turned on but nothing works.
+3. The person signs in with their LG developer account and turns Dev Mode Status on; the TV restarts.
+4. In Developer Mode again, the person turns Key Server on and types the passphrase it shows into Lamp. The key
+   server answers only while Developer Mode is open on the screen, so it stays open until Lamp has connected.
+
+A TV that was set up before may show Developer Mode already signed in, with Dev Mode Status on: then only Key Server
+and the passphrase are left.
+
+Lamp reaches the TV over its second-screen socket, the protocol LG's Connect SDK publishes: `wss://<address>:3001`,
+the TV's own certificate kept with the key the TV hands back once the person lets Lamp in. Later connections offer
+that key, to a TV showing the same certificate only, and the TV doesn't ask again. Requests that open or list apps
+need the key, and fail with 401 without it.
+
+## What Lamp never does
+
+- Press the remote's buttons for the person, install the app silently, or sign in for them.
+- See the LG account's password or the passphrase in any conversation: the passphrase is typed into the setup window
+  and goes only to the TV's key server (port 9991), exactly as typed (it's case-sensitive).
+- Say a step happened that it can't see. Lamp sees that the TV let it in, that the app is installed, and that the TV
+  went away and came back; a sign-in or a switch is the person's to do, and Lamp says nothing of it as done.
+- Open anything but the LG Content Store's page for Developer Mode and the Developer Mode app.
+
+## Not yet checked on a real TV
+
+- That the store query below (the Connect SDK's form) opens Developer Mode's own page rather than the store's front
+  page. The TV only says it opened the store, so the line said then always says what to do on the front page.
+
+## The steps
+
+Lamp's setup reads this block and follows it in order; the frontmatter's `setup-for`, `setup-system` and `setup-step`
+say which setup step it does (the TV row's first, on webOS). `{name}` is the TV's name. A step is one of: `connect`
+(let Lamp in; asks on the TV the first time), `request` (send one request; `failed` is said and the setup goes on when
+`continueOnFailure`), `wait` (ask the TV every `every` seconds until the value at `until.json` in the answer to
+`until.uri` equals `until.equals`), `confirm` (the person clicks `button` once they've done it; a confirm has no
+`done`, since Lamp didn't see it happen), `rejoin` (the device restarts: Lamp carries on by itself once it has seen it
+stop answering and answer again, and only then says `done`; `button` skips a restart that isn't needed and claims
+nothing), and `handoff` (the last: the TV goes back to the setup window's own step, here the passphrase, which is done
+only once the key is fetched, unlocked and SSH answers).
+
+```lamp-setup
+{
+  "connection": "webos-second-screen",
+  "offer": "Lamp opens each screen on the TV; you press the buttons.",
+  "steps": [
+    {
+      "do": "connect",
+      "doing": "Asking {name} to let Lamp in…",
+      "ask": "On the TV, choose Accept.",
+      "done": "{name} let Lamp in",
+      "refused": "{name} didn't let Lamp in. Click Try Again, then choose Accept on the TV."
+    },
+    {
+      "do": "request",
+      "uri": "ssap://system.launcher/launch",
+      "payload": {
+        "id": "com.webos.app.discovery",
+        "params": {
+          "query": "category/GAME_APPS/com.palmdts.devmode"
+        }
+      },
+      "doing": "Opening the LG Content Store on {name}…",
+      "done": "Asked {name} to show Developer Mode in the LG Content Store",
+      "failed": "{name} couldn't open the LG Content Store. On the TV, open it and search for Developer Mode.",
+      "continueOnFailure": true
+    },
+    {
+      "do": "wait",
+      "until": {
+        "uri": "ssap://com.webos.applicationManager/listApps",
+        "json": "apps.id",
+        "equals": "com.palmdts.devmode"
+      },
+      "every": 3,
+      "doing": "Waiting for Developer Mode to be installed…",
+      "ask": "On the TV, choose Install. If the store shows its front page, search for Developer Mode first.",
+      "done": "Developer Mode is installed on {name}"
+    },
+    {
+      "do": "request",
+      "uri": "ssap://system.launcher/launch",
+      "payload": {
+        "id": "com.palmdts.devmode"
+      },
+      "doing": "Opening Developer Mode on {name}…",
+      "done": "Asked {name} to open Developer Mode",
+      "failed": "{name} couldn't open Developer Mode. On the TV, open it from your apps.",
+      "continueOnFailure": true
+    },
+    {
+      "do": "rejoin",
+      "ask": "If Developer Mode shows no Sign In, unplug the TV for 30 seconds, then plug it back in and turn it on. Lamp carries on once the TV answers again.",
+      "button": "Sign In Is Showing",
+      "done": "{name} is back on"
+    },
+    {
+      "do": "request",
+      "uri": "ssap://system.launcher/launch",
+      "payload": {
+        "id": "com.palmdts.devmode"
+      },
+      "doing": "Opening Developer Mode on {name}…",
+      "done": "Asked {name} to open Developer Mode",
+      "failed": "{name} couldn't open Developer Mode. On the TV, open it from your apps.",
+      "continueOnFailure": true
+    },
+    {
+      "do": "rejoin",
+      "ask": "In Developer Mode, sign in with your LG developer account, then turn Dev Mode Status on. The TV restarts, and Lamp carries on once it's back on.",
+      "button": "Dev Mode Status Is Already On",
+      "link": {
+        "title": "Get an LG Developer Account",
+        "url": "https://webostv.developer.lge.com/"
+      },
+      "done": "{name} is back on"
+    },
+    {
+      "do": "request",
+      "uri": "ssap://system.launcher/launch",
+      "payload": {
+        "id": "com.palmdts.devmode"
+      },
+      "doing": "Opening Developer Mode on {name} again…",
+      "done": "Asked {name} to open Developer Mode again",
+      "failed": "{name} couldn't open Developer Mode. On the TV, open it from your apps.",
+      "continueOnFailure": true
+    },
+    {
+      "do": "handoff",
+      "ask": "In Developer Mode, turn Key Server on and keep Developer Mode open on the TV. Type the passphrase it shows below exactly as shown, then click Connect."
+    }
+  ]
+}
+```