[ClaydeCode]

Documents minimum_freeshard_version in app_meta.json (FreeshardBase/freeshard#246) and ties it to the secret() helper, which is the first template feature that needs it. This PR also carries the 0.41.2 → 0.41.3 version fix that missed #18.

Changes

• app_meta_json.md: the field is added to the full example as annotation 13, and a new ## Minimum Freeshard Version section explains:
  • the PEP 440 specifier format: it needs an operator, so ">=0.41.3" is valid and "0.41.3" is not;
  • the "Shard too old" behaviour for installed apps;
  • that shards older than 0.41.3 ignore the field.
• docker_compose_template.md: an info box at the top of Secrets says "Requires freeshard 0.41.3", explains that a template using secret() cannot be rendered on older shards, and links to the new section. It replaces the version line at the bottom of the section.
• digest.md: the same facts in digest form.
• Version fix: secret() is now documented as usable from 0.41.3. 0.41.2 contains the code, but its image was never published (the ghcr.io manifest is a 404), so no shard can run it.

Store hiding is documented as upcoming

The store-side half of #246 is not released:

• The Sundial gate (sundial#34) was merged on 2026-10-09, but it is among 40 unreleased commits after Sundial 0.1.2.
• Core versions v36, v37 and v38 all pin sundial:0.1.2.
• web-terminal doesn't implement the gate at all.

So on every shard today, the store still shows an app that the shard is too old for. The new section marks that part with the repo's "Upcoming Feature" warning.

What this means for Dawarich/Umami: declaring >=0.41.3 doesn't keep those apps off older shards yet. Shards on 0.41.1 or older ignore the field. A shard new enough to enforce it already satisfies >=0.41.3. On an old shard the install fails when the template renders, because secret is undefined. Real protection needs a Sundial release containing #34, pinned in a core version, and that core version rolled out.

How the behaviour was verified

• Field format: VersionSpecifier / SpecifierSet in shard_core/data_model/app_meta.py (identical at 0.41.3 and main); freeshard_version_is_compatible in app_tools.py.
• Splash text: from web/internal/app_error.py.
• Ignored by older shards: the field is absent from the 0.41.1 tag, and AppMeta doesn't forbid extra keys.
• Render failure on old shards: reproduced with plain Jinja: UndefinedError: 'secret' is undefined.
• UI pins: from the controller's core-versions/v36–v38/docker-compose.yml.
• Sundial gate: checked against the Sundial tags.

mkdocs build --strict passes locally.

Spotted, not addressed here

• Format version mismatch: app_meta_json.md says the current format version v is 1.2, but shard_core's CURRENT_VERSION is 1.3. This is about the documented format version, so it matters for anyone copying the example.
• Stale digest copy in app-repository: .claude/skills/add-app/reference/freeshard-digest.md still says no minimum_freeshard_version field exists. That is the copy the add-app skill reads, so it will tell agents the wrong thing until someone refreshes it.

🤖 Generated with Claude Code