[ClaydeCode]

Updates the documented app_meta.json format from 1.2 to 1.3, the current version since shard_core 0.40.0. Version 1.3 also changed the lifecycle fields, so lifecycle.md gets the bigger part of this change.

Changes

• app_meta_json.md:
  • the full example now uses "v": "1.3" and the new lifecycle fields;
  • "current version" now says 1.3;
  • a new "Version 1.3" entry under Past Updates;
  • a note that the linked JSON schema still describes 1.2;
  • the minimum_portal_size values (xs to xl) are listed.
• lifecycle.md:
  • new "Pause and Stop" section: idle apps are frozen with their memory moved to swap, then stopped after a longer idle time; apps are paused or stopped early under memory pressure, and all apps are stopped on low disk;
  • the old idle_time_for_shutdown description is replaced by a table of idle_for_pause (default 60s), idle_for_stop (default 3h), skip_pause and always_on, plus the rules for combining them;
  • notes that pausing can be switched off on a shard, and that ≤1.2 files are still read.
• digest.md: the same facts.

Why the old page was wrong in practice

The page promised a 60-second stop via idle_time_for_shutdown. On 1.3 shards, that field is migrated to idle_for_pause, so with pausing on, the app pauses after 60s and stops after 3h. With pausing off, it only stops after 3h.

How it was verified

• Field rules and defaults: Lifecycle model, AppLifecycleSettings, _control_app_time, _demote_lru and docker_pause_app at the 0.41.3 tag. The 1.2→1.3 migration is in app_meta_migration.py. 0.40.0 is the first tag with CURRENT_VERSION = "1.3".
• "Older shards cannot read 1.3": the pre-0.40 migration loop indexes migrations by v, so it has no entry for "1.3".

mkdocs build --strict passes locally.

Spotted, not addressed here

• No 1.3 JSON schema is published. The json-schema job in freeshard's .github/workflows/release.yml is commented out, so the newest schema at the storage URL is 1.2. An IDE using it will flag the 1.3 lifecycle fields and minimum_freeshard_version.
• Store apps still use old format versions. Every app in app-repository is on format 1.0, 1.1 or 1.2. That still works through migration, but every app with an idle_time_for_shutdown (36 of them) now pauses at that time and stops after 3h, not at the time its author picked.

🤖 Generated with Claude Code